[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ B ] [ C ] [ next ]

Debian Python Policy
Chapter 3 - Packaged Modules

The goal of these policies is to reduce the work necessary for Python transitions. Python modules are internally very dependent on a specific Python version. However, we want to automate recompiling modules when possible, either during the upgrade itself (re-byte-compiling pyc and pyo files) or shortly thereafter with automated rebuilds (to handle C extensions). These policies encourage automated dependency generation and loose version bounds whenever possible.

3.1 Types of Python 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. Some distributions link extensions to libpython, but this is not the case in Debian as symbols might as well be 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 documentation 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 Module Path, Section 2.5. 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.

3.2 Wheels

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 zips 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 tool, in a Debian policy compliant way. The set of packages providing wheels for this purpose are (by source package name): chardet, distlib, html5lib, python-colorama, python-pip, python-setuptools, python-urllib3, requests, and six.

Wheel packages supporting pyvenv and pip are named with the python- prefix, and the -whl suffix, e.g. python-chardet-whl. When these binary packages are installed, their .whl files must be placed in the /usr/share/python-wheels directory. Such wheels must be built with the --universal flag so as to generate wheels compatible with both Python 2 and Python 3.

3.3 Module Package Names

Public 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. Python 3 modules must be in a separate binary package prefixed with python3- to preserve run time separation between python and python3. The binary package for module foo should preferably be named python-foo, if the module name allows, but this is not required if the binary package ships multiple modules. In the latter case the maintainer chooses the name of the module which represents the package the most. For subpackages such as foo.bar, the recommendation is to name the binary packages python-foo.bar and python3-foo.bar. Such a package should support the current Debian Python version, and more if possible (there are several tools to help implement this, see Packaging Tools, Appendix B). For example, if Python 2.5, 2.6, and 2.7 are supported, the Python statement

     import foo

should import the module when the user is running any of /usr/bin/python2.5, /usr/bin/python2.6, and /usr/bin/python2.7. This requirement also applies to extension modules; binaries for all the supported Python versions should be included in a single package.

3.4 Specifying Supported Versions

The optional X-Python-Version (preferred) or XS-Python-Version field in the general paragraph (the first one, for the source package) of debian/control specifies the versions of Python (not versions of Python 3) supported by the source package. Similarly, X-Python3-Version is used to specify the versions of Python 3 supported by the package. When not specified, they default to all currently supported Python (or Python 3) versions. They 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-Python-Version: >= X.Y
     X-Python-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 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 versions and must be ignored for Python 3 versions. Lists of multiple individual versions (e.g. 2.4, 2.5, 2.6) work for XS-Python-Version and will continue to be supported, but are not recommended and are not supported by X-Python-Version or X-Python3-Version 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 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 it's intended purpose of managing Python transitions. This can be adequately accomplished by examining package dependencies.

3.5 Dependencies

Packaged modules available for the default Python version (or many versions including the default) as described in Module Package Names, Section 3.3 must depend on "python (>= X.Y)". If they require other modules to work, they must depend on the corresponding python-foo. They must not depend on any pythonX.Y-foo.

Packaged modules available for one particular version of Python must depend on the corresponding pythonX.Y package instead. If they need other modules, they must depend on the corresponding pythonX.Y-foo packages, and must not depend on any python-foo.

3.6 Provides

Provides in binary packages of the form python-X.Y>foo must be specified if the package contains an extension for more than one python version and an other package with version specific dependencies on the package require it. Provides are only for extensions, not modules. Provides should only be rarely used for Python packages and never for Python 3.

3.7 Modules Byte-Compilation

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 postinst, and removed in the package's prerm. 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 postinst 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.