packaging-pitfalls.rst

Forgetting to specify package data.

why:	Your package distribution doesn't include static files.
fix:	Create a MANIFEST.in.

Listing few file types in MANIFEST.in, then adding some webfonts - only to find out the release you published on PyPI doesn't include them.

why:	You duplicated information you already have in the filesystem. [1]
fix:	Just recursive-include or graft the whole dir.

Listing few file types in package_data, then adding some webfonts - only to find out the release you published on PyPI doesn't include them.

why:	You duplicated information you already have in the filesystem. [1] You have better options.
fix:	Use MANIFEST.in instead, it's more flexible.

Listing excludes/prunes before includes/grafts.

why:	Last rule wins.
fix:	Use correct rule ordering.

Hardcoding packages list in setup.py.

why:	You duplicated information you already have in the filesystem. [1]
fix:	Use setuptools.find_packages.

Hardcoding py_modules list in setup.py.

why:	You duplicated information you already have in the filesystem. [1]
fix:	Discover the modules, example: py_modules=[splitext(basename(i))[0] for i in glob.glob("src/*.py")].

Importing your package in setup.py.

why:	It's risky. If your package imports dependencies they might now be available and your package becomes uninstallable. pip/easy_install might need to run your ``setup.py` to discover dependencies. [2]
fix:	If you need to extract the version read the file instead and parse out the version.

Importing unavailable tools in setup.py.

why:	They might not be installed at the time setup.py is run.
fix:	Use setup_requires, delay imports - import in your custom command class's methods.

Running code that expects a very specific environment. Example: the infamous from distribute_setup import use_setuptools; use_setuptools() pattern expected superuser privileges in order to upgrade setuptools.

why:	Users can't always have the exact evironment as you have.
fix:	Just import setuptools. Modern python installations, pip and virtualenv already provide setuptools.

[1]	(1, 2, 3, 4) It aint' gonna update itself and you're going to forget to. Happens to the best.

[2]	Except when using wheels or eggs. But you should always upload the sdist (hard to make binary available for every imaginable platform) - which already relies on running setup.py.