<!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>
<author>
<name>Barry Warsaw</name>
<email>barry@debian.org</email>
</author>
<author>
<name>Ben Finney</name>
<email>ben+debian@benfinney.id.au</email>
</author>
<version>version 0.10.1.0</version>
<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–2016 Software in the Public Interest
</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 version 2 is available as
<file>/usr/share/common-licences/GPL-2</file> in the Debian
GNU/Linux system, or on the World Wide Web at
<url id="https://www.gnu.org/licenses/old-licenses/gpl-2.0.html"
name="GNU General Public License, version 2">.
</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="python3">
<heading>On the move to Python 3</heading>
<p>
Debian currently supports two Python stacks, one for Python 2
and one for Python 3. The long term goal for Debian is to
reduce this to one stack, dropping the Python 2 stack at some
time.
<url id="https://www.python.org/dev/peps/pep-0404/"
name="PEP 404"> states that no more major Python 2 releases
are planned, although the latest released minor version 2.7
will see some extended support, documented in
<url id="https://www.python.org/dev/peps/pep-0466/"
name="PEP 466">.
</p>
<p>
Packages in Debian should use Python 3 if Python 3 is
supported. New packages should use Python 3 from the initial
upload, new upstream versions for existing packages should
use Python 3 if the new upstream version supports it.
</p>
<p><enumlist>
<item>
<p>
Programs should use Python 3, and should not be packaged
for Python 2 as well. Python 3 should be used for the
packaging if the packaging scripts use Python.
</p>
</item>
<item>
<p>
Python libraries should be always packaged for Python 3
if supported. Python 2 libraries should be packaged, if
applications found in the reverse dependencies are not
yet supported by Python 3.
</p>
</item>
<item>
<p>
Existing Python 2 libraries should not be dropped before
the last reverse dependency is removed.
</p>
</item>
</enumlist></p>
</chapt>
<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 Python 3 should be treated as separate runtime systems with
minimal interdependencies.
</p>
<p>
In some cases, Python policy explicitly references Python helper
tools. For Debian Stretch, the <package>dh-python</package>
package provides the only such tools; earlier helpers have been
removed from Debian.
</p>
<p>
It is a design goal to fully specify required interfaces and
functions in policy for Python 3 and to avoid enshrining specific
implementation 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.
</p>
<p>
The default Debian Python version should always be the latest
stable upstream version that can be fully integrated in Debian.
There may be newer supported or unsupported versions included in
the Debian if they are not fully integrated for a particular
release.
</p>
<p>
Apart from the default version, legacy versions of Python or beta
releases of future upstream versions may be included as well in
Debian, as long as they are needed by other packages, or as long
as it seems reasonable to provide them.
</p>
<p>
Note: For the scope of this document, a Python version is
synonymous with all micro versions within that minor version. e.g.
Python 3.5.0 and 3.5.1 are micro versions of the same Python
version 3.5, but Python 3.4 and 3.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>; the supported
interface to this information is <prgn>/usr/bin/pyversions</prgn>.
The set of currently supported Python 3 versions can be found
in <file>/usr/share/python3/debian_defaults</file>; the supported
interface to this information is
through <prgn>/usr/bin/py3versions</prgn>.
</p>
<p>
These files are in Python ConfigParser format. They define (in
the <tt>DEFAULT</tt> section) the following options:
<list>
<item><tt>default-version</tt>: The name of the interpreter for
the current default Debian Python.</item>
<item><tt>supported-versions</tt>: The set of interpreter names
currently supported and for which modules should be built and
byte-compiled. This includes <tt>default-version</tt>.</item>
<item><tt>old-versions</tt>: The set of interpreter names which
might still be on the system but for which modules should not
be built.</item>
<item><tt>unsupported-versions</tt>: The set of interpreter
names which should not be supported at all, that is modules
should not be built or byte-compiled for these. This includes
(is a superset of) <tt>old-versions</tt>.</item>
</list>
</p>
<p>
Newer versions might also appear in <tt>unsupported-versions</tt>
before being moved to <tt>supported-versions</tt>.
</p>
</sect>
<sect id="base">
<heading>Main packages</heading>
<p>
For every Python version provided in Debian, 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 <tt>profile</tt> module), for dependency tracking
purposes (for example the GPL-licensed <tt>gdbm</tt> module) or
that should not be included for packaging reasons (for example
the <tt>tk</tt> module which depends on Xorg).
</p>
<p>
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>.
</p>
<p>
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.
</p>
<p>
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>
Because upstream has started providing it, there will be a symlink
for <file>/usr/bin/python2</file> for Wheezy and later releases. See
<url id="https://www.python.org/dev/peps/pep-0394/" name="PEP 394">
for details. Packages must be careful to depend on a sufficient
version of <package>python</package> if they make use of this symlink.
</p>
</sect>
<sect id="minimal">
<heading>Minimal packages</heading>
<p>
For every Python version provided in Debian, the binary package
<package>python<var>X</var>.<var>Y</var>-minimal</package> 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 not override 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 <tt>PYTHONPATH</tt> environment variable and in
the <tt>sys.path</tt> Python variable. For all supported Debian
releases, <tt>sys.path</tt> does not include
a <file>/usr/lib/python<var>X</var><var>Y</var>.zip</file> entry.
</p>
<p>
Directories with private Python modules must be absent from the
<tt>sys.path</tt>.
</p>
<p>
Public Python modules must be installed in the system Python
modules directory,
<file>/usr/lib/python<var>X</var>.<var>Y</var>/dist-packages</file>.
Public Python 3 modules must be installed in
<file>/usr/lib/python3/dist-packages</file>.
</p>
<p>
A special directory is dedicated to public Python modules
installed by the local administrator,
<file>/usr/lib/python3/dist-packages</file> for all Python 3 versions,
<file>/usr/local/lib/python2.<var>Y</var>/dist-packages</file> for
Python 2.
</p>
<p>
For a local installation by the administrator of Python 2, a
special directory is reserved to Python modules which should only
be available to this Python,
<file>/usr/local/lib/python2.<var>Y</var>/site-packages</file> (and
<file>/usr/local/lib/python3/site-packages</file> for all Python 3
versions).
</p>
<p>
Additional information on appending site-specific paths to the
module search path is available in the official documentation of
the <tt>site</tt> module.
</p>
<p>
When binary packages ship identical source code for multiple
Python versions, for instance
<file>/usr/lib/python2.6/dist-packages/foo.py</file> and
<file>/usr/lib/python2.7/dist-packages/foo.py</file>, these should
point to a common file. Version-specific directories for identical
source code are not required for Python 3 and must not be used for
this.
</p>
<p>
Since Python 2.7 is the last Python 2 version and the only
supported version in Wheezy and later releases, a common location
to share arch-independent files across Python versions is no
longer needed. Historically the location for this
was <file>/usr/share/pyshared</file>. For Python 2.7, use
of <file>/usr/lib/python2.7/dist-packages</file> is sufficient.
For Python 3, a special location is not required, use
<file>/usr/lib/python3/dist-packages</file>.
</p>
</sect>
<sect id="runtimes_hooks">
<heading>Hooks for updates to installed runtimes</heading>
<p>
The <package>python</package> binary package has special hooks to
allow other packages to act upon updates to the installed
runtimes.
</p>
<p>
This mechanism is required to handle changes of the default Python
runtime in some packages and to enable the Python packaging
helpers.
</p>
<p>
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.
</p>
<p><enumlist>
<item>
<p>
<file>/usr/share/python/runtime.d/*.rtinstall</file>: These
are called when a runtime is installed or becomes supported.
The first argument is <tt>rtinstall</tt>, the second argument
is the affected runtime (for
example <file>python<var>X</var>.<var>Y</var></file>) 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>
<file>/usr/share/python/runtime.d/*.rtremove</file>: These are
called when a runtime is removed or stops being supported. The
first argument is <tt>rtremove</tt>, and the second argument
is the affected runtime (for example
<file>python<var>X</var>.<var>Y</var></file>).
</p>
</item>
<item>
<p>
<file>/usr/share/python/runtime.d/*.rtupdate</file>: These are
called when the default runtime changes. The first argument is
either <tt>pre-rtupdate</tt>, called before changing the
default runtime, or <tt>rtupdate</tt>, called when changing
the default runtime, or <tt>post-rtupdate</tt>, called
immediately afterwards. The second argument is the old default
runtime (for example
<file>python<var>X</var>.<var>Y</var></file>), and the third
argument is the new default runtime (for example
<file>python<var>X</var>.<var>Z</var></file>).
</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-compiling bytecode files <file>*.pyc</file>
and <file>*.pyo</file>) or shortly thereafter with automated
rebuilds (to handle C extensions). These policies encourage
automated dependency generation and loose version bounds whenever
possible.
<sect>
<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 generally 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.
</p>
<p>
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 <file>libpython</file>.
</p>
<p>
Python packages are a way of structuring Python’s module namespace
by using “dotted module names”. See
<url id="https://docs.python.org/3/glossary.html#term-package"
name="Python's glossary"> for details on how packages are defined
in Python terms (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.
</p>
</sect>
<sect id="wheels">
<heading>Wheels</heading>
<p>
<url id="https://www.python.org/dev/peps/pep-0427/"
name="PEP 427">
defines a built-package format called "wheels", which is a Zip
format archive containing Python code and
a <file>*.dist-info</file> metadata directory, in a single file
named with the <file>.whl</file> suffix. As Zip files, wheels
containing pure Python can be put on sys.path and modules in the
wheel can be imported directly by Python's <tt>import</tt>
statement. (Importing extension modules from wheels is not yet
supported as of Python 3.4.)
</p>
<p>
Except as described below, packages must not build or provide
wheels. They are redundant to the established way of providing
Python libraries to Debian users, take no advantage of
distro-based tools, and are less convenient to use. E.g. they must
be explicitly added to <tt>sys.path</tt>, cannot be easily
grepped, and stack traces through Zip files are more difficult to
debug.
</p>
<p>
A very limited set of wheel packages are available in the archive,
but these support the narrow purpose of enabling
the <prgn>pip</prgn> tool, in a Debian policy compliant way. The
set of packages providing wheels for this purpose are (by source
package name):
<list compact="compact">
<item><package>chardet</package></item>
<item><package>distlib</package></item>
<item><package>html5lib</package></item>
<item><package>python-colorama</package></item>
<item><package>python-pip</package></item>
<item><package>python-setuptools</package></item>
<item><package>python-urllib3</package></item>
<item><package>requests</package></item>
<item><package>six</package></item>
</list>
</p>
<p>
Wheel packages supporting <prgn>pyvenv</prgn> and <prgn>pip</prgn>
are named with the <package>python-</package> prefix, and
the <package>-whl</package> suffix,
e.g. <package>python-chardet-whl</package>. When these binary
packages are installed, their <file>*.whl</file> files must be
placed in the <file>/usr/share/python-wheels</file> directory.
Such wheels must be built with the <tt>--universal</tt> flag so as
to generate wheels compatible with both Python 2 and Python 3.
</p>
</sect>
<sect id="package_names">
<heading>Module Package Names</heading>
<p>
Public modules used by other packages must have their binary
package name prefixed with <package>python-</package>. 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 <package>python3-</package> to preserve run time separation
between Python and Python 3.
</p>
<p>
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.
</p>
<p>
For subpackages such as <var>foo.bar</var>, the recommendation is
to name the binary
packages <package>python-<var>foo.bar</var></package>
and <package>python3-<var>foo.bar</var></package>.
</p>
<p>
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.5,
2.6, and 2.7 are supported, the Python statement
<example>
import foo
</example>
should import the module when the user is running any
of <prgn>/usr/bin/python2.5</prgn>, <prgn>/usr/bin/python2.6</prgn>,
and <prgn>/usr/bin/python2.7</prgn>. This requirement also
applies to extension modules; binaries for all the supported
Python versions should be included in a single package.
</p>
</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> were methods to
specify the versions of Python (not versions of Python 3) supported by the
source package (they are obsolete and can be removed now that there is only
<package>python2.7</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.
</p>
<p>
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>
X-Python3-Version: >= X.Y
X-Python3-Version: >= A.B, << X.Y
XS-Python-Version: A.B, X.Y
XS-Python-Version: all
</example>
</p>
<p>
The keyword <tt>all</tt> means that the package supports any
Python version available but might be deprecated in the future
since using version numbers is clearer than <tt>all</tt> and
encodes more information. The keyword <tt>all</tt> 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 are not supported
by <tt>X-Python-Version</tt> or <tt>X-Python3-Version</tt> for
Wheezy and later releases.
</p>
<p>
The keyword <tt>current</tt> 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
versions.
</p>
<p>
The use of <tt>XB-Python-Version</tt> in the binary package
paragraphs of <file>debian/control</file> file has been deprecated
and should be removed in the normal course of package updates. It
never achieved sufficient deployment to support its intended
purpose of managing Python transitions. This purpose can be
adequately accomplished by examining package dependencies.
</p>
</sect>
<sect id="dependencies">
<heading>Dependencies</heading>
<p>
Packaged modules available for the default Python version (or many
versions including the default) as described
in <ref id="package_names"> must declare <tt>Depends:
python (>= <var>X</var>.<var>Y</var>)</tt>. 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>
All Python module packages and Python 3 binary extension packages must
also declare a maximum version they support as currently built (this
is accomplished by declaring a maximum version constraint strictly
less than one higher than the current maxiumum version, i.e.
<tt>Depends:
python (<< <var>X</var>.<var>Y</var>)</tt>.
</p>
</sect>
<sect id="provides">
<heading>Provides</heading>
<p>
Python Provides in binary packages of the form
<package>python<var>X</var>.<var>Y</var>-<var>foo</var></package>
were never supported for Python 3 and are no longer useful for
Python. They should be removed in the normal course of package
updates. Future provision of values for the substituation variable
<tt>python:Provides</tt> is not guaranteed.
</p>
</sect>
<sect id="byte_compilation">
<heading>Modules Byte-Compilation</heading>
<p>
If a binary package provides any binary-independent modules
(<file><var>foo</var>.py</file> files), the corresponding
byte-compiled modules (<file><var>foo</var>.pyc</file> files) and
optimized modules (<file><var>foo</var>.pyo</file> files) must not
ship in the package. Instead, they should be generated in the
package's post-install script, and removed in the package's
pre-remove script. The package's prerm has to make sure that
both <file><var>foo</var>.pyc</file> and
<file><var>foo</var>.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
post-install scripts should respect these settings.
</p>
<p>
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.
</p>
<p>
Public Python extensions should be bin-NMUed.
</p>
<p>
Private Python extensions should be subject to binary NMUs every
time the default interpreter changes, unless the extension is
updated through a <file>*.rtupdate</file> script.
</p>
</sect>
</chapt>
<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.
</p>
<p>
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 modules should be
installed in <file>/usr/share/<var>module</var></file>, or
<file>/usr/lib/<var>module</var></file> if the modules are
architecture-dependent (e.g. extensions).
</p>
<p>
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 post-install script using the current default Python
version, and removed in the pre-remove script. Modules should be
byte-compiled using the current default Python version.
</p>
<p>
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.7),
python (<< 2.8)</tt>.
</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 providing necessary modules.
</p>
<p>
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
package itself.
</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
<tt>Build-Depends</tt> on
<package>python<var>X</var>.<var>Y</var>-dev</package>, where
<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
<file>libpython<var>X</var>.<var>Y</var>.so.<var>Z</var></file>
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 micro version 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, declare <tt>Build-Depends</tt> on
<package>python<var>X</var>.<var>Y</var>-dev</package>.
</p>
<p>
Some applications and pure Python modules may be able to declare
<tt>Build-Depends</tt> on the runtime <package>python</package>
or <package>python-all</package> package, and not require
the <package>-dev</package> packages. A package that does not
require the <package>-dev</package> packages must not declare
<tt>Build-Depends</tt> on them.
</p>
<p>
Declare <tt>Build-Depends</tt> on at least:
<example>
Build-Depends: python2.7
Build-Depends: python2.6 (>= 2.6-1)
Build-Depends: python (>= 2.6.6-9)
Build-Depends: python-all
Build-Depends: python2.7-dev
Build-Depends: python3.5-dev (>= 3.5.1-1)
Build-Depends: python-dev (>= 2.6.6-9)
Build-Depends: python-all-dev
Build-Depends: python3-all-dev (>= 3.2)
</example>
</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>
<sect id="distutils">
<heading>distutils</heading>
<p>
The standard Python <tt>distutils</tt> module has been modified in
Debian to change the default installation directory of public
Python modules and to add a new flag to the <tt>install</tt>
command to override the default, <tt>--install-layout=</tt>.
</p>
<p>
Public Python modules installed with a modified distutils default
to
<file>/usr/local/lib/python<var>X</var>.<var>Y</var>/dist-packages</file>
for Python 2.6 and later. This directory is seen by the
system-provided Python 2.6.
</p>
<p>
When using a local Python installation, the default is
<file>/usr/local/lib/python<var>X</var>.<var>Y</var>/site-packages</file>
which is only seen by the local Python installation.
</p>
<p>
Using the <tt>--install-layout=deb</tt> flag to
the <tt>install</tt> command of <prgn>setup.py</prgn> with a
system-provided Python 2.6 or later versions, Python modules will
be installed to
<file>/usr/lib/python<var>X</var>.<var>Y</var>/dist-packages</file>
which is only seen by the system-provided Python, not by a local
installation.
</p>
</sect>
<sect id="dh-python">
<heading><package>dh-python</package></heading>
<p>
<package>dh-python</package> provides extensions
for <package>debhelper</package> to make it easier to package
Python modules and extensions. They calculate Python dependencies,
add maintainer scripts to byte compile files, etc. Their use is not
mandatory, but they are recommended by the Python maintainers.
</p>
<p>
See <tt>man dh_python2</tt> or <tt>man dh_python3</tt> for details.
</p>
</sect>
<sect id="pybuild">
<heading>pybuild</heading>
<p>
Pybuild is a Debian Python specific build system that invokes various
build systems for requested Python versions in order to build modules
and extensions. It supports automatically building for multiple Python
and Python 3 versions.
</p>
</sect>
<sect id="cdbs">
<heading>CDBS</heading>
<p>
The CDBS <file>python-distutils.mk</file> class helps packaging of
distutils based Python packages.
</p>
</sect>
<sect id="pysupport">
<heading><package>python-support</package> (removed)</heading>
<p>
<package>python-support</package> provided another way to manage
Python modules. It has been removed from Debian Stretch and later
releases.
</p>
</sect>
<sect id="pycentral">
<heading><package>python-central</package> (removed)</heading>
<p>
<package>python-central</package> provided another way to manage
Python modules. It has been removed from Debian Jessie and later
releases.
</p>
</sect>
</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 Debian <tt>unstable</tt>
release, 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 Debian <tt>experimental</tt> 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 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 <tt>unstable</tt>.
</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 Debian release team schedules rebuilds for packages that
may need it. Packages that require additional manual work get
updated and uploaded.
</p>
</item>
</enumlist>
</p>
<p>
The necessary package builds are typcially done in three phases in
order to keep transitions as smooth as possible. For Python 3, there
is no general need to update architecture all packages for a new
Python 3 version. Only architecture any packages need to be rebuilt.
<enumlist>
<item>
<p>
The new Python 3 version is added to supported versions and
packages that support multiple Python 3 versions are binNMUed.
They now support both the new and older Python 3 versions.
This requires transition assistance from the release team in
the form of a transition tracker and binNMU scheduling, but is
not a transition that can cause entanglements with other
transitions in Debian.
</p>
</item>
<item>
<p>
Once the default Python 3 version is changed, binNMUs are done
for packages that only support one Python 3 version. Some
transient uninstallability is unavoidable. This is a
transition that can entangle other transitions in Debian and
requires more careful coordination with the release team.
</p>
</item>
<item>
<p>
After the old Python 3 version is dropped from supported
versions then packages with multi-version support are binNMUed
again to remove support for the old Python 3 version. This is
not a true transition and only needs a tracker and binNMU
scheduling.
<p>
</item>
</enumlist>
</appendix>
</book>
</debiandoc>
<!--
Local variables:
coding: utf-8
mode: sgml
indent-tabs-mode: t
fill-column: 76
End:
-->
<!-- vim: set fenc=utf-8 ft=sgml ai noet sts=2 sw=2 tw=76 : -->