Debian Python policy & Upgrade Path (draft/proposal) [0.3.3]
A revised version:
- Included Donovan's proposals. Note that I left the paragraph
about the "latest stable version", so that Gregor can't escape
so easyly ;-)
- Recommend /usr/bin/env python over /usr/bin/python
- Add chapter of other python versions installed on the system
(Anthony's and Neil's comments).
- Restructured chapter "Packaging Modules", new point, how the binary
module could be packaged (like python-pqueue now).
- Updated the upgrade path to the state of the current packages in
unstable (and for uploading the packages in
http://ftp-master.debian.org/~doko/python/).
Debian Python Policy
--------------------
Neil Schemenauer <nas@debian.org>
Matthias Klose <doko@debian.org>
version 0.3.3
-------------------------------------------------------------------------------
Abstract
--------
This document describes the packaging of Python within the Debian
GNU/Linux distribution and the policy requirements for packaged Python
programs and modules.
Copyright Notice
----------------
Copyright (C) 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 The GNU Public Licence
(http://www.gnu.org/copyleft/gpl.html).
You can also obtain it by writing to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-------------------------------------------------------------------------------
Contents
--------
1. Python Packaging
1.1. Stable and Legacy Versions
1.2. Base Package
1.3. Module Path
1.4. Documentation
2. Packaged Modules
2.1. Packaging Variants
2.1.1. Support Only The Default Version
2.1.2. Support a Particular Version(s)
2.1.3. Support All/Most Versions (Including Default)
2.2. Module Package Names
2.3. Dependencies
3. Python Programs
3.1. Version Independant Programs
3.2. Version Dependant Programs
4. Programs Embedding Python
4.1. Building Embedded Programs
4.2. Embedded Python Dependencies
5. Interaction with Locally Installed Python Versions
A. Upgrade Procedure
-------------------------------------------------------------------------------
1. Python Packaging
-------------------
1.1. Stable and Legacy Versions
-------------------------------
There can be any number of Python packages available. These must be
named `python<X>.<Y>-base' and include the file
`/usr/bin/python<X>.<Y>', where <X> and <Y> represent the major and
minor versions of the Python, respectively.
At any given time, the package `python-base' should establish one of
these packaged versions of Python as the default Debian Python. The
`python-base' package must depend on the default `python<X>.<Y>-base',
and provide a symlink `/usr/bin/python' to the default
`/usr/bin/python<X>.<Y>' binary.
At any given time, the package `python-base' should represent the
latest stable upstream version of Python, that Debian is able to get
into the release.
1.2. Base Package
-----------------
In order to provide a minimal installation of Python for use by
applications without requiring the whole of Python to be installed,
the `python-base' package contains the binary and a basic set of
modules.
1.3. Module Path
----------------
Python searches three different locations for modules. The module
search path for Debian has been ordered to include these locations at
the beginning of the path in the following order:
/usr/local/lib/python<X>.<Y>/site-packages
/usr/local/lib/site-python
/usr/lib/python<X>.<Y>/site-packages
1.4. Documentation
------------------
Python documentation is split out in separate packages
`python<X>.<Y>-doc'. The package `python-doc' depends on the
`python<X>.<Y>-doc' (the documentation of the current stable upstream
version of Python.
TODO: Policy for documentation of third party packages.
-------------------------------------------------------------------------------
2. Packaged Modules
-------------------
2.1. Packaging Variants
-----------------------
There is more than one way to package a Python module:
1. Support only the default version.
2. Support a particular version, or some but not all versions of
Python available in Debian.
3. Support all/most versions of python, including the default.
Works only for architecture independant python modules.
2.1.1. Support Only The Default Version
---------------------------------------
Name your package `python-foo' (for a library). Make your package
dependy look like
Depends: python-base (>= X.Y), python-base (<< X.Y+1)
Install your modules into `/usr/lib/python<X>.<Y>/'. Note that this
means your package will break when `python-base' is upgraded, and will
not work for even old versions of `python<X>.<Y>-base'.
The packaged source must declare a `Build-Depends' on
`python<X>.<Y>-dev', where <X>.<Y> is the default version.
2.1.2. Support a Particular Version(s)
--------------------------------------
Make your package depend on `python<X>.<Y>-base'. It should install
modules somewhere inside `/usr/lib/python<X>.<Y>/', and use
`#!/usr/bin/pythonX.Y' for programs. A recomended name would be
`python<X>.<Y>-foo', as this allows you to add packages to support
other versions later on, but this is not required.
The packaged source must declare a `Build-Depends' on
`python<X>.<Y>-dev', where <X>.<Y> is the version chosen by the
package maintainer.
2.1.3. Support All/Most Versions (Including Default)
----------------------------------------------------
This option is available for architecture independent packages. There
are two cases:
1. You have extensions compiled against particular versions or
Python. Create multiple `python<X>.<Y>-<module>' packages as in
Section 2.1.2, `Support a Particular Version(s)'. Also create an
empty package `python-<module>' with
Depends: python-base (>= X.Y), python-base (<< X.Y+1), pythonX.Y-module
The `python-<module>' package will need to be updated to match
python-base when ever it updates.
The packaged source must declare `Build-Depends' on each
`python<X>.<Y>-dev' package, the module is built for (i.e.
building more than one Python version from the same source).
2. NOT YET SUPPORTED!!! You have version independant Python
scripts/programs. Create a single package that depends on
`python-base'. Any name can be used, but `python-<module>' is
recommended for a library. It should install modules somewhere
inside `/usr/lib/python/' and use `#!/usr/bin/python' for
programs. The `postinst' script should create symlinks in all
`/usr/lib/pythonX.Y/' directories that point to its
`/usr/lib/python/' files and compile them.
NOT YET SUPPORTED: It becomes errorprone if the package itself
supplies these scripts. And the package cannot know when a new
upstream Python version is installed. So the
`python<X>.<Y>-base' must provide these scripts, which is not yet
done.
The packaged source must declare `Build-Depends' on one
`python<X>.<Y>-dev' package. XXX: Or build-depend on each Python
version, so that only checked modules are uploaded?
DO WE WANT THIS: Some packages, which provide binary Python modules
only, package these modules together in one package (like
`python-pqueue'). They build-depend on all `python<X>.<Y>-dev'
packages on depend on at least one of the versioned base packages:
`python1.5-base | python2.1-base'.
2.2. Module Package Names
-------------------------
Python module packages should be named for the primary module
provided. The naming convention for module `foo' is `python-foo'.
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
should be named `python<X>.<Y>-foo'.
2.3. Dependencies
-----------------
Packaged modules available for the default Python version as described
in in Section 2.1.1, `Support Only The Default Version' must depend on
`python-base (>= <X>.<Y>)' and `python-base (<< <X>.<Y+1>)', where
<X>.<Y+1> describes the next Python upstream version (without the
subminor version).
Packaged modules available for one particular version of Python may
depend on the corresponding `python<X>.<Y>-base' instead.
-------------------------------------------------------------------------------
3. Python Programs
------------------
3.1. Version Independant Programs
---------------------------------
Programs that can run with any version of Python must start with
`#!/usr/bin/env python'. They must also specify a dependency on
`python-base'.
3.2. Version Dependant Programs
-------------------------------
Programs which require a specific version of Python must start with
`#!/usr/bin/env python<X>.<Y>'. They must also specify a dependency
on `python<X>.<Y>'.
-------------------------------------------------------------------------------
4. Programs Embedding Python
----------------------------
4.1. Building Embedded Programs
-------------------------------
Programs which embed a Python interpreter must declare a
`Build-Depends' on `python<X>.<Y>-dev'.
4.2. Embedded Python Dependencies
---------------------------------
Dependencies for programs linking against the shared Python library
will be automatically created by `dpkg-shlibdeps'.
-------------------------------------------------------------------------------
5. 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.
-------------------------------------------------------------------------------
A. Upgrade Procedure
--------------------
This section describe 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>' upstream packages:
1. 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.
2. Upload python core packages `python-<module> (2.1)' & Co
depending on `python2.1-<module>'.
The new packages will conflict with every Python dependant
package, that does depend on `python', `python-base', without
depending on `python (<< 1.6)' or `python-base (<< 2.1)'.
3. 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. XXX Do we allow NMUs which
only fix the dependencies?
4. File bug report against packages and/or make NMU's for packages
that are not adapted by their maintainer.
5. If maintainer A (maintaining `python-foo' (depending on
`python-base (>= 2.1)', `python-base (<< 2.2))' decides for (a),
then a maintainer B should be allowed to repackage
`python1.5-foo', if "his" package cannot be converted to use the
default Python version.
6. File reports that `python2.0' should go away, file serious
reports against all the `python2-*' the packages and
`ftp.debian.org'.
7. Hopefully release woody with `python2.1' as the default Python
version.
-------------------------------------------------------------------------------
Debian Python Policy
Neil Schemenauer <nas@debian.org>
Matthias Klose <doko@debian.org>
version 0.3.3
Reply to: