Newer
Older
<!doctype debiandoc system>
<debiandoc>
<book>
<titlepag>
<title>Debian Python Policy</title>
<author>
<name>Neil Schemenauer</name>
<email>nas@debian.org</email>
</author>
<author>
<name>Matthias Klose</name>
<email>doko@debian.org</email>
</author>
<author>
<name>Gregor Hoffleit</name>
<email>flight@debian.org</email>
</author>
<author>
<name>Josselin Mouette</name>
<email>joss@debian.org</email>
</author>
<author>
<name>Joe Wreschnig</name>
<email>piman@debian.org</email>
</author>
<author>
<name>Loïc Minier</name>
<email>lool@debian.org</email>
</author>
<author>
<name>Scott Kitterman</name>
<email>scott@kitterman.com</email>
</author>
<abstract>
This document describes the packaging of Python within the
Debian GNU/Linux distribution and the policy requirements for
packaged Python programs and modules.
</abstract>
<copyright>
<copyrightsummary>
Copyright © 1999, 2001, 2003, 2006, 2009, 2010, 2011 Software in the
</copyrightsummary>
<p>
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.
</p>
<p>
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.
</p>
<p>
A copy of the GNU General Public License is available as
<tt>/usr/share/common-licences/GPL</tt> in the Debian GNU/Linux
distribution or on the World Wide Web at
<url id="http://www.gnu.org/copyleft/gpl.html"
name="The GNU General Public License">.
</p>
<p>
You can also obtain it by writing to the
Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
Boston, MA 02110-1301, USA.
</p>
</copyright>
</titlepag>
<toc detail="sect1">
<chapt id="python">
<heading>Python Packaging</heading>
<sect id="versions">
<heading>Versions</heading>
<p>
At any given time, the binary package <package>python</package>
will represent the current default Debian Python version. The
binary package <package>python3</package> will represent the current
Debian Python 3 version. As far as is reasonable, python and python3
should be treated as separate runtime systems with minimal
interdependencies. In some cases, Python policy explicitly references
Python helper programs such as python-support and python-central. None of
these references apply to Python 3. It is a design goal to fully specify
required interfaces and functions in policy for Python 3 and to avoid
enshrining specific implmentation details in policy. Except as noted,
policy for Python 3 is the same as Python with the addition of the version
number as needed to distinguish them.
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.
</p>
<p>
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 sub-minor versions of
the same Python version 2.5, but Python 2.4 and 2.5 are
indeed different versions.)
</p>
<p>
For any version, the main binary package must be called
<package>python<var>X</var>.<var>Y</var></package>.
</p>
<p>
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 should not be
built or byte-compiled for these. The supported interface to this
file is <file>/usr/bin/pyversions</file>. The Python 3 interface is
through <file>/usr/bin/py3versions</file>.
</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>
<sect id="base">
<heading>Main packages</heading>
For every Python version provided in the distribution, the binary
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 with
some exceptions.
</p>
<p>
Excluded are modules that cannot be included for licensing
reasons (for example the profile module), for dependency tracking
purposes (for example the GPL-licensed gdbm module) or that should
not be included for packaging reasons (for example the tk module
which depends on Xorg).
Some tools and files for the <em>development</em> of Python
modules are split off in a separate binary package
<package>python<var>X</var>.<var>Y</var>-dev</package>.
Documentation will be provided separately as well.
</p>
<p>
At any time, the <package>python</package> binary package must
ensure that <file>/usr/bin/python</file> is provided as a symlink
to the current <file>python<var>X</var>.<var>Y</var></file>
executable.
The <package>python</package> binary 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> binary 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>
<p>
There is no symlink for <file>/usr/bin/python2</file>. This is
consistent with current upstream practice. This is being discussed
in <url id="http://www.python.org/dev/peps/pep-0394/"
name="PEP-0394">. If this PEP is approved, then the policy for
Debian should be reconsidered.
</p>
</sect>
<sect id="minimal">
<heading>Minimal packages</heading>
<p>
For every Python version provided in the distribution, the
binary 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>
<sect id="interpreter">
<heading>Python Interpreter</heading>
<sect1 id="interpreter_name">
<heading>Interpreter Name</heading>
<p>
Python scripts depending on the default Python version (see <ref
id="base">) or not depending on a specific Python version should
use <file>python</file> (without a version) as the interpreter name.
</p>
<p>
Python scripts that only work with a specific Python version must
explicitly use the versioned interpreter name
(<file>python<var>X</var>.<var>Y</var></file>).
</p>
</sect1>
<sect1 id="interpreter_loc">
<heading>Interpreter Location</heading>
<p>
The preferred specification for the Python interpreter is
<file>/usr/bin/python</file> or
<file>/usr/bin/python<var>X</var>.<var>Y</var></file>.
This ensures that a Debian installation of python is used
and all dependencies on additional python modules are met.
</p>
<p>
Maintainers should notoverride the Debian Python interpreter using
<file>/usr/bin/env python</file> or
<file>/usr/bin/env python<var>X</var>.<var>Y</var></file>. This is
not advisable as it bypasses Debian's dependency checking and makes
the package vulnerable to incomplete local installations of python.
</p>
</sect1>
</sect>
<sect id="paths">
<heading>Module Path</heading>
<p>
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, python2.6 version 2.6.2-1, and in all python2.7 versions,
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. Public Python 3 modules must be installed in
/usr/lib/python3/dist-packages.
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/lib/python3/dist-packages for all python3 versions,
/usr/local/lib/python2.<var>Y</var>/dist-packages for python2.6 and
later, and /usr/local/lib/python2.<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/python2.<var>Y</var>/site-packages (and
/usr/local/lib/python3/site-packages for all python3 versions).
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>
When binary 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. Version specific directories for identical source code
are not required for python3 and must not be used for this.
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. For python3,
a special location is not required, use
/usr/lib/python3/dist-packages
</sect>
<sect id="runtimes_hooks">
<heading>Hooks for updates to installed runtimes</heading>
The <package>python</package> binary 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,
removals, or upgrades occur.
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
<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>
Python documentation is split out in separate binary packages
<package>python<var>X</var>.<var>Y</var>-doc</package>. The binary
package <package>python-doc</package> will always provide the
documentation for the default Debian Python version.
</p>
<p>
TODO: Policy for documentation of third party packages.
</p>
</sect>
</chapt>
<chapt id="module_packages">
<heading>Packaged Modules</heading>
<p>
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-byte-compiling 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.
<heading>Types of Python Modules</heading>
<p>
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
<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
<file>__init__.py</file>, 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.
</p>
<p>
There are two ways to distribute Python modules. Public
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 private directory such
as <file>/usr/share/<var>package-name</var></file>
or <file>/usr/lib/<var>package-name</var></file>. They are
generally only accessible to a specific program or suite of
programs included in the same package.
<sect id="package_names">
<heading>Module Package Names</heading>
Public modules used by other packages must have their binary
package name prefixed with <var>python-</var>. It is recommended
to use this prefix for all packages with public modules as they may
be used by other packages in the future. Python 3 modules must be
in a separate binary package prefixed with <var>python3-</var> to
preserve run time separation between python and python3.
The binary package for module foo should preferably be named
<package>python-<var>foo</var></package>, if the module name
allows, but this is not required if the binary package ships
multiple modules. In the latter case the maintainer chooses the
name of the module which represents the package the most.
Such a package should support the current Debian Python version,
and more if possible (there are several tools to help implement
this, see <ref id="packaging_tools">). For example, if Python 2.3,
2.4, and 2.5 are supported, the Python statement
<example>
import foo
</example>
should import the module when the user is running any
of <prgn>/usr/bin/python2.3</prgn>, <prgn>/usr/bin/python2.4</prgn>,
and <prgn>/usr/bin/python2.5</prgn>. This requirement also
applies to extension modules; binaries for all the supported
Python versions should be included in a single package.
</sect>
<sect id="specifying_versions">
<heading>Specifying Supported Versions</heading>
<p>
The optional <tt>X-Python-Version</tt> (preferred) or <tt>
XS-Python-Version</tt> field in the general paragraph (the first one,
for the source package) of <file>debian/control</file> specifies the
versions of Python (not versions of Python 3) supported by the
source package. Similarly, <tt>X-Python3-Version</tt> is used to
specify the versions of Python 3 supported by the package. When not
specified, they default to all currently supported Python (or Python 3)
versions.
They are 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
XS-Python-Version: A.B, X.Y
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 "all" is limited to Python versions and
must be ignored for Python 3 versions. Lists of multiple individual
versions (e.g. 2.4, 2.5, 2.6) work for <tt>XS-Python-Version</tt> and
will continue to be supported, but are not recommended and will not
be supported by <tt>X-Python-Version</tt> or <tt>X-Python3-Version</tt>
after the Squeeze release.
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). It must be ignored for Python 3
The use of XB-Python-Version in the binary package paragraphs of
debian/control file has been deprecated and should be removed in the
normal course of package updates. It never achieved sufficient
deployment to support it's intended purpose of managing Python
transitions. This can be adequately accomplished by examining
package dependencies.
</p>
<p>
If your package is used by another module or application
that requires a specific Python version, it should also
<tt>Provide: python<var>X</var>.<var>Y</var>-foo</tt> for
each version it supports.
<sect id="dependencies">
<heading>Dependencies</heading>
Packaged modules available for the default Python version
(or many versions including the default) as described
in <ref id="package_names"> must depend on "<package>python
(>= <var>X</var>.<var>Y</var></package>)". If they
require other modules to work, they must depend on the
corresponding <package>python-foo</package>. They must not
depend on
any <package>python<var>X</var>.<var>Y</var>-foo</package>.
</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="provides">
<heading>Provides</heading>
<p>
Provides in binary packages of the form
<package>python-<var>foo</var></package> 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. Provides
are only for extensions, not modules.
<sect id="byte_compilation">
<heading>Modules Byte-Compilation</heading>
If a binary package provides any binary-independent modules
(<file>foo.py</file> files), the corresponding byte-compiled
modules (<file>foo.pyc</file> files) and optimized modules
(<file>foo.pyo</file> 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 <file>foo.pyc</file> and
<file>foo.pyo</file> are removed.
</p>
<p>
A binary package should only byte-compile the files which belong to
the package.
</p>
<p>
The file <file>/etc/python/debian_config</file> 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.
<chapt id="programs">
<heading>Python Programs</heading>
<sect id="version_indep_progs">
<heading>Programs using the default python</heading>
<p>
Programs that can run with any version of Python must
begin with <tt>#!/usr/bin/python</tt> or <tt>#!/usr/bin/env
python</tt> (the former is strongly preferred). They must also
specify a dependency on <package>python</package>, with a
versioned dependency if necessary.
If the program needs the python module <tt>foo</tt>,
it must depend on the real package providing this module, usually
<package>python-foo</package> but this name might vary when the
package ships multiple modules.
</p>
<sect1 id="current_version_progs">
<heading>Programs Shipping Private Modules</heading>
<p>
A program using <file>/usr/bin/python</file> as
interpreter can come up with private Python modules. These
<tt>/usr/share/<var>module</var></tt>, or
<tt>/usr/lib/<var>module</var></tt> if the modules are
architecture-dependent (e.g. extensions).
The rules explained in <ref id="byte_compilation"> apply to
those private modules: the byte-compiled modules must not
be shipped with the binary package, they should be generated in
the package's postinst, using the current default Python
version, and removed in the prerm. Modules should be
byte-compiled 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. <tt>Depends: python (>= 2.4), python (<= 2.5)</tt>. No
tools currently exist to alleviate this situation.
</p>
</sect1>
</sect>
<sect id="version_dep_progs">
<heading>Programs Using a Particular Python Version</heading>
<p>
A program which requires a specific version of Python must
begin with
<tt>#!/usr/bin/python<var>X</var>.<var>Y</var></tt> (or
<tt>#!/usr/bin/env python<var>X</var>.<var>Y</var></tt>). It
must also specify a dependency on
<package>python<var>X</var>.<var>Y</var></package> and on
any <package>python<var>X</var>.<var>Y</var>-foo</package>
package providing necessary modules. It should not depend on
any <package>python-foo</package> 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. <tt>Depends: python2.4-foo, python-foo (>=
1.0)</tt>).
The notes on installation directories and byte-compilation
for programs that support any version of Python also apply
to programs supporting only a single Python version. Modules
to be byte-compiled should use the same Python version as the
</p>
</sect>
</chapt>
<chapt id="embed">
<heading>Programs Embedding Python</heading>
<sect id="build_embedded">
<heading>Building Embedded Programs</heading>
<p>
Programs which embed a Python interpreter must declare a
<tt>Build-Depends</tt> on
<package>python<var>X</var>.<var>Y</var>-dev</package>, where
python<var>X</var>.<var>Y</var> is the python version the program
builds against. It should be the current default python version
unless the program does not work correctly with this version.
</p>
</sect>
<sect id="embedded_deps">
<heading>Embedded Python Dependencies</heading>
<p>
Dependencies for programs linking against the shared Python
library will be automatically created by
<prgn>dpkg-shlibdeps</prgn>. The
<tt>libpython<var>X</var>.<var>Y</var>.so.<var>Z</var></tt> library
the program is built against is provided by the
<package>python<var>X</var>.<var>Y</var></package> package.
</p>
</sect>
</chapt>
<chapt id="other">
<heading>Interaction with Locally Installed Python Versions</heading>
<p>
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.
</p>
<p>
If you install a different sub-release of the version of python
you have got installed, you will need to be careful to install all
the modules you use for that version of python too.
</p>
</chapt>
<appendix id="build_dependencies">
<heading>Build Dependencies</heading>
<p>
Build dependencies for Python dependent packages must be
declared for every Python version that the package is built
for. The <package>python-all-dev</package> should be used when
building extensions for any or all Python versions. To build for
a specific version or versions, Build-Depend on
<package>python<var>X</var>.<var>Y</var>-dev</package>.
</p>
<p>
Some applications and pure Python modules may be able to
build-depend only on <package>python</package>
or <package>python-all</package> and not require the -dev
packages. Packages that do not require the -dev packages must not
build-depend on them.
<p>
Build-Depend on at least:
<example>
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
Build-Depends: python3-all-dev (>= 3.1)
<p>
If you use either <package>python-support</package> or
<package>python-central</package> you must additionally
</p>
</appendix>
<appendix id="packaging_tools">
<heading>Packaging Tools</heading>
<p>
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.
</p>
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
<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 does not affect the default installation directory.
</p>
</sect>
<sect id="pysupport">
<heading>python-support</heading>
<p>
The python-support system provides a simple way to
byte-compile pure Python modules and manage dependencies. 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.
See the python-support documentation in
/usr/share/doc/python-support for details.
</p>
</sect>
<sect id="pycentral">
<heading>python-central</heading>
<p>
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.
See the python-central documentation in the pycentral(1) and
dh_pycentral(1) man pages.
</p>
</sect>
<sect id="cdbs">
<heading>CDBS</heading>
<p>
The CDBS python-distutils.mk class helps packaging of setup.py
based Python packages.
</appendix>
<appendix id="upgrade">
<heading>Upgrade Procedure</heading>
<p>
This section describes the procedure for the upgrade when the
default python version is changed in the <tt>unstable</tt>
distribution, requiring recompilation of many python-related
packages.
</p>
<p>
<enumlist>
<item>
<p>
Selected pre-releases and release candidates 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>
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>
<p>
Upload of the python core meta-packages <package>python</package>,
<package>python-dev</package>, <package>python-doc</package> and
several <package>python-<var>module</var></package>, depending on
the new <package>python<var>X</var>.<var>Y</var></package>,
<package>python<var>X</var>.<var>Y</var>-dev</package> and so on.
</p>
</item>
<item>
<p>
The release team schedules rebuilds for packages that
may need it. Packages that require additional manual work get
</p>
</item>
</enumlist>
</p>
</appendix>
</book>
</debiandoc>