I have been using Python more and more, and I keep seeing the variable __all__
set in different __init__.py
files. Can someone explain what this d
__all__
is used to document the public API of a Python module. Although it is optional, __all__
should be used.
Here is the relevant excerpt from the Python language reference:
The public names defined by a module are determined by checking the module’s namespace for a variable named
__all__
; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in__all__
are all considered public and are required to exist. If__all__
is not defined, the set of public names includes all names found in the module’s namespace which do not begin with an underscore character ('_').__all__
should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module).
PEP 8 uses similar wording, although it also makes it clear that imported names are not part of the public API when __all__
is absent:
To better support introspection, modules should explicitly declare the names in their public API using the
__all__
attribute. Setting__all__
to an empty list indicates that the module has no public API.[...]
Imported names should always be considered an implementation detail. Other modules must not rely on indirect access to such imported names unless they are an explicitly documented part of the containing module's API, such as
os.path
or a package's__init__
module that exposes functionality from submodules.
Furthermore, as pointed out in other answers, __all__
is used to enable wildcard importing for packages:
The import statement uses the following convention: if a package’s
__init__.py
code defines a list named__all__
, it is taken to be the list of module names that should be imported whenfrom package import *
is encountered.
It's a list of public objects of that module, as interpreted by import *
. It overrides the default of hiding everything that begins with an underscore.
__all__
affects how from foo import *
works.
Code that is inside a module body (but not in the body of a function or class) may use an asterisk (*
) in a from
statement:
from foo import *
The *
requests that all attributes of module foo
(except those beginning with underscores) be bound as global variables in the importing module. When foo
has an attribute __all__
, the attribute's value is the list of the names that are bound by this type of from
statement.
If foo
is a package and its __init__.py
defines a list named __all__
, it is taken to be the list of submodule names that should be imported when from foo import *
is encountered. If __all__
is not defined, the statement from foo import *
imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by __init__.py
.
Note that __all__
doesn't have to be a list. As per the documentation on the import statement, if defined, __all__
must be a sequence of strings which are names defined or imported by the module. So you may as well use a tuple to save some memory and CPU cycles. Just don't forget a comma in case the module defines a single public name:
__all__ = ('some_name',)
See also Why is “import *” bad?
It also changes what pydoc will show:
module1.py
a = "A"
b = "B"
c = "C"
module2.py
__all__ = ['a', 'b']
a = "A"
b = "B"
c = "C"
$ pydoc module1
Help on module module1: NAME module1 FILE module1.py DATA a = 'A' b = 'B' c = 'C'
$ pydoc module2
Help on module module2: NAME module2 FILE module2.py DATA __all__ = ['a', 'b'] a = 'A' b = 'B'
I declare __all__
in all my modules, as well as underscore internal details, these really help when using things you've never used before in live interpreter sessions.
From (An Unofficial) Python Reference Wiki:
The public names defined by a module are determined by checking the module's namespace for a variable named
__all__
; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in__all__
are all considered public and are required to exist. If__all__
is not defined, the set of public names includes all names found in the module's namespace which do not begin with an underscore character ("_").__all__
should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module).