13

I've already read Can someone explain __all__ in Python? and I understand that it only affects from ... import * statements, but I can't figure out a real use case. Why should I repeat exported names in __all__ (DRY!) when I could simply avoid importing those names in __init__ namespace?

Example:

mypackage/__init__.py

from a import A

mypackage/a.py

A = "A"
A1 = "A1"

mypackage/b.py

B = "B"

And then in python:

>>> from mypackage import *
>>> A
'A'
>>> 
>>> A1
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'A1' is not defined
>>> b
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'b' is not defined

As you can see A is in the namespace but A1 and b are not. Why should I have to define __all__ = ["A"]?

Community
  • 1
  • 1
Zac
  • 2,180
  • 2
  • 23
  • 36

1 Answers1

17

The only time you want to define __all__ in your package's __init__.py is to list the names of "exported" members that you want to export for when a user does:

from package import *

This is documented in 6.4.1. Importing * From a Package

Note: If you don't define an __all__ in your package then the default behaviour is as follows (from the documentation):

If __all__ is not defined, the statement from sound.effects import * does not import all submodules from the package sound.effects into the current namespace; it only ensures that the package sound.effects has been imported (possibly running any initialization code in __init__.py) and then imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by __init__.py. It also includes any submodules of the package that were explicitly loaded by previous import statements. Consider this code:

A "naive" interpretation of this can be:

If you don't define __all__; a from package import * will bring in everything from that package and anything imported in that pacakge's __init__.py.

codeforester
  • 39,467
  • 16
  • 112
  • 140
James Mills
  • 18,669
  • 3
  • 49
  • 62
  • 1
    Look at my example: I didn't use `__all__` but I can show or hide names in `from mypackage import *` anyway. So why using it? – Zac Jun 17 '15 at 10:33
  • 2
    @Zac you can restrict what comes with `*`. In your example it will bring everything. – Peter Wood Jun 17 '15 at 10:36
  • @PeterWood: not everything but only what is imported in `__init__` (updated example in question) – Zac Jun 17 '15 at 12:00
  • "If you don't define `__all__`; a `from package import *` will bring in everything from that package and all subpackages." Not everything but only what is imported in `__init__` – Zac Jun 17 '15 at 12:03
  • 4
    @Zac You may want to initialise the package and need to import identifiers in order to do that. But you may not want to export them with your package. So you can control it using `__all__`. – Peter Wood Jun 17 '15 at 12:35
  • it is discouraged to do this: ``Wildcard imports (from import *) should be avoided`` https://www.python.org/dev/peps/pep-0008/ – ArtificiallyIntelligence Feb 17 '22 at 04:10