__all__

[Ethan Furman]

Greetings!

Does anyone know/recall the original purpose of __all__?

I had thought it was primarily to specify what would be imported when
`from ... import *` was executed, such as for tk; 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 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 *`.

History lessons, as well as ideas, welcomed!

~Ethan~

 

[Steven D'Aprano]

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.