[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