Idiomatic file level comments in Python?

Question

When I need to write extensive comments about functions, I use docstrings. However, I'm not sure what the equivalent for file level comments is in Python, and whether it differs for modules vs scripts.

Is it common to use this style?

"""
file.py: module for X
Detailed information...
"""

import x

def foo(bar):
  return 42

Or perhaps this?

# file.py: module for X
# More info...

import x
# ...

Any thoughts?

Answer 1

Always use a string, since that will actually populate the __doc__ variable of the current file / module.

Compare this:

'''Hello World'''
print(__doc__)

to

# Hello World
print(__doc__)

Consider this is in a module foo.py and compare the output off:

>>> import foo
>>> help(foo)

You also do not need to add the "file: ..." part, since python displays that automatically.