/usr/share/doc/python/python-policy.html/ch-python.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">

<html>

<head>

<meta http-equiv="content-type" content="text/html; charset=utf-8">

<title>Debian Python Policy - Python Packaging</title>

<link href="index.html" rel="start">
<link href="ch-python3.html" rel="prev">
<link href="ch-module_packages.html" rel="next">
<link href="index.html#contents" rel="contents">
<link href="index.html#copyright" rel="copyright">
<link href="ch-python3.html" rel="chapter" title="1 On the move to Python 3">
<link href="ch-python.html" rel="chapter" title="2 Python Packaging">
<link href="ch-module_packages.html" rel="chapter" title="3 Packaged Modules">
<link href="ch-programs.html" rel="chapter" title="4 Python Programs">
<link href="ch-embed.html" rel="chapter" title="5 Programs Embedding Python">
<link href="ch-other.html" rel="chapter" title="6 Interaction with Locally Installed Python Versions">
<link href="ap-build_dependencies.html" rel="appendix" title="A Build Dependencies">
<link href="ap-packaging_tools.html" rel="appendix" title="B Packaging Tools">
<link href="ap-upgrade.html" rel="appendix" title="C Upgrade Procedure">
<link href="ch-python.html#s-versions" rel="section" title="2.1 Versions">
<link href="ch-python.html#s-base" rel="section" title="2.2 Main packages">
<link href="ch-python.html#s-minimal" rel="section" title="2.3 Minimal packages">
<link href="ch-python.html#s-interpreter" rel="section" title="2.4 Python Interpreter">
<link href="ch-python.html#s-paths" rel="section" title="2.5 Module Path">
<link href="ch-python.html#s-runtimes_hooks" rel="section" title="2.6 Hooks for updates to installed runtimes">
<link href="ch-python.html#s-docs" rel="section" title="2.7 Documentation">
<link href="ch-module_packages.html#s3.1" rel="section" title="3.1 Types of Python Modules">
<link href="ch-module_packages.html#s-wheels" rel="section" title="3.2 Wheels">
<link href="ch-module_packages.html#s-package_names" rel="section" title="3.3 Module Package Names">
<link href="ch-module_packages.html#s-specifying_versions" rel="section" title="3.4 Specifying Supported Versions">
<link href="ch-module_packages.html#s-dependencies" rel="section" title="3.5 Dependencies">
<link href="ch-module_packages.html#s-provides" rel="section" title="3.6 Provides">
<link href="ch-module_packages.html#s-byte_compilation" rel="section" title="3.7 Modules Byte-Compilation">
<link href="ch-programs.html#s-interpreter-directive" rel="section" title="4.1 Interpreter directive (“Shebang”)">
<link href="ch-programs.html#s-version_indep_progs" rel="section" title="4.2 Programs using the default Python">
<link href="ch-programs.html#s-version_dep_progs" rel="section" title="4.3 Programs Using a Particular Python Version">
<link href="ch-embed.html#s-build_embedded" rel="section" title="5.1 Building Embedded Programs">
<link href="ch-embed.html#s-embedded_deps" rel="section" title="5.2 Embedded Python Dependencies">
<link href="ap-packaging_tools.html#s-distutils" rel="section" title="B.1 distutils">
<link href="ap-packaging_tools.html#s-setuptools" rel="section" title="B.2 setuptools">
<link href="ap-packaging_tools.html#s-dh-python" rel="section" title="B.3 dh-python">
<link href="ap-packaging_tools.html#s-pybuild" rel="section" title="B.4 pybuild">
<link href="ap-packaging_tools.html#s-cdbs" rel="section" title="B.5 CDBS">
<link href="ap-packaging_tools.html#s-pysupport" rel="section" title="B.6 python-support (removed)">
<link href="ap-packaging_tools.html#s-pycentral" rel="section" title="B.7 python-central (removed)">
<link href="ch-python.html#s-interpreter_name" rel="subsection" title="2.4.1 Interpreter Name">
<link href="ch-python.html#s-interpreter_loc" rel="subsection" title="2.4.2 Interpreter Location">
<link href="ch-programs.html#s-current_version_progs" rel="subsection" title="4.2.1 Programs Shipping Private Modules">

</head>

<body>

<p><a name="ch-python"></a></p>
<hr>

<p>
[ <a href="ch-python3.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch-python3.html">1</a> ]
[ 2 ]
[ <a href="ch-module_packages.html">3</a> ]
[ <a href="ch-programs.html">4</a> ]
[ <a href="ch-embed.html">5</a> ]
[ <a href="ch-other.html">6</a> ]
[ <a href="ap-build_dependencies.html">A</a> ]
[ <a href="ap-packaging_tools.html">B</a> ]
[ <a href="ap-upgrade.html">C</a> ]
[ <a href="ch-module_packages.html">next</a> ]
</p>

<hr>

<h1>
Debian Python Policy
<br>Chapter 2 - Python Packaging
</h1>

<hr>

<h2 id="s-versions">2.1 Versions</h2>

<p>
At any given time, the binary package <code>python3</code> will represent the
current default Debian Python 3 version; the binary package <code>python</code>
will represent the current default Debian Python 2 version.  As far as is
reasonable, Python 3 and Python 2 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 <code>dh-python</code> 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 2 is the same as Python 3 with the
exception of the different major version number as needed to distinguish them.
</p>

<p>
The default Debian Python version, for each of Python 3 and Python 2, should
always be the latest stable upstream version that can be fully integrated in
Debian.
</p>

<p>
There may be newer supported or unsupported versions included in 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
<code>python<var>X</var>.<var>Y</var></code>.
</p>

<p>
The set of currently supported Python 3 versions can be found in
<code>/usr/share/python3/debian_defaults</code>; the supported interface to
this information is through <code>/usr/bin/py3versions</code>.  The set of
currently supported Python 2 versions can be found in
<code>/usr/share/python/debian_defaults</code>; the supported interface to this
information is <code>/usr/bin/pyversions</code>.
</p>

<p>
These files are in Python <samp>configparser</samp> format.  They define (in
the <samp>DEFAULT</samp> section) the following options:
</p>
<ul>
<li>
<p>
<samp>default-version</samp>: The name of the interpreter for the current
default Debian Python.
</p>
</li>
</ul>
<ul>
<li>
<p>
<samp>supported-versions</samp>: The set of interpreter names currently
supported and for which modules should be built and byte-compiled.  This
includes <samp>default-version</samp>.
</p>
</li>
</ul>
<ul>
<li>
<p>
<samp>old-versions</samp>: The set of interpreter names which might still be on
the system but for which modules should not be built.
</p>
</li>
</ul>
<ul>
<li>
<p>
<samp>unsupported-versions</samp>: 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) <samp>old-versions</samp>.
</p>
</li>
</ul>

<p>
Newer versions might also appear in <samp>unsupported-versions</samp> before
being moved to <samp>supported-versions</samp>.
</p>

<hr>

<h2 id="s-base">2.2 Main packages</h2>

<p>
For every Python version provided in Debian, the binary package
<code>python<var>X</var>.<var>Y</var></code> shall provide a complete
distribution for <em>deployment</em> of Python scripts and applications.  The
package must ensure that the binary
<code>/usr/bin/python<var>X</var>.<var>Y</var></code> is provided.
</p>

<p>
Installation of <code>python<var>X</var>.<var>Y</var></code> 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 <samp>profile</samp> module), for dependency tracking purposes (for example
the GPL-licensed <samp>gdbm</samp> module), or that should not be included for
packaging reasons (for example the <samp>tk</samp> 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
<code>python<var>X</var>.<var>Y</var>-dev</code>.
</p>

<p>
Documentation will be provided separately as well.
</p>

<p>
At any time, the <code>python3</code> binary package must ensure that
<code>/usr/bin/python3</code> is provided, as a symlink to the current
<code>python3.<var>Y</var></code> executable.  The package must depend on the
<code>python3.<var>Y</var></code> package that installs the executable.
</p>

<p>
The version of the <code>python3</code> package must be greater than or equal
to 3.<var>Y</var> and lower than 3.<var>Y+1</var>.
</p>

<p>
At any time, the <code>python</code> binary package must ensure that
<code>/usr/bin/python2</code> is provided, as a symlink to the current
<code>python2.<var>Y</var></code> executable.  The package must depend on the
<code>python2.<var>Y</var></code> package that installs the executable.
</p>

<p>
The version of the <code>python</code> package must be greater than or equal to
2.<var>Y</var> and lower than 2.<var>Y+1</var>.
</p>

<p>
The <code>python</code> binary package must also ensure that
<code>/usr/bin/python</code> is provided, as a symlink to the current
<code>python2.<var>Y</var></code> executable.  See <code><a
href="https://www.python.org/dev/peps/pep-0394/">PEP 394</a></code> for
details.
</p>

<hr>

<h2 id="s-minimal">2.3 Minimal packages</h2>

<p>
For every Python version provided in Debian, the binary package
<code>python<var>X</var>.<var>Y</var>-minimal</code> might exist and should not
be depended upon by other packages except the Python runtime packages
themselves.
</p>

<hr>

<h2 id="s-interpreter">2.4 Python Interpreter</h2>

<hr>

<h3 id="s-interpreter_name">2.4.1 Interpreter Name</h3>

<p>
The different Python major versions require different interpreters (see <a
href="#s-base">Main packages, Section 2.2</a>).
</p>

<p>
Python scripts that require the default Python 3 version should specify
<code>python3</code> as the interpreter name.
</p>

<p>
Python scripts that require the default Python 2 version should specify
<code>python2</code> as the interpreter name.
</p>

<p>
Python scripts may specify <code>python</code> as the interpreter name only if
they do not require any particular version of Python.  (Note: this means any
python2 version)
</p>

<p>
Python scripts that only work with a specific Python minor version must
explicitly use the versioned interpreter name
(<code>python<var>X</var>.<var>Y</var></code>).
</p>

<hr>

<h3 id="s-interpreter_loc">2.4.2 Interpreter Location</h3>

<p>
Python scripts should specify the Debian Python interpreter, to ensure that the
Debian Python installation is used and all dependencies on additional Python
modules are met.
</p>

<p>
The preferred specification for the Python 3 interpreter is
<code>/usr/bin/python3</code> (or <code>/usr/bin/python3.<var>Y</var></code> if
it requires Python 3.<var>Y</var>).
</p>

<p>
The preferred specification for the Python 2 interpreter is
<code>/usr/bin/python2</code> (or <code>/usr/bin/python2.<var>Y</var></code> if
it requires Python 2.<var>Y</var>).
</p>

<p>
Scripts requiring the default Python 2 version may instead specify the
interpreter <code>/usr/bin/python</code>.
</p>

<p>
Maintainers should not override the Debian Python interpreter using
<code>/usr/bin/env <var>name</var></code>.  This is not advisable as it
bypasses Debian's dependency checking and makes the package vulnerable to
incomplete local installations of Python.
</p>

<hr>

<h2 id="s-paths">2.5 Module Path</h2>

<p>
By default, Python modules are searched in the directories listed in the
<samp>PYTHONPATH</samp> environment variable and in the <samp>sys.path</samp>
Python variable.  For all supported Debian releases, <samp>sys.path</samp> does
not include a <code>/usr/lib/python<var>X</var><var>Y</var>.zip</code> entry.
</p>

<p>
Directories with private Python modules must be absent from the
<samp>sys.path</samp>.
</p>

<p>
Public Python 3 modules must be installed in the system Python 3 modules
directory, <code>/usr/lib/python3/dist-packages</code>.
</p>

<p>
Public Python 2 modules must be installed in the system Python 2 modules
directory <code>/usr/lib/python2.<var>Y</var>/dist-packages</code>, where
2.<var>Y</var> is the Python 2 version.
</p>

<p>
A special directory is dedicated to public Python modules installed by the
local administrator, <code>/usr/lib/python3/dist-packages</code> for all Python
3 versions, <code>/usr/local/lib/python2.<var>Y</var>/dist-packages</code> for
Python 2.
</p>

<p>
For local installation of Python modules by the system administrator, special
directories are reserved.  The directory
<code>/usr/local/lib/python3/site-packages</code> is in the Python 3 runtime
module search path.  The directory
<code>/usr/local/lib/python2.<var>Y</var>/site-packages</code> is in the Python
2.<var>Y</var> runtime module search path.
</p>

<p>
Additional information on appending site-specific paths to the module search
path is available in the official documentation of the <samp>site</samp>
module.
</p>

<p>
Python modules which work with multiple supported Python 2 versions must
install to version-specific locations, for instance
<code>/usr/lib/python2.6/dist-packages/foo.py</code> and
<code>/usr/lib/python2.7/dist-packages/foo.py</code>.  These should point to a
common file.
</p>

<p>
Architecture-independent public Python 3 modules must be installed to
<code>/usr/lib/python3/dist-packages</code>.
</p>

<p>
Architecture-independent public Python 2 modules should be installed to
<code>/usr/lib/python2.7/dist-packages</code>.  The historical location for
this was <code>/usr/share/pyshared</code>.  Since Python 2.7 is the last Python
2 version and the only supported version in Wheezy and later releases, a
version-specific location is sufficient.
</p>

<hr>

<h2 id="s-runtimes_hooks">2.6 Hooks for updates to installed runtimes</h2>

<p>
The <code>python</code> 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>
<ol type="1" start="1" >
<li>
<p>
<code>/usr/share/python3/runtime.d/*.rtinstall</code>,
<code>/usr/share/python/runtime.d/*.rtinstall</code>: These are called when a
runtime is installed or becomes supported.  The first argument is
<samp>rtinstall</samp>, the second argument is the affected runtime (for
example <code>python<var>X</var>.<var>Y</var></code>) 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>
</li>
</ol>
<ol type="1" start="2" >
<li>
<p>
<code>/usr/share/python3/runtime.d/*.rtremove</code>,
<code>/usr/share/python/runtime.d/*.rtremove</code>: These are called when a
runtime is removed or stops being supported.  The first argument is
<samp>rtremove</samp>, and the second argument is the affected runtime (for
example <code>python<var>X</var>.<var>Y</var></code>).
</p>
</li>
</ol>
<ol type="1" start="3" >
<li>
<p>
<code>/usr/share/python3/runtime.d/*.rtupdate</code>,
<code>/usr/share/python/runtime.d/*.rtupdate</code>: These are called when the
default runtime changes.  The first argument is either
<samp>pre-rtupdate</samp>, called before changing the default runtime, or
<samp>rtupdate</samp>, called when changing the default runtime, or
<samp>post-rtupdate</samp>, called immediately afterwards.  The second argument
is the old default runtime (for example
<code>python<var>X</var>.<var>Y</var></code>), and the third argument is the
new default runtime (for example <code>python<var>X</var>.<var>Z</var></code>).
</p>
</li>
</ol>

<hr>

<h2 id="s-docs">2.7 Documentation</h2>

<p>
Python documentation is split out in separate binary packages
<code>python<var>X</var>.<var>Y</var>-doc</code>.
</p>

<p>
The binary package <code>python3-doc</code> will always provide the
documentation for the default Debian Python 3 version.  The binary package
<code>python-doc</code> will always provide the documentation for the default
Debian Python 2 version.
</p>

<p>
TODO: Policy for documentation of third party packages.
</p>

<hr>

<p>
[ <a href="ch-python3.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch-python3.html">1</a> ]
[ 2 ]
[ <a href="ch-module_packages.html">3</a> ]
[ <a href="ch-programs.html">4</a> ]
[ <a href="ch-embed.html">5</a> ]
[ <a href="ch-other.html">6</a> ]
[ <a href="ap-build_dependencies.html">A</a> ]
[ <a href="ap-packaging_tools.html">B</a> ]
[ <a href="ap-upgrade.html">C</a> ]
[ <a href="ch-module_packages.html">next</a> ]
</p>

<hr>

<p>
Debian Python Policy
</p>

<address>
version 0.10.1.1<br>
<br>
Neil Schemenauer <code><a href="mailto:nas@debian.org">mailto:nas@debian.org</a></code><br>
Matthias Klose <code><a href="mailto:doko@debian.org">mailto:doko@debian.org</a></code><br>
Gregor Hoffleit <code><a href="mailto:flight@debian.org">mailto:flight@debian.org</a></code><br>
Josselin Mouette <code><a href="mailto:joss@debian.org">mailto:joss@debian.org</a></code><br>
Joe Wreschnig <code><a href="mailto:piman@debian.org">mailto:piman@debian.org</a></code><br>
Lo&iuml;c Minier <code><a href="mailto:lool@debian.org">mailto:lool@debian.org</a></code><br>
Scott Kitterman <code><a href="mailto:scott@kitterman.com">mailto:scott@kitterman.com</a></code><br>
Barry Warsaw <code><a href="mailto:barry@debian.org">mailto:barry@debian.org</a></code><br>
Ben Finney <code><a href="mailto:ben+debian@benfinney.id.au">mailto:ben+debian@benfinney.id.au</a></code><br>
<br>
</address>
<hr>

</body>

</html>
python 2.7.13-2 / usr / share / doc / python / python-policy.html / ch-python.html
