Packaging Python modules and applications¶
Our packaging follows Debian’s Python policy. We will use python-markdown package as an example, which can be downloaded from PyPI. You can look at its packaging at its Subversion repository.
There are two types of Python packages — modules and apps.
At the moment of writing this, Ubuntu has two incompatible versions of Python — 2.x and 3.x. /usr/bin/python is a symbolic link to a default Python 2.x version, and /usr/bin/python3 — to a default Python 2.x version. Python modules should be built against all supported Python versions.
If you are going to package a new Python module, you can find py2dsc tool useful (available in python-stdeb package).
debian/control¶
Python 2.x and 3.x versions of the package should be in separate binary packages. Names should have python{,3}-modulename format (like: python3-dbus.mainloop.qt). Here, we will use python-markdown and python3-markdown for module packages and python-markdown-doc for the documentation package.
Things in debian/control that are specific for a Python package:
Section of module packages should be python, of the documentation package — doc. For an application, a single binary package will be enough.
We should add build dependencies on python-all (>= 2.6.6-3~) and python3-all (>= 3.1.2-7~) to make sure Python helpers are available (see the next section for details).
It’s recommended to add X-Python-Version and X-Python3-Version fields — see “Specifying Supported Versions” section of the Policy for details. For example:
X-Python-Version: >= 2.6 X-Python3-Version: >= 3.1
If your package works only with Python 2.x or 3.x, build depend only on one -all package and use only one -Version field.
Module packages should have {python:Depends} and {python3:Depends} substitution variables (respectively) in their dependency lists.
debian/rules¶
The recommended helpers for python modules are dh_python2 and dh_python3. Unfortunately, debhelper doesn’t yet build Python 3.x packages automatically (see bug 597105 in Debian BTS), so we’ll need to do that manually in override sections (skip this if your package doesn’t support Python 3.x).
Here’s our debian/rules file (with annotations):
# This command builds the list of supported Python 3 versions
PYTHON3=$(shell py3versions -r)
%:
# Adding the required helpers
dh $@ --with python2,python3
override_dh_auto_clean:
dh_auto_clean
rm -rf build/
override_dh_auto_build:
# Build for each Python 3 version
set -ex; for python in $(PYTHON3); do \
$$python setup.py build; \
done
dh_auto_build
override_dh_auto_install:
# The same for install; note the --install-layout=deb option
set -ex; for python in $(PYTHON3); do \
$$python setup.py install --install-layout=deb --root=debian/tmp; \
done
dh_auto_install
It is also a good practice to run tests during the build, if they are shipped by upstream. Usually tests can be invoked using setup.py test or setup.py check.
debian/*.install¶
Python 2.x modules are installed into /usr/share/pyshared/ directory, and symbolic links are created /usr/lib/python2.x/dist-packages/ for every interpreter version, while Python 3.x ones are all installed into /usr/lib/python3/dist-packages/.
If your package is an application and has private Python modules, they should be installed in /usr/share/module, or /usr/lib/module if the modules are architecture-dependent (e.g. extensions) (see “Programs Shipping Private Modules” section of the Policy).
So, our python-markdown.install file will look like this (we’ll also want to install a markdown_py executable):
usr/lib/python2.*/
usr/bin/
and python3-markdown.install will only have one line:
usr/lib/python3/
The -doc package¶
Tool that is most commonly used for building Python docs is Sphinx. To add Sphinx documentation to your package (using dh_sphinxdoc helper), you should:
- Add build-dependency on python-sphinx or python3-sphinx package (depending on what Python version do you want to use);
- Append sphinxdoc to dh --with line;
- Run setup.py build_sphinx in override_dh_auto_build (sometimes not needed);
- Add {sphinxdoc:Depends} to dependency list of your -doc package;
- Add path to built docs directory (usually build/sphinx/html) to your .docs file.
In our case, docs are automatically built in build/docs/ directory (when we run setup.py build), so we can simply put this in the python-markdown-doc.docs file:
build/docs/
Because docs also contain source .txt files, we’ll also tell dh_compress to not compress them — and add this to debian/rules:
override_dh_compress:
dh_compress -X.txt
Checking for packaging mistakes¶
Along with lintian, there is a special tool for checking Python packages — lintian4py. It is available in lintian4python package. For example, this command invokes both lintian and lintian4py and checks source and binary packages:
lintian{,4py} -EI --pedantic *.dsc *.deb
Here, -EI option is used to enable experimental and informational tags.
See also¶
- The Python policy;
- Python/Packaging article on Debian wiki;
- Python/LibraryStyleGuide and Python/AppStyleGuide articles on Debian wiki;
- Debian python-modules and python-apps teams.