Search code examples
pythonsetuptoolsdistutils

pep 420 namespace_packages purpose in setup.py

What is the purpose of the namespace_packages argument in setup.py when working with PEP420 namespace packages (the ones without __init__.py)?

I played with it and saw no difference whether I declared the namespace packages or not. "setup.py install" and "pip install ." worked in any case.

I am building an automatic setup.py code generator and would be happy not to handle this if this is not necessary.

Solution

  • As long as you:

    • aim for Python 3.3 and newer or Python 2.7 with importlib2 dependency installed (a backport of importlib for Python 2),
    • use a recent version of setuptools for packaging (I think it should be 28.8 or newer)
    • and use a recent pip version for installing (9.0 and newer will be fine, 8.1.2 will probably also work, but you should test that yourself),

    you are on the safe side and can safely omit the namespace_packages keyword arg in your setup scripts.

    There is a PyPA's official repository named sample-namespace-packages on GitHub that contains a suite of tests for different possible scenarios of distributions installed that contain namespace packages of each kind. As you can see, the sample packages using the implicit namespace packages don't use namespace_packages arg in their setup scripts (here is one of the scripts) and all of the tests of types pep420 and cross_pep420_pkgutil pass on Python 3; here is the complete results table.