views:

89

answers:

4

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 locations to put items such as these? What other __[name]__ variables are common to list at the top of modules?

+1  A: 

I would suggest not to worry about __author__, __version__, etc. Those attributes are handled by any decent version control system anyway. Only add them if you need to have that information on a production system, where the source code has already been exported out of the version control system.

Gintautas Miliauskas
But PEP 8 says, that: If you have to have Subversion, CVS, or RCS crud in your source file, do it as follows.__version__ = "$Revision: 84354 $"# $Source$These lines should be included after the module's docstring, before any other code, separated by a blank line above and below.
Max
+2  A: 

You could have a look at:

Bruno
AA! You have just stolen my answer! :)
Max
+5  A: 

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.

katrielalex
+1  A: 

Google can list many for you

THC4k