Debian Python Policy Neil Schemenauer nas@debian.org Matthias Klose doko@debian.org Gregor Hoffleit flight@debian.org version 0.3.7 This document describes the packaging of Python within the Debian GNU/Linux distribution and the policy requirements for packaged Python programs and modules. Copyright © 1999, 2001 Software in the Public Interest

This manual is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is available as /usr/share/common-licences/GPL in the Debian GNU/Linux distribution or on the World Wide Web at .

You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Python Packaging Versions

At any given time, the package python will represent the current default Debian Python version.

The default Debian Python version should alway be the latest stable upstream release that can be integrated in the distribution.

Apart from the default version, legacy versions of Python may be included as well in the distribution, as long as they are needed by other packages, or as long as it seems reasonable to provide them. (Note: For the scope of this document, Python versions are synonymous to feature releases, i.e. Python 2.0 and 2.0.1 are subminor versions of the same Python version 2.0, but Python 2.1 and 2.2 are indeed different versions.)

For any version, the main package must be called pythonX.Y. Names of related packages must include the pythonX.Y part.

Main package

For every Python version provided in the distribution, the package pythonX.Y shall comprise a complete distribution for deployment of Python scripts and applications. The package includes the binary /usr/bin/pythonX.Y and all modules of the upstream Python distribution.

Excluded are any modules that depend on non-required packages, they will be provided in separate packages. Some tools and files for the development of Python modules are split off in a separate package pythonX.Y-dev. Documentation will be provided separately as well.

At any time, exactly one package must contain a binary /usr/bin/python. That package must either be python or a dependency of that package.

Python Interpreter Interpreter Name

Python scripts depending on the default Python version (see ) or not depending on a specific Python version should use python (unversioned) as the interpreter name.

Python scripts that only work with a specific Python version must explicitely use the versioned interpreter name (pythonX.Y).

Interpreter Location

The preferred specification for the Python interpreter is /usr/bin/python or /usr/bin/pythonX.Y.

If a maintainer would like to provide the user with the possibility to override the Debian Python interpreter, he may want to use /usr/bin/env python or /usr/bin/env pythonX.Y.

Module Path

The module search path for Debian has been amended to include a directory tree in /usr/local at the beginning of the path. By default, sys.path is searched in the following order: /usr/local/lib/pythonX.Y/site-packages /usr/local/lib/site-python /usr/lib/pythonX.Y/site-packages /usr/lib/site-python

Note that the use of the site-python directories in Python is depreciated. The directories might be dropped from the path in a future version.

TODO: What about /usr/share/pythonX.Y ?

Documentation

Python documentation is split out in separate packages pythonX.Y-doc. The package python-doc will always provide the documentation for the default Debian Python version.

TODO: Policy for documentation of third party packages.

Packaged Modules 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 default version can take place before without upgrading *all* packages with dependencies on Python.

Packaging Variants

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

Support only the default Python version.

Support a particular version, or some but not all versions of Python available in Debian.

Support all/most versions of python, including the default. Works only for architecture independant python modules.

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!

The source package must declare Build-Depends: pythonX.Y-dev where X.Y is the version used in the Depends.

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

Support a Particular Version(s)

Name your package pythonX.Y-foo (a versioned module package). Make the dependency look like Depends: pythonX.Y It should install modules somewhere inside /usr/lib/pythonX.Y/site-packages/. Any programs included should use #!/usr/bin/pythonX.Y.

The packaged source must declare Build-Depends: pythonX.Y-dev where X.Y is the version used above.

TODO: Describe support for multiple particular versions

Support All/Most Versions (Including Default)

This option is only XXX available for architecture dependent and independent packages. There are two different cases:

Multiple versioned packages

You have binary extensions that must be compiled against particular versions of Python. Create multiple pythonX.Y-foo packages as in . 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.

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)?

DO WE WANT THIS: Some packages, which provide binary Python only, package these modules together in one package (like python-pqueue). They build-depend on all used pythonX.Y-dev packages, and depend on the presence of at least one of the used Python versions installed, e.g. Depends: python1.5 | python2.1 Also, such a package should declare Provides for pythonX.Y-foo for all versions provided by the package.

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.

Dependencies

Packaged modules available for the default Python version as described in in must depend on "python (>= X.Y), python (<< X.Y+1)".

Packaged modules available for one particular version of Python must depend on the corresponding pythonX.Y package instead.

Python Programs Version Independent Programs

Programs that can run with any version of Python should be started with #!/usr/bin/python. They must also specify a dependency on python. You're free to use #!/usr/bin/env python, if you'd like to give the user a chance to override the Debian Python package with a local version.

Version Dependent Programs

Programs which require a specific version of Python must start with #!/usr/bin/pythonX.Y. They must also specify a dependency on pythonX.Y. Again, if you're using #!/usr/bin/env pythonX.Y, please be aware that a user might override the Debian Python package with a local version.

Programs Embedding Python Building Embedded Programs

Programs which embed a Python interpreter must declare a Build-Depends on pythonX.Y-dev.

TODO: Be more verbose. How about versions...

Embedded Python Dependencies

Dependencies for programs linking against the shared Python library will be automatically created by dpkg-shlibdeps.

Interaction with Locally Installed Python Versions

As long as you don't install other versions of Python in your path, Debian's Python versions won't be affected by a new version.

If you install a different subrelease of the version of python you've got installed, you'll need to be careful to install all the modules you use for that version of python too.

Build Dependencies

Build dependencies for Python dependent packages must be declared for every Python version, that the package is built for. To build for a specific version, add the versioned dependencies, to build for the default version, add the unversioned dependency. Architecture dependent packages must depend on the -dev package; for architecture independent packages, it may be sufficient to depend on the python or pythonX.Y package.

Build-Depend on at least: Build-Depends: python1.5 Build-Depends: python2 (>= 2.0.1-1.2) Build-Depends: python2.1 Build-Depends: python2.2 (>= 2.1.99-2) Build-Depends: python1.5-dev (>= 1.5.2-18.6) Build-Depends: python1.5-distutils Build-Depends: python2-dev (>= 2.0.1-1.2) Build-Depends: python2.1-dev (>= 2.1.1-1.4) Build-Depends: python2.2-dev (>= 2.1.99-2)

Upgrade Procedure

This section describes the procedure for the upgrade from the current python-XXX (1.5) packages to the python1.5-XXX packages, the removal of the python2-XXX packages and the upgrade to the recent python2.1-XXX packages:

The Debian Python maintainer decides for the default Debian Python version. In the following we assume that python2.1 will be the default (hint, hint ...).

Serious issues with the python-policy should be resolved, the policy should be submitted to debian-policy.

Upload python core packages python-module (2.1) & Co depending on python2.1-module.

The new packages will conflict with every Python dependent package, that does depend on python, python-base, without depending on python (<< 1.6) or python-base (<< 2.1).

At this point other python modules/packages can be made, which follow the proposed policy. Notify the maintainers of packages, that the new packages conflict with.

We propose to make more than one source package for support of more than one python version. Build 2.1 (and probably 2.2) dependent packages from one source packages, and 1.5 and 2.0 packages from another source package (if you support these versions at all). This makes it easy to remove the old packages from testing/unstable.

XXX Do we allow NMUs which only fix the dependencies?

File bug report against packages and/or make NMU's for packages that are not adapted by their maintainer.

If maintainer A (maintaining python-foo (depending on python (>= 2.1), python (<< 2.2)) decides for , then a maintainer B should be allowed to repackage python1.5-foo, if "his" package cannot be converted to use the default Python version.

File reports that python2.0 should go away, file serious reports against all the python2-* the packages and ftp.debian.org.

Hopefully release woody with python2.1 as the default Python version.