__all__

[Steven D'Aprano]

Ethan Furman wrote:

> Greetings!
> 
> Does anyone know/recall the original purpose of __all__?

To customise the names available for `from ... import *`:

http://docs.python.org/whatsnew/2.1.html#other-changes-and-fixes


> I had thought it was primarily to specify what would be imported when
> `from ... import *` was executed, such as for tk;  

Yes, that was the original use. If __all__ is not defined, Python will
import everything that doesn't start with an underscore.


> today, it seems it is 
> also used to specify the API for the module, and so the help() subsystem
> will only provide details for those items found in __all__.

The two meanings are assumed to be synonymous: names in the public API
should be importable with *, and importable names should be in the public
API. You can't specify "this can be imported with *, but isn't public"
or "this is public, but not importable with *".

http://docs.python.org/reference/simple_stmts.html#index-1090


Also, the behaviour of __all__ with packages may be slightly different:

http://docs.python.org/tutorial/modules.html#index-1134

 
> The issue I'm having with this is that there are roughly a dozen items I
> would like to make available via the `import *` mechanism in my dbf
> module, and another dozen that, while part of the public API, don't need
> to be available via an `import *`.

You have to choose both, or neither, but you can't have just one.



-- 
Steven