The most common way to distribute Python modules is using PyPI, the Python Package Index (formerly known as the Cheese shop).
The tool to download and install packages is pip. Predecessors like EasyInstall are no longer recommended, with only a few exceptions (in particular pip does not support binary distributions).
There are tool to build and upload packages is or setuptools. Make sure to use version 0.7 or later.
There are a few alternatives to setuptools: distutils is a tool in the standard library with limited functionality. The downside of both distutils and setuptools is that they use a script rather than a file format to store metadata, and force the developer an end-user to use the same tool to build and install the software. distutils2 (the module will be named `package`) is an attempt to move to a modern packaging system for Python, but has not been included as of Python 3.4.
Credit: These steps are based on the sphinxcontrib-aafig documentation.
In order to make a PyPi release, do the following steps:
- Make sure the repository is up-to date.
- Ensure the version is incremented:
setup.pymust be updated
libary/__init__.pymust be updated
doc/changes.rstmust contain a summary of the changes
- Make sure all changes are committed, including the version number changes.
- Tag the sources with
hg tag -m 'Tag mymodule-X.Y' mymodule-X.Yor
git tag mymodule-X.Y.
- Push the code and tag:
git push --tags origin
- Temporarily modify
setup.cfgfile to comment out the variables
tag_build = devand
tag_date = true(do not commit this change).
- Register and upload the new release
python setup.py register sdist upload.
- Generate the documentation with
cd doc; make.
- Upload the new documentation (to PyPi or to github mypackage.wiki repository).
Package and Egg Loading Trickery
Python has a rather poor system of loading modules. Tools such as setuptools work around this problem, but sometimes these workarounds have unintended consequences.
import sphinxcontrib.restbuilderalways loaded this package from site-packages directory, despite that the
sphinxcontrib.restbuildermodule was also available in the current directory, and
sys.pathcontained the current directory as first entry.
- easy-install 'only' modifies
$PYTHONPATH). setuptools takes it a step further and creates a
.pth<code> file that manipulates <code>sys.modules.
First of all: Python eggs are a neat way to distribute different software packages inside the same Python package. Consider the following two directory structures:
site-packages/ sphinxcontrib/ blockdiag/ restbuilder/ swf/
site-packages/ sphinxcontrib-blockdiag-1.2.egg sphinxcontrib/ blockdiag/ sphinxcontrib-restbuilder-0.1.egg sphinxcontrib/ restbuilder/ sphinxcontrib-swf-0.3.egg sphinxcontrib/ swf/
The second directory structure allows separate release cycles for all three packages. The downside is that all
*.egg directories need to be included in
import sys, types, os p = os.path.join(sys._getframe(1).f_locals['sitedir'], 'sphinxcontrib') if os.path.exists(os.path.join(p,'__init__.py')): mp =  else: m = sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib')) mp = m.__dict__.setdefault('__path__',) if (p not in mp): mp.append(p)
- Python Packaging: Hate, hate, hate everywhere by Armin Ronacher gives some background on the different tools (easy-install, setuptools, and pip).
- Python site module, which is responsible for defining
sys.path, and executing the
.pthfiles during Python boot time.