Question

It is my understanding that a module docstring should just provide a general description of what a module does and details such as author and version should only be contained in the module’s comments.

However, I have seen the following in comments and docstrings:

__author__ = "..."
__version__ = "..."
__date__ = "..."

Where is the correct location to put items such as these? What other __[name]__ variables are common to list at the top of modules?

Answer 1

They are merely conventions, albeit quite widely-used conventions. See this description of a set of Python metadata requirements.

__version__ is mentioned in the Python Style Guide.

Regarding docstrings, there’s a PEP just for you!

The docstring for a module should
generally list the classes, exceptions
and functions (and any other objects)
that are exported by the module, with
a one-line summary of each. (These
summaries generally give less detail
than the summary line in the object’s
docstring.) The docstring for a
package (i.e., the docstring of the
package’s init.py module) should
also list the modules and subpackages
exported by the package.