[Python-Dev] __docformat__ scope

Edward Loper edloper at gradient.cis.upenn.edu
Thu Apr 22 21:35:49 EDT 2004

Pep 258 [1] specifies that the __docformat__ variable should be used to 
define the markup language used by docstrings in a module.

Recently, I got an RFE for epydoc requesting that a __docformat__ in a 
package's __init__.py apply to the entire package [2].  My first 
reaction was that it was a good idea, but then I remembered a recent 
discussion on python-dev, where there seemed to be a strong sentiment 
that "from __future__ import absolute_import" should *not* have package 
scope [3]; and I wondered if some of the same arguments would go against 
  applying __docformat__ to the entire package.

So...  Should __docformat__ have package scope (with submodules/ 
subpackages possibly overriding it), or should it only apply to the 
actual module that defines it?

Either way, PEP 258 should be updated to reflect the decision.


[1] pep 258 (Docutils Design Specification)

[2] epydoc RFE: __docformat__ for entire packages

[3] http://mail.python.org/pipermail/python-dev/2004-April/044201.html

More information about the Python-Dev mailing list