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

Debian Python Policy
Chapter 2 - Packaged Modules


2.1 Rationale: A different view

A package with a name python-foo will always provide the module foo for the default Debian Python version of the distribution. I.e. the package will extend the function of /usr/bin/python (which is installed by the package python).

The system of dependencies of the default packages is robust against upgrades, but introduces a strong dependency: I.e. an upgrade of the python package will be hold back as long as there are still default modules packages left over on the system that can't be upgraded to the new version.

The versioned packages (legacy versions) ensure that an upgrade to a new version can take place before upgrading *all* packages with dependencies on Python.


2.2 Packaging Variants

There is more than one way to package a Python module:

  1. Support only the default Python version.
  1. Support a particular version, or some but not all versions of Python available in Debian.
  1. Support all/most versions of python, including the default. This variant is still not completely supported.

2.2.1 Support Only The Default Version

Name your package python-foo. This kind of package is called a default module package. Install your modules into /usr/lib/pythonX.Y/site-packages/. Make your package dependency look like

     Depends: python (>= X.Y), python (<< X.Y+1)

Note that this kind of packaging means that your package will trigger a conflict when the default Debian Python version in the distribution is changed, and that you will have to provide a new version as soon as possible, since the package will block the upgrade of python.

You should not make a default, unversioned module package python-foo depend on the versioned Python package pythonX.Y!

If the build process uses distutils and/or binary modules are built, the source package must declare:

     Build-Depends: pythonX.Y-dev

where X.Y is the version used in the Depends. If the packaging process can deal with later versions of python without any changes to the packaging, it can instead declare:

     Build-Depends: python-dev (>= X.Y)

When the default python version is changed, these packages still need to be rebuilt, if modules are installed in a module path specific to the python version.

Any scripts and examples provided in the package should use /usr/bin/python as interpreter.

TODO: Should a python-foo provide pythonX.Y-foo, provided that the Debian policy allows us to create such a mass of virtual packages?


2.2.2 Support one or several Particular Version(s)

For each pythonX.Y version you want to support, name the package pythonX.Y-foo (a versioned module package). Make the dependency look like

     Depends: pythonX.Y

Each of them should install modules somewhere inside /usr/lib/pythonX.Y/site-packages/. Any included scripts and examples should use /usr/bin/pythonX.Y as interpreter.

If necessary, the packaged source must declare

     Build-Depends: pythonX.Y-dev, ...

including all X.Y supported versions.


2.2.3 Support All/Most Versions (Including Default)

This option is recommended for most modules packages. There are two different cases:

  1. Multiple versioned packages

    You have binary extensions that must be compiled against particular versions of Python. Create multiple pythonX.Y-foo packages as in Support one or several Particular Version(s), Section 2.2.2. Also create an empty default package python-foo with

         Depends: python (>= X.Y), python (<< X.Y+1), pythonX.Y-foo
    

    Note that this kind of packaging means that the default package will trigger a conflict when the default Debian Python version in the distribution is changed, and that you will have to provide a new version of your package as soon as possible, since the package will block the upgrade of python.

    The packaged sources Build-Depends must contain all pythonX.Y-dev packages that the module is built for.

  1. A single package for all versions (NOT YET SUPPORTED!)

    You have a version independent Python module. Create a single package python-foo that has a dependency

         Depends: python
    

    It should install modules somewhere inside /usr/lib/python/site-packages/ and use #!/usr/bin/python for programs. The postinst script should create symlinks in all /usr/lib/pythonX.Y/site-packages/ directories that point to its /usr/lib/python/site-packages/ files and compile them.

    NOT YET SUPPORTED: It's errorprone if the package itself supplies these scripts. And the package cannot know when a new upstream Python version is installed. So the pythonX.Y must provide these scripts, which is not yet done.

    The packaged source must declare Build-Depends on one pythonX.Y-dev package. XXX: Or build-depend on each Python version, so that only checked modules are uploaded?

    TODO: Should policy demand that these packages must have a dependency on python (<= X.Y+1)?


2.3 Module Package Names

Python module packages should be named for the primary module provided. The naming convention for a module Foo is python-foo for the package for the default Python version (the default module package). (Packages which include multiple modules may additionally include provides for those modules using the same convention.)

Python module packages packaged for one particular version of Python (versioned modules packages) should be named pythonX.Y-foo.

A module package providing a module for python version, which is not the default python version, must not be named python-foo, it has to be named pythonX.Y-foo.


2.4 Dependencies

Packaged modules available for the default Python version as described in Support Only The Default Version, Section 2.2.1 must depend on "python (>= X.Y), python (<< X.Y+1)". 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.


2.5 Modules Bytecompilation

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 be shipped in the package. Instead, they should be generated at the package post-installation, using e.g.

     PYTHON=python2.3
     if which $PYTHON >/dev/null 2>&1; then
             DIRLIST="/usr/lib/python2.3/site-packages"
             for i in $DIRLIST ; do
                     $PYTHON -E -O /usr/lib/$PYTHON/compileall.py -q $i
                     $PYTHON -E /usr/lib/$PYTHON/compileall.py -q $i
             done
     fi

and removed in the package's pre-removal script, e.g.

     dpkg -L python2.3-somemodule |
             awk '$0~/\.py$/ {print $0"c\n" $0"o"}' |
             xargs rm -f >&2

If you use debhelper, it is a good idea to use dh_python just before dh_installdeb, in which case you must Build-depend on debhelper (>= 4.1.67). It removes undesired files and generates those scripts automatically. It also helps automating the package's dependencies generation, using the ${python:Depends} substitution variable.


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

Debian Python Policy

version 0.3.7.2

Neil Schemenauer nas@debian.org
Matthias Klose doko@debian.org
Gregor Hoffleit flight@debian.org
Josselin Mouette joss@debian.org