[Doc-SIG] __all__, and how it relates to doc tools
Tim Peters
tim.one@home.com
Sun, 15 Apr 2001 03:14:50 -0400
[Edward D. Loper]
> I was looking through the changes made in Python 2.1, and noticed
> the "__all__" variable in modules. My understanding is that, when
> defined, this lists all of the variables that will be imported
> when you do "from xyz import *".
Correct! That's it's only enforced semantics. More generally, it's meant to
identify which names a module intends to export regardless of means, and in
that larger sense it's more of a doc gimmick than a language feature.
> Would it also be reasonable for a doc tool to look at this value, for
> an indication of which objects to document?
Absolutely. In fact, that's probably the best use.
> ...
> And you'd probably want tools to have a flag that tells them to
> ignore the __all__ variable.
I wouldn't: if a module lies about what it intends to export, that's a bug
in the module.
> ...
> Also, would it be reasonable to only document the fields of a
> class listed in an __all__ class variable, if such a variable is
> defined?
__all__ was a marginal idea even at the module level; I'd prefer not to see
it spread. The practical problem at the module level was that
import xyz
also acts as an export of xyz (from "import *"'s POV), and usually an
unintended export. There's no such problem at the class level.