[Doc-SIG] __all__, and how it relates to doc tools

Edward D. Loper edloper@gradient.cis.upenn.edu
Sun, 15 Apr 2001 03:53:32 EDT


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

My guess is that most people won't put "private" functions/classes/
etc. in the __all__ list, but it still may be useful for a doc tool to
be able to process the docstrings of the "private" objects..  This is
similar to including a flag saying whether a doc tool should process
private objects (ones starting with "_" or "__")..

> __all__ was a marginal idea even at the module level; I'd prefer not
> to see it spread.

Ok.

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

I would be surprised if people don't also use it to hide "private"
objects.  Is this something we want to discourage?  (Of course, 
"private" objects are probably named with a _leading_backslash, and
my understanding is that "from xyz import *" won't import such
objects if __all__ is undefined.. so perhaps the question is moot..)

Incidentally, if __all__ is defined, and it includes objects that
begin with a "_", do those get imported (in "from xyz import *")?  Or
does the general rule that objects starting with "_" don't get
imported override that?  (I haven't had a chance to grab 2.1 and play
with it yet..)

-Edward