[Python-Dev] __docformat__ scope

[Edward Loper]

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.

-Edward

[1] pep 258 (Docutils Design Specification)
     http://www.python.org/peps/pep-0258.html

[2] epydoc RFE: __docformat__ for entire packages
 
http://sourceforge.net/tracker/index.php?func=detail&aid=928058&group_id=32455&atid=405621

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