Module Level __magic__ Variables
10 PM
September 18, 2003
Getting ready to dress up a Python module for release, I got to asking myself which __magic__ variable names the module should declare. Some of these are part of the language, while others are defined by convention. There are more than a handful and they don't seem to be documented in one place anywhere on the web, so I made a list for future reference.
Unless otherwise noted, this information is cribbed from the Modules entry of the Language Reference.
__name__- A String. The name the module. This is typically the name you used to refer to the module in the
import statement.
__doc__- A String. The docstring. Just like a function or class docstring, it may be defined by placing a string as the first statement in the module. PEPs 257 and 258 have plenty of good info on docstring conventions and processing.
__file__- A String. The name of the file from which the module was imported - it will have a .pyc, .pyd, .so or .dll extension.
__dict__- A read-only dictionary, keyed by String. The module global dictionary.
__all__- Set to a "sequence of strings". When an import statement of the form
from module import * is executed, the public names defined in module are imported. If it exists, the __all__ variable defines the public names, otherwise the public names are all the ones without a leading underscore.
__version__- String. PEP-8 defines this as the place to put revision control system version numbers; for example:
__version__ = "$Revision: 1.18 $". The ever-amazing pydoc module / script / search-engine / webserver processes this variable specially.
__date__- String. The date of the code. Special processing by pydoc. I could not find any comment on the semantics of this one, though I would expect the __date__ and __revision__ to be kept in step.
__author__- String. The name(s) of each author. Special processing by pydoc.
__credits__- String. Public credits and kudos. Special processing by pydoc. The March 2001 email thread where Guido first noticed then blessed the new
__author__ and __credits__ variables starts here.
Comments
Very useful -- I too found it very difficult finding any guidance on __magic__ attributes for modules.
It's worth noting that some of them (__name__, __file__, __dict__) are automagically created on import and shouldn't be set explicitly in the module code.
__doc__ is semi-automagic -- if it's not explicitly set, it is set on import to the first string in the module. (FWIW, I usually set __doc__ explicitly in my modules; it seems clearer to me to do so than to rely on magic. In scripts, I often use __doc__ as the usage text if a -h or --help argument is passed.)
The rest are not magic and seem the ones most subject to unspoken convention -- and out of interest, what special processing does pydoc do on them? The pydoc section in the Library Reference doesn't say.
PEP258 suggests that __all__ has meaning to docstring extraction, and thus to doc generation, as well as to "from module import *" -- if __all__ is defined, only the identifiers listed in it are examined for docstrings.
I also couldn't find anything on what format __author__ should have. In scripts I write for work, I set it to the author's email address, and have a custom exception handler email detailed exception reports (tracebacks+frame locals, environment etc) to the author. It's found me a few bugs in its time, and also makes me look omniscient when I can send a "you're using it wrong; do this, this, and this and it'll work" email to a user before he comes to me...
Finally, one typo -- I suspect the description of __date__ should be expecting __date__ and __version__, not __revision__, to be kept in step...
__path__ is missing in your list: it is only present on packages.
And if the module was imported by a new import hook (zipimport, for example, see PEP 302), __loader__ will also be set.
Does anyone use s.th. like __copyrightBy__ and __license__ or are magic variables a bad way of stating legal aspects?
Bud - usually I see that information in docstrings or a big comment block near the top of the module.
I think that systems like 'epydoc' with its own epytext system (and the ability to use reStructuredText) allow you to mark up your doc strings in a way that they could contain structured information that doesn't fill the module with funky variables. Then when the documentation is generated, those can stand out more clearly while also remaining part of the general prose.
That's just what I've seen.
In a related note, epydoc and docutils both promote use of __docformat__ so that a documentation tool can try to render document content.
http://epydoc.sourceforge.net/othermarkup.html
http://www.python.org/peps/pep-0258.html#choice-of-docstring-format
as far as my work and our in-house doc generitaor go, we use the __copyright__ in all our modules and __license__ in all root package modules/scripts that go public (e.g. __init__.py and version.py ... etc.). plus, if the module is written by more than one person there are the list attribute __contributors__ and/or str or list attribute __authors__.
Re: Bud's question -- I think the acid test here is "are there any programmatic uses for these __magic__ variables"?
For me, __author__ and __version__ are both useful things to introspect for (when generating exception reports, for example), so I'll happily use them.
Licence and copyright info doesn't seem to me to be terribly useful at runtime -- unless like Alex you use a doc generator which treats it specially -- so I stick it into comments.
Another thing to note is that when optimization is turned on, __doc__ is not automatically defined. Docstrings are disregarded.
I don't know if this also applies to any of the other magic variables, so for optimization's sake it is better to use an implicit docstring rather than a __doc__ assignment.
About the license and copyright issues, I imagine that they would be best in the docstring for the module. Probably as a reference to another file with the applicable information.
Great site guys... Keep up the good work :)
For __dict__: "A read-only dictionary, keyed by String. The module global dictionary."
... should be "this read-only attribute is a dict, the module global dictionary". The dictionary itself is not read-only (also, you *can* put keys in there which are not strings, but you'll get slower performance of the dict from then on).