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

[Tim Peters]

[Edward D. Loper]
> 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 "__")..

It's useful for a doc tool to have a notion of public and private class
attributes, but naming conventions already exist to make those distinctions.
It would be unPythonic to introduce another mechanism to do the same thing.

> ...
> I would be surprised if people don't also use it to hide "private"
> objects.  Is this something we want to discourage?

Yes:  the convention for module-private names has always been to begin them
with an underscore.  It wasn't the intent of __all__ to throw that rule away;
although, frankly, I've never been clear on exactly why __all__ *was* added.
The addition of "import name as _name" syntax made it convenient enough to do
"non-exporting imports", as far as I was concerned.

> ...
> Incidentally, if __all__ is defined, and it includes objects that
> begin with a "_", do those get imported (in "from xyz import *")?

Yes, if an __all__ list is present, import* imports exactly the names it
contains.