Table of Contents
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-bytecompiling 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.
There are two kinds of Python modules, "pure" Python modules, and extension modules. Pure Python modules are Python source code that works across many versions of Python. Extensions are C code compiled and linked against a specific version of the libpython library, and so can only be used by one version of Python.
Python packages are directories containing at least a
__init__.py
, other modules, extensions and
packages (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 one of the directories listed
in Section 1.4, “Module Path”. They are accessible to any
program. Private modules are installed in a directory such
as /usr/share/
or packagename
/usr/lib/
. They are
generally only accessible to a specific program or suite of
programs included in the same package.
packagename
Public modules should be packaged with a name
of python-
,
where foo
foo
is the name of the module. 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 2.3, 2.4, and 2.5 are supported, the
Python command
import foo
should import the module when the user is running any
of /usr/bin/python2.3
, /usr/bin/python2.4
,
and /usr/bin/python2.5
. This requirement also
applies to extension modules; binaries for all the supported
Python versions should be included in a single package.
The XS-Python-Version
field
in debian/control
specifies the versions of
Python supported by the package. This is used to track
packages during Python transitions, and is also used by some
packaging scripts to automatically generate appropriate
Depends and Provides lines. The format of the field may be
one of the following:
XS-Python-Version: all XS-Python-Version: current XS-Python-Version: current, >= X.Y XS-Python-Version: >= X.Y XS-Python-Version: >= A.B, << X.Y XS-Python-Version: A.B, X.Y
Where "all" means the package supports any Python version available, and "current" means it supports Debian's current Python version. Explicit Versions or version ranges can also be used.
Your control file should also have a line:
XB-Python-Version: ${python:Versions}
The python:Versions is substituted by the supported Python
versions of the binary package, based on
XS-Python-Version
. (If you are not using
dh_python
you will need to handle this
substitution yourself.) The format of the field
XB-Python-Version
is the same as the
XS-Python-Version
field for packages not containing
extensions. Packages with extensions must list the versions
explicitely.
If your package is used by another module or application
that requires a specific Python version, it should also
Provide: python
for
each version it supports.
X
.Y
-foo
Packaged modules available for the default Python version
(or many versions including the default) as described
in Section 2.2, “Module Package Names” must depend on "python
(>=
)". If they
require other modules to work, they must depend on the
corresponding X
.Y
python-foo
. They must not
depend on
any python
.
X
.Y
-foo
Packaged modules available for one particular version of Python must
depend on the corresponding
python
package instead.
If they need other modules, they must depend on the corresponding
X
.Y
python
packages, and
must not depend on any X
.Y
-foopython-foo
.
Provides in packages of the form
python-
must be specified,
if the package contains an extension for more than one
python version. Provides should also be added on request of
maintainers who depend on a non-default python version.
foo
Packaged modules available for one particular version of Python must
depend on the corresponding
python
package instead.
If they need other modules, they must depend on the corresponding
X
.Y
python
packages, and
must not depend on any X
.Y
-foopython-foo
.
If a package provides any binary-independent modules
(foo.py
files), the corresponding bytecompiled
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 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.
Modules in private installation directories and in
/usr/lib/site-python
should be byte-compiled,
when the default python version changes.