Chapter 3. Packaged Modules

There are two kinds of Python modules, "pure" Python modules, and extension modules. Pure Python modules are Python source code that generally works across many versions of Python. Extensions are C code compiled and linked against a specific version of the Python runtime, and so can only be used by one version of Python.

Debian Python does not link extensions to libpython (as is done in some operating systems). Symbols are resolved by /usr/bin/pythonX.Y which is not linked to libpython.

Python packages are a way of structuring Python’s module namespace by using “dotted module names”. See Python's glossary for details on how packages are defined in Python terms (a package in the Python sense is unrelated to a Debian package). Python packages must be packaged into the same directory (as done by upstream). Splitting components of a package across directories changes the import order and may confuse documentation tools and IDEs.

There are two ways to distribute Python modules. Public modules are installed in a public directory as listed in Section 2.5, “Module Path”. They are accessible to any program. Private modules are installed in a private directory such as /usr/share/package-name or /usr/lib/package-name. They are generally only accessible to a specific program or suite of programs included in the same package.

PEP 427 defines a built-package format called "wheels", which is a Zip format archive containing Python code and a *.dist-info metadata directory, in a single file named with the .whl suffix. As Zip files, wheels containing pure Python can be put on sys.path and modules in the wheel can be imported directly by Python's import statement. (Importing extension modules from wheels is not yet supported as of Python 3.4.)

Except as described below, packages must not build or provide wheels. They are redundant to the established way of providing Python libraries to Debian users, take no advantage of distro-based tools, and are less convenient to use. E.g. they must be explicitly added to sys.path, cannot be easily grepped, and stack traces through Zip files are more difficult to debug.

A very limited set of wheel packages are available in the archive, but these support the narrow purpose of enabling the pip, virtualenv, and pyvenv tools in a Debian policy compliant way. These packages build their own dependent wheels through the use of the dirtbike "rewheeling" tool, which takes installed Debian packages and turns them back into wheels. Only universal wheels (i.e. pure-Python, Python 3 and 2 compatible packages) are supported. Since only the programs that require wheels need build them, only they may provide -whl packages, e.g. python3-pip-whl.

When these binary packages are installed, *.whl files must be placed in the /usr/share/python-wheels directory. The location inside a virtual environment will be rooted in the virtual environment, instead of /usr.

Public Python modules must be packages separately by major Python version, to preserve run time separation between Python 2 and Python 3.

Public Python 3 modules used by other packages must have their binary package name prefixed with python3-. Public Python 2 modules used by other packages must have their binary package name prefixed with python-. It is recommended to use this prefix for all packages with public modules as they may be used by other packages in the future.

The binary package for module foo should preferably be named python3-foo (for Python 3) or python-foo (for Python 2), if the module name allows. This is not required if the binary package installs multiple modules, in which case the maintainer shall choose the name of the module which best represents the package.

For subpackages such as foo.bar, the recommendation is to name the binary package python3-foo.bar (for Python 3) or python-foo.bar (for Python 2).

Such a package should support the current Debian Python version, and more if possible (there are several tools to help implement this, see Appendix B, Packaging Tools). For example, if Python 3.3, 3.4, and 3.5 are supported, the Python statement

import foo
	  

should import the module when the program interpreter is any of /usr/bin/python3.3, /usr/bin/python3.4, and /usr/bin/python3.5. This requirement also applies to extension modules; binaries for all the supported Python versions should be included in a single package.

Packages intended for use with Django (python3-django/ python-django) are installed in the same namespace as other python packages for a variety of reasons. Many such packages are named django_$name upstream. These are then packaged as python3-django-$name and python-django-$name. This makes it clear that they are intended for use with Django and not general purpose Python modules. Debian maintainers are encouraged to work with their upstreams to support consistent use of this approach.

The debian/control source paragraph may contain optional fields to specify the versions of Python the package supports.

The optional X-Python3-Version field specifies the versions of Python 3 supported. When not specified, it defaults to all currently supported Python 3 versions.

Similarly, the optional fields X-Python-Version or XS-Python-Version were used to specify the versions of Python 2 supported by the source package. They are obsolete and can be removed now that only Python 2.7 is supported.

These fields are used by some packaging scripts to automatically generate appropriate Depends and Provides lines. The format of the field may be one of the following:

X-Python3-Version: >= X.Y
X-Python3-Version: >= A.B, << X.Y
XS-Python-Version: A.B, X.Y
XS-Python-Version: all
	  

The keyword all means that the package supports any Python 2 version available but might be deprecated in the future since using version numbers is clearer than all and encodes more information. The keyword all is limited to Python 2 versions and must be ignored for Python 3 versions.

A comma-separated list of multiple individual versions (e.g. 3.3, 3.4, 3.5) in XS-Python-Version will continue to be supported, but is not recommended. The use of multiple individual versions in X-Python-Version or X-Python3-Version is not supported for Wheezy and later releases.

The keyword current has been deprecated and used to mean that the package would only have to support a single Python 2 version (even across default version changes). It must be ignored for Python 3 versions.

The use of XB-Python-Version in the binary package paragraphs of debian/control file has been deprecated and should be removed in the normal course of package updates. It never achieved sufficient deployment to support its intended purpose of managing Python transitions. This purpose can be adequately accomplished by examining package dependencies.

Any package that installs modules for the default Python version (or many versions including the default) as described in Section 3.3, “Module Package Names”, must declare a dependency on the default Python runtime package. If it requires other modules to work, the package must declare dependencies on the corresponding packaged modules. The package must not declare dependency on any version-specific Python runtime or module package.

For Python 3, the correct dependencies are Depends: python3 (>= 3.Y) and any corresponding python3-foo packages.

For Python 2, the correct dependencies are Depends: python (>= 2.Y) and any corresponding python-foo packages.

Any package that installs Python modules or Python 3 binary extensions must also declare a maximum version it supports as currently built. This is accomplished by declaring a maximum version constraint strictly less than one higher than the current maximum version, i.e. Depends: python3 (<< X.Y).

Binary packages that declare Provides dependencies of the form pythonX.Y-foo were never supported for Python 3 and are no longer useful for Python 2. They should be removed in the normal course of package updates. Future provision of values for the substituation variable python:Provides is not guaranteed.

If a binary package provides any binary-independent modules (foo.py files), the corresponding byte-compiled modules (foo.pyc files) and optimized modules (foo.pyo files) must not ship in the package. Instead, they should be generated in the package's post-install script, and removed in the package's pre-remove script. The package's prerm has to make sure that both foo.pyc and foo.pyo are removed.

A binary package should only byte-compile the files which belong to the package.

The file /etc/python/debian_config allows configuration how modules should be byte-compiled. The post-install scripts should respect these settings.

Pure Python modules in private installation directories that are byte-compiled with the default Python version must be forcefully byte-compiled again when the default Python version changes.

Public Python extensions should be bin-NMUed.

Private Python extensions should be subject to binary NMUs every time the default interpreter changes, unless the extension is updated through a *.rtupdate script.