[Please CC me on replies] I made a new version of the Debian Python Policy, based on Neil's Python Policy (0.1), the new Python packages in unstable and Donovan's comments on the upgrade procedure.
It's appended and available from http://ftp-master.debian.org/~doko/ (including the sgml source). Comments (and patches against the sgml source) are appreciated. Matthias PS: Install the build-dependencies of debian-policy and run nsgmls -gues python-policy.sgml debiandoc2text python-policy.sgml to check and build the sgml file. Debian Python Policy -------------------- Neil Schemenauer <[EMAIL PROTECTED]> Matthias Klose <[EMAIL PROTECTED]> version 0.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. Support Only The Default Version 2.2. Support a Particular Version(s) 2.3. Support All/Most Versions (Including Default) 2.4. Dependencies 2.5. Module Package Names 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 A. Upgrade Procedure ------------------------------------------------------------------------------- 1. Python Packaging ------------------- 1.1. Stable and Legacy Versions ------------------------------- At any given time, the package `python-base' should represent the current stable upstream version of Python. XXX: Should we have an exception for the case, when a new upstream version is released during a Debian freeze? Only one package may contain the `/usr/bin/python' binary and that package must either be `python' or a dependency of that package. The `python' package must provide `python<X>.<Y>'; where <X> and <Y> represent the major and minor versions of the Python, respectively. There can be any number of legacy Python packages available. These must be named `python-<X>.<Y>' and include the file `/usr/bin/python<X>.<Y>'. 1.2. Base Package ----------------- In order to provide a minimal installation of Python for use by applications without requiring the whole of Perl 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/site-python /usr/local/lib/python<X>.<Y>/site-packages /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 ------------------- 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. NOT YET SUPPORTED!!! 2.1. Support Only The Default Version ------------------------------------- Name your package `python-foo' (for a library). Make your package depend on `python-base (>= <X>.<Y>)', `python-base (<< <X2>.<Y2>)'. Install you 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'. 2.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. 2.3. Support All/Most Versions (Including Default) -------------------------------------------------- This option is available for architecture independent packages. XXX Not yet supported!!! 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.2, `Support a Particular Version(s)'. Also create an empty package `python-<module>' with Depends: python-base (>= X.Y), python-base (<< X2.Y2), pythonX.Y-module The `python-<module>' package will need to be updated to match python-base when ever it updates. 2. 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. 2.4. Dependencies ----------------- Packaged modules must depend on `python-base (> <X>.<Y>)' and `python-base (<< <X2>.<Y2>)'. 2.5. 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'. ------------------------------------------------------------------------------- 3. Python Programs ------------------ 3.1. Version Independant Programs --------------------------------- Programs that can run with any version of Python must start with `#!/usr/bin/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/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'. ------------------------------------------------------------------------------- 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. File bugs against any packages that do not meet the above alternatives for packages. 2. Remove the python alternative from the current `python-base' package. The `python-base (1.5.2)' package provides the symlink to `python1.5'. 3. Change the description of the `python-<module> (1.5.2)' packages to "Package providing Debian's default version of the `python-<module>' package". Make the `python-<module> (1.5.2)' packages depend on `python1.5-<module>>'. 4. Wait until all/most bug reports filed in 1) are resolved. Note that during this transition, `python1.5' is the default, so all packages should be fixed to match the above scheme where `python1.5' is the default. At this point we have transitioned to the new scheme. The next part is using this scheme to transition from 1.5 to 2.1. 5. Upload python core packages `python-<module> (2.1)' & Co depending on `python2.1-<module>'. Alternatively if `python2.2' is released at this time we could go on with `python2.2' from this point. Note that this act will break the dependencies of all the packages that have Depends: python-base (>=1.5), python-base (<<1.6) This is intentional, as all the packages with this dependancy will need upgrading. 6. At this point other python modules/packages can be made, which follow the policy from XXX. 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. 7. File reports that `python2.0' should go away, file serious reports against all the `python2-*' the packages and `ftp.debian.org'. 8. Hopefully release woody with `python2.1' or better as the default Python version. ------------------------------------------------------------------------------- Debian Python Policy Neil Schemenauer <[EMAIL PROTECTED]> Matthias Klose <[EMAIL PROTECTED]> version 0.3