[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.