[ MFT: debian-python@ldo ]
Hi all,
To resurrect the Python Policy as a document reflecting required and
recommended Python packaging practices, we prepared a set of patches.
We started in private to provide a complete set of changes and avoid
flames as much as possible, but now we'd like the whole Debian Python
community to send comments, feedback, or additional patches.
The goal of this set of patches is only to reflect what's de facto
being done in the archive, and update various bit-rotted sections of
the Python Policy. It's only a first step, but also a prerequisite for
other changes.
We hope that once consensus is reached on how to fix the Python Policy
in the python-defaults package, we can propose new series of patches
proposing changes to the Python Policy such as ideas from the "new
dh_python proposal" [1], or Python 3.x support etc.
Thanks,
[1] http://lists.debian.org/debian-python/2009/08/msg00003.html
--
Piotr Ożarowski, Scott Kitterman, Loïc Minier
From 15c7fa3bbbac8832c638e51c3745cf43e34a2bfc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Thu, 3 Dec 2009 11:53:21 +0100
Subject: [PATCH 01/25] Bump version to 1.9.0.0 to prepare version 2
---
debian/python-policy.sgml | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 5b5e3c2..f0520f7 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -24,7 +24,7 @@
<name>Joe Wreschnig</name>
<email>piman@debian.org</email>
</author>
- <version>version 0.4.1.0</version>
+ <version>version 1.9.0.0</version>
<abstract>
This document describes the packaging of Python within the
--
1.6.5
From 75bb34cfe38be82a52def8952c4feb396cd6caee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Thu, 3 Dec 2009 11:53:59 +0100
Subject: [PATCH 02/25] Add 2009 to Copyright years
---
debian/python-policy.sgml | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index f0520f7..57c0b94 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -34,7 +34,7 @@
<copyright>
<copyrightsummary>
- Copyright © 1999, 2001, 2003, 2006 Software in the
+ Copyright © 1999, 2001, 2003, 2006, 2009 Software in the
Public Interest
</copyrightsummary>
<p>
--
1.6.5
From 635b73c502f03c2fa18f118058185085fed7a56b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Thu, 3 Dec 2009 11:55:02 +0100
Subject: [PATCH 03/25] Update FSF address
---
debian/python-policy.sgml | 4 ++--
1 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 57c0b94..46df3bd 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -58,8 +58,8 @@
</p>
<p>
You can also obtain it by writing to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ Boston, MA 02110-1301, USA.
</p>
</copyright>
</titlepag>
--
1.6.5
From 7c8a18f37366bb87081e5166773d90302025d633 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org> Date: Thu, 3 Dec 2009 11:58:52 +0100 Subject: [PATCH 04/25] Update sample version numbers --- debian/python-policy.sgml | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-) diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml index 46df3bd..0e72f65 100644 --- a/debian/python-policy.sgml +++ b/debian/python-policy.sgml @@ -85,8 +85,8 @@ 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 + releases, i.e. Python 2.5 and 2.5.1 are subminor versions of + the same Python version 2.5, but Python 2.4 and 2.5 are indeed different versions.) </p> <p> -- 1.6.5
From 19335d6cb295340d8e573388e9a43bfcaba2c9ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Thu, 3 Dec 2009 14:29:52 +0100
Subject: [PATCH 05/25] Misc updates related to module dirs and sys.path
Misc updates related to module dirs and sys.path:
- avoid hardcoding the list of sys.path dirs in the Python Policy
- document canonical location of public Python modules -- unless when
using python-central/python-support
- document site-packages versus dist-packages in python2.5 and earlier,
and in python2.6 and later
- drop obsolete directories and mentions of .zip entries
---
debian/python-policy.sgml | 72 +++++++++++++++++++++++---------------------
1 files changed, 38 insertions(+), 34 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 0e72f65..d9205d3 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -172,31 +172,40 @@
<sect id="paths">
<heading>Module Path</heading>
<p>
- 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:
- <example>
-/usr/lib/python<var>XY</var>.zip
-/usr/lib/python<var>X</var>.<var>Y</var>
-/usr/lib/python<var>X</var>.<var>Y</var>/plat-linux2
-/usr/lib/python<var>X</var>.<var>Y</var>/lib-tk
-/usr/lib/python<var>X</var>.<var>Y</var>/lib-dynload
-/usr/local/lib/python<var>X</var>.<var>Y</var>/site-packages
-/usr/lib/python<var>X</var>.<var>Y</var>/site-packages
-/var/lib/python-support/python<var>X</var>.<var>Y</var>
-/usr/lib/python<var>X</var>.<var>Y</var>/site-packages/<var>module-dir</var>
-/usr/lib/site-python
- </example>
- </p>
- <p>
- The use of the <file>/usr/lib/site-python</file> directory
- is deprecated. The directory may be dropped from the path in
- a future version. The /usr/lib/python<var>XY</var>.zip
- archive appeared in python2.3; it is not currently used in
- Debian. Modules should not install directly to the
- <file>/var/lib/python-support</file> directory; it is for
- use by <ref id="pysupport">.
+ By default, Python modules are searched in the directories listed
+ in the PYTHONPATH environment variable and in the sys.path Python
+ variable. Since python2.4 version 2.4.5-3, python2.5 version
+ 2.5.2-7, and python2.6 version 2.6.2-1 sys.path does not include
+ a /usr/lib/python<var>X</var><var>Y</var>.zip entry anymore.
+
+ Directories with private Python modules must be absent from the
+ sys.path.
+
+ Public Python modules not handled by python-central or
+ python-support must be installed in the system Python modules
+ directory, /usr/lib/python<var>X</var>.<var>Y</var>/dist-packages
+ for python2.6 and later, and
+ /usr/lib/python<var>X</var>.<var>Y</var>/site-packages for
+ python2.5 and earlier.
+
+ As an exception to the above, modules managed by python-support
+ are installed in another directory which is added to the sys.path
+ using the .pth mechanism. The .pth mechanism is documented in the
+ Python documentation of the <tt>site</tt> module.
+
+ A special directory is dedicated to public Python modules
+ installed by the local administrator,
+ /usr/local/lib/python<var>X</var>.<var>Y</var>/dist-packages for
+ python2.6 and later, and
+ /usr/local/lib/python<var>X</var>.<var>Y</var>/site-packages for
+ python2.5 and earlier.
+
+ For a local installation by the administrator of python2.6 and
+ later, a special directory is reserved to Python modules which
+ should only be available to this Python,
+ /usr/local/lib/python<var>X</var>.<var>Y</var>/site-packages.
+ Unfortunately, for python2.5 and earlier this directory is also
+ visible to the system Python.
</p>
</sect>
@@ -246,9 +255,9 @@
</p>
<p>
There are two ways to distribute Python modules. Public
- modules are installed in one of the directories listed
+ modules are installed in a public directory as listed
in <ref id="paths">. They are accessible to any
- program. Private modules are installed in a directory such
+ program. Private modules are installed in a private directory such
as <file>/usr/share/<var>packagename</var></file>
or <file>/usr/lib/<var>packagename</var></file>. They are
generally only accessible to a specific program or suite of
@@ -385,9 +394,8 @@ XB-Python-Version: ${python:Versions}
postinst scripts should respect these settings.
</p>
<p>
- Modules in private installation directories and in
- <file>/usr/lib/site-python</file> should be byte-compiled,
- when the default python version changes.
+ Modules in private installation directories should be
+ byte-compiled, when the default python version changes.
</p>
</sect>
</chapt>
@@ -420,10 +428,6 @@ XB-Python-Version: ${python:Versions}
architecture-dependent (e.g. extensions).
</p>
<p>
- <file>/usr/lib/site-python</file> is deprecated and should
- no longer be used for this purpose.
- </p>
- <p>
The rules explained in <ref id="bytecompilation"> apply to
those private modules: the bytecompiled modules must not
be shipped with the package, they should be generated in
--
1.6.5
From c5b99d16c1b12923e67a0769390440ce0df47dbd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Thu, 3 Dec 2009 15:15:47 +0100
Subject: [PATCH 06/25] Document distutils' --install-layout=deb flag
Document the distutils default and the --install-layout=deb flag; see
<http://lists.debian.org/debian-devel/2009/02/msg00431.html>.
---
debian/python-policy.sgml | 39 +++++++++++++++++++++++++++++++++++++++
1 files changed, 39 insertions(+), 0 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index d9205d3..c1e9ad7 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -566,6 +566,45 @@ Build-Depends: python-all-dev
versa). This appendix is just an overview. If you use these
tools, you should read their full documentation.
</p>
+ <sect id="distutils">
+ <heading>distutils</heading>
+ <p>
+ The standard Python distutils module has been modified in Debian to
+ change the default installation directory of public Python modules
+ and to add a new flag to the "install" command to override the
+ default, <prgn>--install-layout=</prgn>.
+
+ To allow the use this flag, maintainers should ensure that at
+ least version 2.6.2-1 will be used for python2.6, version 2.5.4-1
+ for python2.5, and version 2.4.6-2 for python2.4. This flag is
+ parsed but ignored in python2.4 and python2.5.
+
+ Public Python modules installed with a modified distutils default
+ to /usr/local/lib/python<var>X</var>.<var>Y</var>/dist-packages
+ for python2.6 and later. This directory is seen by the
+ system-provided python2.6.
+
+ When using a system-provided python2.4 or python2.5, the default
+ is /usr/lib/python<var>X</var>.<var>Y</var>/site-packages which is
+ seen by the system-provided python2.4 and python2.5 versions, but
+ not by a system-provided python2.6 and later versions.
+
+ When using a local Python installation, the default is
+ /usr/local/lib/python<var>X</var>.<var>Y</var>/site-packages which
+ is only seen by the local Python installation.
+
+ Using the <prgn>--install-layout=deb</prgn> flag to the "install"
+ command of <prgn>setup.py</prgn> with a system-provided python2.6 or
+ later versions, Python modules will be installed to
+ /usr/lib/python<var>X</var>.<var>Y</var>/dist-packages which is only
+ seen by the system-provided python, not by a local installation.
+
+ Using the <prgn>--install-layout=deb</prgn> flag to
+ <prgn>setup.py</prgn> with a system-provided python2.4 or
+ python2.5 doesn't affect the default installation directory.
+ </p>
+ </sect>
+
<sect id="pysupport">
<heading>python-support</heading>
<p>
--
1.6.5
From bcd7d7e577c2758dc7a9fdb858d226de4fef636c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org> Date: Thu, 3 Dec 2009 15:23:27 +0100 Subject: [PATCH 07/25] Deprecate "current" keyword and document "all" --- debian/python-policy.sgml | 16 +++++++++------- 1 files changed, 9 insertions(+), 7 deletions(-) diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml index c1e9ad7..22694cb 100644 --- a/debian/python-policy.sgml +++ b/debian/python-policy.sgml @@ -296,17 +296,19 @@ import foo Depends and Provides lines. The format of the field may be one of the following: <example> -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 +XS-Python-Version: all </example> - 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. + The keyword "all" means that the package supports any Python + version available but might be deprecated in the future since + using version numbers is clearer than "all" and encodes more + information. + + The keyword "current" has been deprecated and used to mean that + the package would only have to support a single version (even + across default version changes). </p> <p> Your control file should also have a line: -- 1.6.5
From ae0ee08523ccc1e30abc5be1638e170478c50385 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Thu, 3 Dec 2009 15:35:46 +0100
Subject: [PATCH 08/25] Document /usr/share/pyshared usage
---
debian/python-policy.sgml | 28 ++++++++++++++++++++--------
1 files changed, 20 insertions(+), 8 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 22694cb..fda0ed5 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -207,6 +207,18 @@
Unfortunately, for python2.5 and earlier this directory is also
visible to the system Python.
</p>
+
+ <p>
+ When packages ship identical source code for multiple Python
+ versions, for instance
+ /usr/lib/python2.6/dist-packages/foo.py and
+ /usr/lib/python2.5/site-packages/foo.py, these should point to a
+ common file.
+
+ A common location to share, across Python versions,
+ arch-independent files which would otherwise go to the directory
+ of system public modules is /usr/share/pyshared.
+ </p>
</sect>
<sect id="docs">
@@ -616,12 +628,12 @@ Build-Depends: python-all-dev
python-support, you should install your modules
to <file>/usr/share/python-support/<var>package</var></file>
rather than the standard Python directories. python-support
- will then handle compiling the modules and making
- appropriate symbolic links for installed Python versions to
- find them,
- substitute <tt>${python:Depends}</tt>, <tt>${python:Versions}</tt>,
- and <tt>${python:Provides}</tt> in your control file, and
- manage bytecompilation in your postinst/prerm.
+ will then move them to /usr/share/pyshared, handle compiling the
+ modules and making appropriate symbolic links for installed Python
+ versions to find them, substitute <tt>${python:Depends}</tt>,
+ <tt>${python:Versions}</tt>, and <tt>${python:Provides}</tt> in
+ your control file, and manage bytecompilation in your
+ postinst/prerm.
</p>
<p>
To use it, call <prgn>dh_pysupport</prgn>
@@ -657,8 +669,8 @@ binary-indep: build install
modules. It integrates with <package>debhelper</package>,
but can also be used without it. When using python-central,
you should install your modules normally. It will then move
- them to its private directory, and manage the same things
- python-support does.
+ them to the /usr/share/pyshared directory, and manage the same
+ things python-support does.
</p>
<p>
To use it, call <prgn>dh_pycentral</prgn>
--
1.6.5
From 4e681bc46827ba97988d9437e961d2f8a62f5568 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Thu, 3 Dec 2009 15:57:48 +0100
Subject: [PATCH 09/25] Document runtimes updates hooks
---
debian/python-policy.sgml | 58 +++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 58 insertions(+), 0 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index fda0ed5..6fd8c1a 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -221,6 +221,58 @@
</p>
</sect>
+ <sect id="runtimes_hooks">
+ <heading>Hooks for updates to installed runtimes</heading>
+ <p>
+ The <package>python</package> package has special hooks to allow
+ other packages to act upon updates to the installed runtimes.
+
+ This mechanism is required to handle changes of the default Python
+ runtime in some packages and to enable the Python packaging
+ helpers.
+
+ There are three supported hook types which come in the form of
+ scripts which are invoked from the maintainer scripts of the
+ Python runtime packages when specific installations,
+ uninstallations, or upgrades occur.
+ </p>
+ <p><enumlist>
+ <item>
+ <p>
+ /usr/share/python/runtime.d/*.rtinstall: these are called when
+ a runtime is installed or becomes supported. The first
+ argument is "rtinstall", the second argument is the affected
+ runtime (for example python<var>X</var>.<var>Y</var>) and the
+ third and fourth argument are the old and new version of this
+ packaged runtime if this runtime was already installed but
+ unsupported.
+ </p>
+ </item>
+ <item>
+ <p>
+ /usr/share/python/runtime.d/*.rtremove: these are called when
+ a runtime is installed or stops being supported. The first
+ argument is "rtremove", and the second argument is the
+ affected runtime (for example
+ python<var>X</var>.<var>Y</var>).
+ </p>
+ </item>
+ <item>
+ <p>
+ /usr/share/python/runtime.d/*.rtupate: these are called when
+ the default runtime changes. The first argument is either
+ "pre-rtupdate", called before changing the default runtime, or
+ "rtupdate", called when changing the default runtime, or
+ "post-rtupdate", called immediately afterwards. The second
+ argument is the old default runtime (for example
+ python<var>X</var>.<var>Y</var>), and the third argument is
+ the new default runtime (for example
+ python<var>X</var>.<var>Z</var>).
+ </p>
+ </item>
+ </enumlist></p>
+ </sect>
+
<sect id="docs">
<heading>Documentation</heading>
<p>
@@ -634,6 +686,9 @@ Build-Depends: python-all-dev
<tt>${python:Versions}</tt>, and <tt>${python:Provides}</tt> in
your control file, and manage bytecompilation in your
postinst/prerm.
+
+ python-support will also register proper hooks to handle changes
+ to the list of supported runtimes.
</p>
<p>
To use it, call <prgn>dh_pysupport</prgn>
@@ -671,6 +726,9 @@ binary-indep: build install
you should install your modules normally. It will then move
them to the /usr/share/pyshared directory, and manage the same
things python-support does.
+
+ python-central will also register proper hooks to handle changes
+ to the list of supported runtimes.
</p>
<p>
To use it, call <prgn>dh_pycentral</prgn>
--
1.6.5
From d81e1c326efb4c7c0706702ac795f2b9525a4651 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Thu, 3 Dec 2009 22:28:14 +0100
Subject: [PATCH 10/25] Clarify rules for byte-compilation and extensions
---
debian/python-policy.sgml | 11 +++++++++--
1 files changed, 9 insertions(+), 2 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 6fd8c1a..4fdcc3b 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -460,8 +460,15 @@ XB-Python-Version: ${python:Versions}
postinst scripts should respect these settings.
</p>
<p>
- Modules in private installation directories should be
- byte-compiled, when the default python version changes.
+ Pure Python modules in private installation directories that are
+ byte-compiled with the default Python version must be forcefully
+ byte-compiled again when the default Python version changes.
+
+ Public Python extensions should be bin-NMUed.
+
+ Private Python extensions should be subject to binary NMUs every
+ time the default interpreter changes, unless the extension is
+ updated through a .rtupdate script.
</p>
</sect>
</chapt>
--
1.6.5
From ffb73a557216c802c2b6db511d1e07ce7c9c5dfa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Fri, 4 Dec 2009 12:41:43 +0100
Subject: [PATCH 11/25] Mention existence of -minimal packages
---
debian/python-policy.sgml | 47 +++++++++++++++++++++++++++++---------------
1 files changed, 31 insertions(+), 16 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 4fdcc3b..3ee1e23 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -102,15 +102,17 @@
</sect>
<sect id="base">
- <heading>Main package</heading>
+ <heading>Main packages</heading>
<p>
- For every Python version provided in the distribution, the
- package <package>python<var>X</var>.<var>Y</var></package>
- shall comprise a complete distribution for
- <em>deployment</em> of Python scripts and applications. The
- package includes the binary
- <file>/usr/bin/python<var>X</var>.<var>Y</var></file> and
- all modules of the upstream Python distribution.
+ For every Python version provided in the distribution, the package
+ <package>python<var>X</var>.<var>Y</var></package> shall provide a
+ complete distribution for <em>deployment</em> of Python scripts
+ and applications. The package must ensure that the binary
+ <file>/usr/bin/python<var>X</var>.<var>Y</var></file> is provided.
+ </p>
+ <p>
+ Installation of <package>python<var>X</var>.<var>Y</var></package>
+ shall provide the modules of the upstream Python distribution.
</p>
<p>
Excluded are any modules that depend on
@@ -122,14 +124,27 @@
Documentation will be provided separately as well.
</p>
<p>
- At any time, the <package>python</package> package must contain
- a symlink <file>/usr/bin/python</file> to the the appropriate binary
- <file>/usr/bin/python<var>X</var>.<var>Y</var></file>. The
- <package>python</package> package must also depend on the
- appropriate <package>python<var>X</var>.<var>Y</var></package>
- to ensure this binary is installed. The version of the
- <package>python</package> package must be greater than or equal to
- <var>X</var>.<var>Y</var> and smaller than <var>X</var>.<var>Y+1</var>.
+ At any time, the <package>python</package> package must ensure
+ that the binary <file>/usr/bin/python</file> is provided.
+
+ The <package>python</package> package must also depend on the
+ appropriate <package>python<var>X</var>.<var>Y</var></package> to
+ ensure this runtime is installed.
+ </p>
+ <p>
+ The version of the <package>python</package> package must be
+ greater than or equal to <var>X</var>.<var>Y</var> and smaller
+ than <var>X</var>.<var>Y+1</var>.
+ </p>
+ </sect>
+
+ <sect id="minimal">
+ <heading>Minimal packages</heading>
+ <p>
+ For every Python version provided in the distribution, the
+ package <package>python<var>X</var>.<var>Y</var></package>-minimal
+ might exist and should not be depended upon by other packages
+ except the Python runtime packages themselves.
</p>
</sect>
--
1.6.5
From 1d8a97d877d535cfc6dc342bd966a7677e5f2217 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Fri, 4 Dec 2009 13:00:35 +0100
Subject: [PATCH 12/25] Document /usr/share/python/debian_defaults
---
debian/python-policy.sgml | 21 +++++++++++++++++++--
1 files changed, 19 insertions(+), 2 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 3ee1e23..868a1fe 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -95,8 +95,25 @@
</p>
<p>
- The set of currently supported python versions can be found
- in <file>/usr/share/python/debian_defaults</file>.
+ The set of currently supported python versions can be found in
+ <file>/usr/share/python/debian_defaults</file>. This file is in
+ Python ConfigParser format and defines four variables in its
+ DEFAULT section: default-version which is the current default
+ Python runtime, supported-versions which is the set of runtimes
+ currently supported and for which modules should be built and
+ byte-compiled, old-versions which is the list of runtimes which
+ might still be on the system but for which should not be built
+ anymore, and unsupported-versions which is the list of runtimes
+ which should not be supported at all, that is modules shouldn't be
+ built or byte-compiled for these.
+ </p>
+ <p>
+ unsupported-versions is a superset of (includes) old-versions and
+ the default-version is always in supported-versions.
+ </p>
+ <p>
+ Newer versions might also appear in unsupported-versions before
+ being moved to supported-versions.
</p>
</sect>
--
1.6.5
From ca50971699d4933144c53fe04e46d4d83167cead Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Fri, 4 Dec 2009 19:03:54 +0100
Subject: [PATCH 13/25] Shorten python-support section, pointing at doc
---
debian/python-policy.sgml | 47 ++++++++------------------------------------
1 files changed, 9 insertions(+), 38 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 868a1fe..b61c87d 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -715,44 +715,15 @@ Build-Depends: python-all-dev
<p>
The python-support system provides a simple way to
bytecompile pure Python modules and manage dependencies. It
- integrates with <package>debhelper</package>. When using
- python-support, you should install your modules
- to <file>/usr/share/python-support/<var>package</var></file>
- rather than the standard Python directories. python-support
- will then move them to /usr/share/pyshared, handle compiling the
- modules and making appropriate symbolic links for installed Python
- versions to find them, substitute <tt>${python:Depends}</tt>,
- <tt>${python:Versions}</tt>, and <tt>${python:Provides}</tt> in
- your control file, and manage bytecompilation in your
- postinst/prerm.
-
- python-support will also register proper hooks to handle changes
- to the list of supported runtimes.
- </p>
- <p>
- To use it, call <prgn>dh_pysupport</prgn>
- before <prgn>dh_python</prgn>, and make sure you've
- installed the modules in the right place:
- <example>
-PREFIX := debian/python-package/usr
-...
-install:
- ...
- ./setup.py install --no-compile \
- --install-lib=$(PREFIX)/share/python-support/python-package
-binary-indep: build install
- ...
- dh_pysupport
- dh_python
- ...
- </example>
- </p>
- <p>
- python-support can also manage private modules. To use this
- feature, pass a list of directories to be managed by
- python-support to <prgn>dh_pysupport</prgn>
- and <prgn>dh_python</prgn>. python-support cannot handle
- compiled extensions.
+ integrates with <package>debhelper</package>, manages
+ byte-compilation, private modules, will properly use the
+ /usr/share/pyshared directory, integrates with runtime update
+ hooks, and will fill-in the <tt>${python:Depends}</tt>,
+ <tt>${python:Versions}</tt>, and <tt>${python:Provides}</tt>
+ substvars.
+
+ See the python-support documentation in
+ /usr/share/doc/python-support for details.
</p>
</sect>
--
1.6.5
From 5a7ffc0592b182a66a22c6b6a86d5b8c78759b12 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Fri, 4 Dec 2009 19:08:38 +0100
Subject: [PATCH 14/25] Shorten python-central section, pointing at doc
---
debian/python-policy.sgml | 49 ++++++++------------------------------------
1 files changed, 9 insertions(+), 40 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index b61c87d..69cead3 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -730,47 +730,16 @@ Build-Depends: python-all-dev
<sect id="pycentral">
<heading>python-central</heading>
<p>
- python-central provides another way to manage Python
- modules. It integrates with <package>debhelper</package>,
- but can also be used without it. When using python-central,
- you should install your modules normally. It will then move
- them to the /usr/share/pyshared directory, and manage the same
- things python-support does.
+ python-central provides another way to manage Python modules. It
+ integrates with <package>debhelper</package>, manages
+ byte-compilation, private modules, will properly use the
+ /usr/share/pyshared directory, integrates with runtime update
+ hooks, and will fill-in the <tt>${python:Depends}</tt>,
+ <tt>${python:Versions}</tt>, and <tt>${python:Provides}</tt>
+ substvars.
- python-central will also register proper hooks to handle changes
- to the list of supported runtimes.
- </p>
- <p>
- To use it, call <prgn>dh_pycentral</prgn>
- before <prgn>dh_python</prgn>:
- <example>
-install:
- ...
- ./setup.py install
-
-binary-indep: build install
- ...
- dh_pycentral
- dh_python
- ...
- </example>
- </p>
- <p>
- python-central can handle compiled extensions for multiple
- Python versions. If you want python-central to handle
- private modules, you must pass the list of directories
- containing them to <prgn>dh_python</prgn> (but
- not <prgn>dh_pycentral</prgn>).
- </p>
- <p>
- If python-central should not move the files to its private
- directory, use<prgn>DH_PYCENTRAL=nomove dh_pycentral</prgn>
- instead.
- </p>
- <p>
- Examples for source packages using python-central are
- pyenchant, python-imaging (modules and extensions),
- pyparallel (modules only).
+ See the python-central documentation in the pycentral(1) and
+ dh_pycentral(1) man pages.
</p>
</sect>
--
1.6.5
From 39ceb9ae2c9232978c39281bc6bd95b607243419 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Fri, 4 Dec 2009 20:08:46 +0100
Subject: [PATCH 15/25] Add myself as author
---
debian/python-policy.sgml | 4 ++++
1 files changed, 4 insertions(+), 0 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 69cead3..3facdd0 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -24,6 +24,10 @@
<name>Joe Wreschnig</name>
<email>piman@debian.org</email>
</author>
+ <author>
+ <name>Loïc Minier</name>
+ <email>lool@debian.org</email>
+ </author>
<version>version 1.9.0.0</version>
<abstract>
--
1.6.5
From 8417f627d20faeedcd74f3042dedb5aecf790c4e Mon Sep 17 00:00:00 2001
From: Scott Kitterman <scott@kitterman.com>
Date: Fri, 4 Dec 2009 14:49:58 -0500
Subject: [PATCH 16/25] Remove extraneous paragraph from Provides section. (Closes: #415213)
---
debian/python-policy.sgml | 8 --------
1 files changed, 0 insertions(+), 8 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 3facdd0..684db63 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -464,14 +464,6 @@ XB-Python-Version: ${python:Versions}
python version. Provides should also be added on request of
maintainers who depend on a non-default python version.
</p>
- <p>
- Packaged modules available for one particular version of Python must
- depend on the corresponding
- <package>python<var>X</var>.<var>Y</var></package> package instead.
- If they need other modules, they must depend on the corresponding
- <package>python<var>X</var>.<var>Y</var>-foo</package> packages, and
- must not depend on any <package>python-foo</package>.
- </p>
</sect>
<sect id="bytecompilation">
--
1.6.5
From 726feb0686b7485834bd9185283526956aa35b59 Mon Sep 17 00:00:00 2001
From: Scott Kitterman <scott@kitterman.com>
Date: Fri, 4 Dec 2009 15:07:21 -0500
Subject: [PATCH 17/25] Remove obsolete mentions of dh_python. (Closes: #527009)
---
debian/python-policy.sgml | 17 +++++++----------
1 files changed, 7 insertions(+), 10 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 684db63..59b08c6 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -417,13 +417,12 @@ XB-Python-Version: ${python:Versions}
</example>
The python:Versions is substituted by the supported Python
versions of the binary package, based on
- <tt>XS-Python-Version</tt>. (If you are not using
- <prgn>dh_python</prgn> you will need to handle this
- substitution yourself.) The format of the field
- <tt>XB-Python-Version</tt> is the same as the
- <tt>XS-Python-Version</tt> field for packages not containing
- extensions. Packages with extensions must list the versions
- explicitely.
+ <tt>XS-Python-Version</tt>. (If you are not using python-central
+ or python-support, you will need to handle this substitution
+ yourself.) The format of the field <tt>XB-Python-Version</tt> is
+ the same as the <tt>XS-Python-Version</tt> field for packages not
+ containing extensions. Packages with extensions must list the
+ versions explicitely.
</p>
<p>
If your package is used by another module or application
@@ -651,9 +650,7 @@ Build-Depends: python-all-dev
<p>
If you use either <package>python-support</package> or
<package>python-central</package> you must additionally
- Build-Depend on those. If you are using <prgn>dh_python</prgn>
- at all, you must Build-Depend on <package>python</package>, as
- <package>debhelper</package> does not depend on it.
+ Build-Depend on those.
</p>
</appendix>
--
1.6.5
From 0c972ba856c775aa5575a71b0f0da52027090012 Mon Sep 17 00:00:00 2001 From: Scott Kitterman <scott@kitterman.com> Date: Fri, 4 Dec 2009 15:16:06 -0500 Subject: [PATCH 18/25] Fix policy typo. (Closes: #523226) --- debian/python-policy.sgml | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-) diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml index 59b08c6..90e8aed 100644 --- a/debian/python-policy.sgml +++ b/debian/python-policy.sgml @@ -79,7 +79,7 @@ represent the current default Debian Python version. </p> <p> - The default Debian Python version should alway be the latest stable + The default Debian Python version should always be the latest stable upstream release that can be integrated in the distribution. </p> <p> -- 1.6.5
From 74dfe5810fb6f406a06b20c767e80f6473c35e3a Mon Sep 17 00:00:00 2001 From: Scott Kitterman <scott@kitterman.com> Date: Fri, 4 Dec 2009 16:06:13 -0500 Subject: [PATCH 19/25] Add pointer to doc of site module to tweak path Add pointer to doc of the site module for site-specific paths. (Closes: #287197) --- debian/python-policy.sgml | 4 ++++ 1 files changed, 4 insertions(+), 0 deletions(-) diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml index 90e8aed..2631558 100644 --- a/debian/python-policy.sgml +++ b/debian/python-policy.sgml @@ -242,6 +242,10 @@ /usr/local/lib/python<var>X</var>.<var>Y</var>/site-packages. Unfortunately, for python2.5 and earlier this directory is also visible to the system Python. + + Additional information on appending site-specific paths to the + module search path is available in the official documentation of + the site module. </p> <p> -- 1.6.5
From 94e9ff3a9f8ec97ee6b6e157fe4e8226c8054f48 Mon Sep 17 00:00:00 2001
From: Scott Kitterman <scott@kitterman.com>
Date: Fri, 4 Dec 2009 16:17:30 -0500
Subject: [PATCH 20/25] Add myself to authors.
---
debian/python-policy.sgml | 4 ++++
1 files changed, 4 insertions(+), 0 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 2631558..455ca0e 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -28,6 +28,10 @@
<name>Loïc Minier</name>
<email>lool@debian.org</email>
</author>
+ <author>
+ <name>Scott Kitterman</name>
+ <email>scott@kitterman.com</email>
+ </author>
<version>version 1.9.0.0</version>
<abstract>
--
1.6.5
From 3f9e780dee7b7b8afbf2dfb4c9a779d1d753b566 Mon Sep 17 00:00:00 2001 From: Scott Kitterman <scott@kitterman.com> Date: Fri, 4 Dec 2009 16:25:00 -0500 Subject: [PATCH 21/25] Clarify that the default Python should be fully integrated. Newer versions may be shipped as either supported or unsupported. --- debian/python-policy.sgml | 5 ++++- 1 files changed, 4 insertions(+), 1 deletions(-) diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml index 455ca0e..8d7acf6 100644 --- a/debian/python-policy.sgml +++ b/debian/python-policy.sgml @@ -84,7 +84,10 @@ </p> <p> The default Debian Python version should always be the latest stable - upstream release that can be integrated in the distribution. + upstream release that can be fully integrated in the distribution. + There may be newer supported or unsupported versions included in + the distribution if they are not fully integrated for a particular + release. </p> <p> Apart from the default version, legacy versions of Python -- 1.6.5
From 147a28c2794c32e312020dbf6c3388728f328c2d Mon Sep 17 00:00:00 2001 From: Scott Kitterman <scott@kitterman.com> Date: Fri, 4 Dec 2009 16:36:09 -0500 Subject: [PATCH 22/25] Updated policy for Python version upgrades --- debian/python-policy.sgml | 22 +++++++++++++++++++--- 1 files changed, 19 insertions(+), 3 deletions(-) diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml index 8d7acf6..36ffd51 100644 --- a/debian/python-policy.sgml +++ b/debian/python-policy.sgml @@ -768,13 +768,29 @@ Build-Depends: python-all-dev <enumlist> <item> <p> + Pre-release and early final releases of new Python versions are + uploaded to Experimental to support pre-transition work and + testing. + </p> + </item> + <item> + <p> + Application and module maintainers make sourceful changes where + needed to prepare for the new Python version when needed. + </p> + </item> + <item> + <p> Have a long and heated discussion. </p> </item> <item> <p> - The Debian Python maintainer decides for the new default Debian - Python version and announces the upgrade. + The Debian Python maintainer and module/application maintainers + discuss the readiness for a new default Debian Python version + and associated packaging/policy changes. Once there is some + consensus, the Python maintainer announces the upgrade and + uploads to Unstable. </p> </item> <item> @@ -789,7 +805,7 @@ Build-Depends: python-all-dev <item> <p> The release team schedules rebuilds for packages that - may need it. Packages that require manual work get + may need it. Packages that require additional manual work get updated and uploaded. </p> </item> -- 1.6.5
From 18f869cac8b5ef51753976e4c8fcc8909162829b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Mon, 7 Dec 2009 17:26:10 +0100
Subject: [PATCH 23/25] Extensions aren't linked to libpython
---
debian/python-policy.sgml | 7 ++++++-
1 files changed, 6 insertions(+), 1 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 36ffd51..900a59e 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -352,8 +352,13 @@
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
+ specific version of the python runtime, and so can only
be used by one version of Python.
+
+ Some distributions link extensions to libpython, but this is not
+ the case in Debian as symbols might as well be resolved by
+ <file>/usr/bin/python<var>X</var>.<var>Y</var></file> which is not
+ linked to libpython.
</p>
<p>
Python packages are directories containing at least a
--
1.6.5
From be9cca720ee3948d9806dbf10df1726929af87be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Mon, 7 Dec 2009 17:30:52 +0100
Subject: [PATCH 24/25] Let XS-Python-Version be optional
Let XS-Python-Version be optional as pyversions usefully defaults to all
supported versions and that's fine.
---
debian/python-policy.sgml | 14 ++++++++------
1 files changed, 8 insertions(+), 6 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 900a59e..456d373 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -404,13 +404,15 @@ import foo
<sect id="specifying_versions">
<heading>Specifying Supported Versions</heading>
<p>
- The <tt>XS-Python-Version</tt> field
+ The optional <tt>XS-Python-Version</tt> field
in <file>debian/control</file> 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:
+ Python supported by the package. When not specified, it defaults
+ to all currently supported Python versions.
+
+ It is notably 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:
<example>
XS-Python-Version: >= X.Y
XS-Python-Version: >= A.B, << X.Y
--
1.6.5
From cf624c3f1c8c80fdaff6bca1b823c04d3d6e0ed3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Minier?= <lool@dooz.org>
Date: Tue, 8 Dec 2009 12:40:34 +0100
Subject: [PATCH 25/25] Add mention of CDBS python-distutils.mk class
---
debian/python-policy.sgml | 3 ++-
1 files changed, 2 insertions(+), 1 deletions(-)
diff --git a/debian/python-policy.sgml b/debian/python-policy.sgml
index 456d373..e387629 100644
--- a/debian/python-policy.sgml
+++ b/debian/python-policy.sgml
@@ -757,7 +757,8 @@ Build-Depends: python-all-dev
<sect id="cdbs">
<heading>CDBS</heading>
<p>
- FIXME: Someone familiar with CDBS should write this part.
+ The CDBS python-distutils.mk class helps packaging of setup.py
+ based Python packages.
</p>
</sect>
--
1.6.5
Debian Python Policy
--------------------
Neil Schemenauer <nas@debian.org>
Matthias Klose <doko@debian.org>
Gregor Hoffleit <flight@debian.org>
Josselin Mouette <joss@debian.org>
Joe Wreschnig <piman@debian.org>
Loi"c Minier <lool@debian.org>
Scott Kitterman <scott@kitterman.com>
version 1.9.0.0
-------------------------------------------------------------------------------
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, 2003, 2006, 2009 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., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
-------------------------------------------------------------------------------
Contents
--------
1. Python Packaging
1.1. Versions
1.2. Main packages
1.3. Minimal packages
1.4. Python Interpreter
1.4.1. Interpreter Name
1.4.2. Interpreter Location
1.5. Module Path
1.6. Hooks for updates to installed runtimes
1.7. Documentation
2. Packaged Modules
2.1. Types of Python Modules
2.2. Module Package Names
2.3. Specifying Supported Versions
2.4. Dependencies
2.5. Provides
2.6. Modules Bytecompilation
3. Python Programs
3.1. Programs using the default python
3.1.1. Programs Shipping Private Modules
3.2. Programs Using a Particular Python Version
4. Programs Embedding Python
4.1. Building Embedded Programs
4.2. Embedded Python Dependencies
5. Interaction with Locally Installed Python Versions
A. Build Dependencies
B. Packaging Tools
B.1. distutils
B.2. python-support
B.3. python-central
B.4. CDBS
C. Upgrade Procedure
-------------------------------------------------------------------------------
1. Python Packaging
-------------------
1.1. Versions
-------------
At any given time, the package `python' will represent the current
default Debian Python version.
The default Debian Python version should always be the latest stable
upstream release that can be fully integrated in the distribution.
There may be newer supported or unsupported versions included in the
distribution if they are not fully integrated for a particular
release.
Apart from the default version, legacy versions of Python or beta
versions of future releases 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.5 and 2.5.1 are subminor versions of the same Python version
2.5, but Python 2.4 and 2.5 are indeed different versions.)
For any version, the main package must be called `python<X>.<Y>'.
The set of currently supported python versions can be found in
`/usr/share/python/debian_defaults'. This file is in Python
ConfigParser format and defines four variables in its DEFAULT section:
default-version which is the current default Python runtime,
supported-versions which is the set of runtimes currently supported
and for which modules should be built and byte-compiled, old-versions
which is the list of runtimes which might still be on the system but
for which should not be built anymore, and unsupported-versions which
is the list of runtimes which should not be supported at all, that is
modules shouldn't be built or byte-compiled for these.
unsupported-versions is a superset of (includes) old-versions and the
default-version is always in supported-versions.
Newer versions might also appear in unsupported-versions before being
moved to supported-versions.
1.2. Main packages
------------------
For every Python version provided in the distribution, the package
`python<X>.<Y>' shall provide a complete distribution for _deployment_
of Python scripts and applications. The package must ensure that the
binary `/usr/bin/python<X>.<Y>' is provided.
Installation of `python<X>.<Y>' shall provide the 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
`python<X>.<Y>-dev'. Documentation will be provided separately as
well.
At any time, the `python' package must ensure that the binary
`/usr/bin/python' is provided. The `python' package must also depend
on the appropriate `python<X>.<Y>' to ensure this runtime is
installed.
The version of the `python' package must be greater than or equal to
<X>.<Y> and smaller than <X>.<Y+1>.
1.3. Minimal packages
---------------------
For every Python version provided in the distribution, the package
`python<X>.<Y>'-minimal might exist and should not be depended upon by
other packages except the Python runtime packages themselves.
1.4. Python Interpreter
-----------------------
1.4.1. Interpreter Name
-----------------------
Python scripts depending on the default Python version (see Section
1.2, `Main packages') 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
explicitly use the versioned interpreter name (`python<X>.<Y>').
1.4.2. Interpreter Location
---------------------------
The preferred specification for the Python interpreter is
`/usr/bin/python' or `/usr/bin/python<X>.<Y>'. This ensures that a
Debian installation of python is used and all dependencies on
additional python modules are met.
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 python<X>.<Y>'. However this
is not advisable as it bypasses Debian's dependency checking and makes
the package vulnerable to incomplete local installations of python.
1.5. Module Path
----------------
By default, Python modules are searched in the directories listed in
the PYTHONPATH environment variable and in the sys.path Python
variable. Since python2.4 version 2.4.5-3, python2.5 version 2.5.2-7,
and python2.6 version 2.6.2-1 sys.path does not include a
/usr/lib/python<X><Y>.zip entry anymore. Directories with private
Python modules must be absent from the sys.path. Public Python
modules not handled by python-central or python-support must be
installed in the system Python modules directory,
/usr/lib/python<X>.<Y>/dist-packages for python2.6 and later, and
/usr/lib/python<X>.<Y>/site-packages for python2.5 and earlier. As an
exception to the above, modules managed by python-support are
installed in another directory which is added to the sys.path using
the .pth mechanism. The .pth mechanism is documented in the Python
documentation of the `site' module. A special directory is dedicated
to public Python modules installed by the local administrator,
/usr/local/lib/python<X>.<Y>/dist-packages for python2.6 and later,
and /usr/local/lib/python<X>.<Y>/site-packages for python2.5 and
earlier. For a local installation by the administrator of python2.6
and later, a special directory is reserved to Python modules which
should only be available to this Python,
/usr/local/lib/python<X>.<Y>/site-packages. Unfortunately, for
python2.5 and earlier this directory is also visible to the system
Python. Additional information on appending site-specific paths to
the module search path is available in the official documentation of
the site module.
When packages ship identical source code for multiple Python versions,
for instance /usr/lib/python2.6/dist-packages/foo.py and
/usr/lib/python2.5/site-packages/foo.py, these should point to a
common file. A common location to share, across Python versions,
arch-independent files which would otherwise go to the directory of
system public modules is /usr/share/pyshared.
1.6. Hooks for updates to installed runtimes
--------------------------------------------
The `python' package has special hooks to allow other packages to act
upon updates to the installed runtimes. This mechanism is required to
handle changes of the default Python runtime in some packages and to
enable the Python packaging helpers. There are three supported hook
types which come in the form of scripts which are invoked from the
maintainer scripts of the Python runtime packages when specific
installations, uninstallations, or upgrades occur.
1. /usr/share/python/runtime.d/*.rtinstall: these are called when a
runtime is installed or becomes supported. The first argument is
"rtinstall", the second argument is the affected runtime (for
example python<X>.<Y>) and the third and fourth argument are the
old and new version of this packaged runtime if this runtime was
already installed but unsupported.
2. /usr/share/python/runtime.d/*.rtremove: these are called when a
runtime is installed or stops being supported. The first
argument is "rtremove", and the second argument is the affected
runtime (for example python<X>.<Y>).
3. /usr/share/python/runtime.d/*.rtupate: these are called when the
default runtime changes. The first argument is either
"pre-rtupdate", called before changing the default runtime, or
"rtupdate", called when changing the default runtime, or
"post-rtupdate", called immediately afterwards. The second
argument is the old default runtime (for example python<X>.<Y>),
and the third argument is the new default runtime (for example
python<X>.<Z>).
1.7. Documentation
------------------
Python documentation is split out in separate packages
`python<X>.<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.
-------------------------------------------------------------------------------
2. Packaged Modules
-------------------
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.
2.1. Types of Python Modules
----------------------------
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 python runtime, and so
can only be used by one version of Python. Some distributions link
extensions to libpython, but this is not the case in Debian as symbols
might as well be resolved by `/usr/bin/python<X>.<Y>' which is not
linked to libpython.
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 a public directory as listed in Section 1.5, `Module
Path'. They are accessible to any program. Private modules are
installed in a private directory such as `/usr/share/<packagename>' or
`/usr/lib/<packagename>'. They are generally only accessible to a
specific program or suite of programs included in the same package.
2.2. Module Package Names
-------------------------
Public modules should be packaged with a name of `python-<foo>', where
<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.
2.3. Specifying Supported Versions
----------------------------------
The optional `XS-Python-Version' field in `debian/control' specifies
the versions of Python supported by the package. When not specified,
it defaults to all currently supported Python versions. It is notably
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: >= X.Y
XS-Python-Version: >= A.B, << X.Y
XS-Python-Version: A.B, X.Y
XS-Python-Version: all
The keyword "all" means that the package supports any Python version
available but might be deprecated in the future since using version
numbers is clearer than "all" and encodes more information. The
keyword "current" has been deprecated and used to mean that the
package would only have to support a single version (even across
default version changes).
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 python-central or python-support, 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<X>.<Y>-foo'
for each version it supports.
2.4. Dependencies
-----------------
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 (>= <X>.<Y>')". If they
require other modules to work, they must depend on the corresponding
`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<X>.<Y>' package instead. If they
need other modules, they must depend on the corresponding
`python<X>.<Y>-foo' packages, and must not depend on any `python-foo'.
2.5. Provides
-------------
Provides in packages of the form `python-<foo>' 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.
2.6. 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 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.
Pure Python modules in private installation directories that are
byte-compiled with the default Python version must be forcefully
byte-compiled again when the default Python version changes. Public
Python extensions should be bin-NMUed. Private Python extensions
should be subject to binary NMUs every time the default interpreter
changes, unless the extension is updated through a .rtupdate script.
-------------------------------------------------------------------------------
3. Python Programs
------------------
3.1. Programs using the default python
--------------------------------------
Programs that can run with any version of Python must begin with
`#!/usr/bin/python' or `#!/usr/bin/env python' (the former is
preferred). They must also specify a dependency on `python', with a
versioned dependency if necessary.
If the program needs the python module `foo', it must depend on
`python-foo'.
3.1.1. Programs Shipping Private Modules
----------------------------------------
A program using `/usr/bin/python' as interpreter can come up with
private Python modules. These modules should be installed in
`/usr/share/<module>', or `/usr/lib/<module>' if the modules are
architecture-dependent (e.g. extensions).
The rules explained in Section 2.6, `Modules Bytecompilation' apply to
those private modules: the bytecompiled modules must not be shipped
with the package, they should be generated in the package's postinst,
using the current default Python version, and removed in the prerm.
Modules should be bytecompiled using the current default Python
version.
Programs that have private compiled extensions must either handle
multiple version support themselves, or declare a tight dependency on
the current Python version (e.g. `Depends: python (>= 2.4), python
(<= 2.5)'. No tools currently exist to alleviate this situation.
3.2. Programs Using a Particular Python Version
-----------------------------------------------
A program which requires a specific version of Python must begin with
`#!/usr/bin/python<X>.<Y>' (or `#!/usr/bin/env python<X>.<Y>'). It
must also specify a dependency on `python<X>.<Y>' and on any
`python<X>.<Y>-foo' package providing necessary modules. It should
not depend on any `python-foo' package, unless it requires a specific
version of the package (since virtual packages cannot be versioned).
If this is the case, it should depend on both the virtual package and
the main package (e.g. `Depends: python2.4-foo, python-foo (>=
1.0)').
The notes on installation directories and bytecompilation for programs
that support any version of Python also apply to programs supporting
only a single Python version. Modules to be bytecompiled should use
the same Python version as the package itself.
-------------------------------------------------------------------------------
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', where python<X>.<Y> is the
python version the program builds against. It should be the current
default python version unless the program doesn't work correctly with
this version.
4.2. Embedded Python Dependencies
---------------------------------
Dependencies for programs linking against the shared Python library
will be automatically created by `dpkg-shlibdeps'. The
`libpython<X>.<Y>.so.<Z>' library the program is built against is
provided by the `python<X>.<Y>' package.
-------------------------------------------------------------------------------
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. Build Dependencies
---------------------
Build dependencies for Python dependent packages must be declared for
every Python version that the package is built for. The
`python-all-dev' should be used when building modules for any or all
Python versions. To build for a specific version or versions,
Build-Depend on `python<X>.<Y>-dev'.
Some applications and pure Python modules may be able to depend only
on `python' or `python-all' and not require the -dev packages.
Build-Depend on at least:
Build-Depends: python2.3 (>= 2.3-1)
Build-Depends: python2.4 (>= 2.4-1)
Build-Depends: python (>= 2.3.5-7)
Build-Depends: python-all
Build-Depends: python2.3-dev (>= 2.3-1)
Build-Depends: python2.4-dev (>= 2.4-1)
Build-Depends: python-dev (>= 2.3.5-7)
Build-Depends: python-all-dev
If you use either `python-support' or `python-central' you must
additionally Build-Depend on those.
-------------------------------------------------------------------------------
B. Packaging Tools
------------------
This section describes the various tools to help package Python
programs and modules for Debian. Although none of these tools are
mandatory, their use is strongly encouraged, as the above policy has
been designed with them in mind (and vice versa). This appendix is
just an overview. If you use these tools, you should read their full
documentation.
B.1. distutils
--------------
The standard Python distutils module has been modified in Debian to
change the default installation directory of public Python modules and
to add a new flag to the "install" command to override the default,
`--install-layout='. To allow the use this flag, maintainers should
ensure that at least version 2.6.2-1 will be used for python2.6,
version 2.5.4-1 for python2.5, and version 2.4.6-2 for python2.4.
This flag is parsed but ignored in python2.4 and python2.5. Public
Python modules installed with a modified distutils default to
/usr/local/lib/python<X>.<Y>/dist-packages for python2.6 and later.
This directory is seen by the system-provided python2.6. When using a
system-provided python2.4 or python2.5, the default is
/usr/lib/python<X>.<Y>/site-packages which is seen by the
system-provided python2.4 and python2.5 versions, but not by a
system-provided python2.6 and later versions. When using a local
Python installation, the default is
/usr/local/lib/python<X>.<Y>/site-packages which is only seen by the
local Python installation. Using the `--install-layout=deb' flag to
the "install" command of `setup.py' with a system-provided python2.6
or later versions, Python modules will be installed to
/usr/lib/python<X>.<Y>/dist-packages which is only seen by the
system-provided python, not by a local installation. Using the
`--install-layout=deb' flag to `setup.py' with a system-provided
python2.4 or python2.5 doesn't affect the default installation
directory.
B.2. python-support
-------------------
The python-support system provides a simple way to bytecompile pure
Python modules and manage dependencies. It integrates with
`debhelper', manages byte-compilation, private modules, will properly
use the /usr/share/pyshared directory, integrates with runtime update
hooks, and will fill-in the `${python:Depends}', `${python:Versions}',
and `${python:Provides}' substvars. See the python-support
documentation in /usr/share/doc/python-support for details.
B.3. python-central
-------------------
python-central provides another way to manage Python modules. It
integrates with `debhelper', manages byte-compilation, private
modules, will properly use the /usr/share/pyshared directory,
integrates with runtime update hooks, and will fill-in the
`${python:Depends}', `${python:Versions}', and `${python:Provides}'
substvars. See the python-central documentation in the pycentral(1)
and dh_pycentral(1) man pages.
B.4. CDBS
---------
The CDBS python-distutils.mk class helps packaging of setup.py based
Python packages.
-------------------------------------------------------------------------------
C. Upgrade Procedure
--------------------
This section describes the procedure for the upgrade when the default
python version is changed in the `unstable' distribution, requiring
recompilation of many python-related packages.
1. Pre-release and early final releases of new Python versions are
uploaded to Experimental to support pre-transition work and
testing.
2. Application and module maintainers make sourceful changes where
needed to prepare for the new Python version when needed.
3. Have a long and heated discussion.
4. The Debian Python maintainer and module/application maintainers
discuss the readiness for a new default Debian Python version and
associated packaging/policy changes. Once there is some
consensus, the Python maintainer announces the upgrade and
uploads to Unstable.
5. Upload of the python core metapackages `python', `python-dev',
`python-doc' and several `python-<module>', depending on the new
`python<X>.<Y>', `python<X>.<Y>-dev' and so on.
6. The release team schedules rebuilds for packages that may need
it. Packages that require additional manual work get updated and
uploaded.
-------------------------------------------------------------------------------
Debian Python Policy
Neil Schemenauer <nas@debian.org>
Matthias Klose <doko@debian.org>
Gregor Hoffleit <flight@debian.org>
Josselin Mouette <joss@debian.org>
Joe Wreschnig <piman@debian.org>
Loi"c Minier <lool@debian.org>
Scott Kitterman <scott@kitterman.com>
version 1.9.0.0
Attachment:
signature.asc
Description: Digital signature