<!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&iuml;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.1</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 &copy; 1999&ndash;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 3
	  and one for Python 2.  The long term goal for Debian is to
	  reduce this to one stack, dropping the Python 2 stack at some
	  time.
	</p>
	<p>
	  <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, if they support Python 3, should be always
	      packaged for Python 3. If an application supports only Python
	      2, the Python libraries for that application should also be
	      packaged for Python 2.
	    </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>python3</package>
	  will represent the current default Debian Python 3 version; the
	  binary package <package>python</package> 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 <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 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
	  <package>python<var>X</var>.<var>Y</var></package>.
	</p>

	<p>
	  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>.
	  The set of currently supported Python 2 versions can be found in
	  <file>/usr/share/python/debian_defaults</file>; the supported
	  interface to this information is <prgn>/usr/bin/pyversions</prgn>.
	</p>
	<p>
	  These files are in Python <tt>configparser</tt> 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>python3</package> binary package must
	  ensure that <file>/usr/bin/python3</file> is provided, as a
	  symlink to the current <file>python3.<var>Y</var></file>
	  executable. The package must depend on
	  the <package>python3.<var>Y</var></package> package that installs
	  the executable.
	</p>
	<p>
	  The version of the <package>python3</package> 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 <package>python</package> binary package must
	  ensure that <file>/usr/bin/python2</file> is provided, as a
	  symlink to the current <file>python2.<var>Y</var></file>
	  executable. The package must depend on
	  the <package>python2.<var>Y</var></package> package that installs
	  the executable.
	</p>
	<p>
	  The version of the <package>python</package> package must be
	  greater than or equal to 2.<var>Y</var> and lower than
	  2.<var>Y+1</var>.
	</p>
	<p>
	  The <package>python</package> binary package must also ensure
	  that <file>/usr/bin/python</file> is provided, as a symlink to the
	  current <file>python2.<var>Y</var></file> executable. See
	  <url id="https://www.python.org/dev/peps/pep-0394/" name="PEP
	  394"> for details.
	</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>
	    The different Python major versions require different
	    interpreters (see <ref id="base">).
	  </p>
	  <p>
	    Python scripts that require the default Python 3 version should
	    specify <file>python3</file> as the interpreter name.
	  </p>
	  <p>
	    Python scripts that require the default Python 2 version should
	    specify <file>python2</file> as the interpreter name.
	  </p>
	  <p>
	    Python scripts may specify <file>python</file> 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
	    (<file>python<var>X</var>.<var>Y</var></file>).
	  </p>
	</sect1>
	<sect1 id="interpreter_loc">
	  <heading>Interpreter Location</heading>
	  <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
	    <file>/usr/bin/python3</file> (or
	    <file>/usr/bin/python3.<var>Y</var></file> if it requires Python
	    3.<var>Y</var>).
	  </p>
	  <p>
	    The preferred specification for the Python 2 interpreter is
	    <file>/usr/bin/python2</file> (or
	    <file>/usr/bin/python2.<var>Y</var></file> if it requires Python
	    2.<var>Y</var>).
	  </p>
	  <p>
	    Scripts requiring the default Python 2 version may instead
	    specify the interpreter <file>/usr/bin/python</file>.
	  </p>
	  <p>
	    Maintainers should not override the Debian Python interpreter
	    using <file>/usr/bin/env <var>name</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 3 modules must be installed in the system Python 3
	  modules directory, <file>/usr/lib/python3/dist-packages</file>.
	</p>
	<p>
	  Public Python 2 modules must be installed in the system Python 2
	  modules directory
	  <file>/usr/lib/python2.<var>Y</var>/dist-packages</file>, 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,
	  <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 local installation of Python modules by the system
	  administrator, special directories are reserved. The
	  directory <file>/usr/local/lib/python3/site-packages</file> is in
	  the Python 3 runtime module search path. The
	  directory <file>/usr/local/lib/python2.<var>Y</var>/site-packages</file>
	  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 <tt>site</tt> module.
	</p>
	<p>
	  Python modules which work with multiple supported Python 2
	  versions must install to version-specific locations, 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.
	</p>
	<p>
	  Architecture-independent public Python 3 modules must be installed
	  to <file>/usr/lib/python3/dist-packages</file>.
	</p>
	<p>
	  Architecture-independent public Python 2 modules should be
	  installed to <file>/usr/lib/python2.7/dist-packages</file>. The
	  historical location for this was <file>/usr/share/pyshared</file>.
	  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>
      </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/python3/runtime.d/*.rtinstall</file>,
	      <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/python3/runtime.d/*.rtremove</file>,
	      <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/python3/runtime.d/*.rtupdate</file>,
	      <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>.
	</p>
	<p>
	  The binary package <package>python3-doc</package> will always
	  provide the documentation for the default Debian Python 3 version.
	  The binary package <package>python-doc</package> will always
	  provide the documentation for the default Debian Python 2 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>
	  Debian Python does not link extensions to <file>libpython</file>
	  (as is done in some operating systems). Symbols are 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>, <prgn>virtualenv</prgn>,
	  and <prgn>pyvenv</prgn> tools in a Debian policy compliant way.
	  These packages build their own dependent wheels through the use of
	  the <prgn>dirtbike</prgn> "rewheeling" tool, which takes installed
	  Debian packages and turns them back into wheels.  Only universal
	  wheels (i.e. pure-Python, Python 3 and 2 compatible packages) are
	  supported.  Since only the programs that require wheels need build
	  them, only they may provide <file>-whl</file> packages,
	  e.g. <package>python3-pip-whl</package>.
	</p>
	<p>
	  When these binary packages are installed, <file>*.whl</file> files
	  must be placed in the <file>/usr/share/python-wheels</file>
	  directory. The location inside a virtual environment will be
	  rooted in the virtual environment, instead of <file>/usr</file>.
	</p>
      </sect>
      <sect id="package_names">
	<heading>Module Package Names</heading>
	<p>
	  Public Python modules must be packages separately by major Python
	  version, to preserve run time separation between Python 2 and
	  Python 3.
	</p>
	<p>
	  Public Python 3 modules used by other packages must have their
	  binary package name prefixed with <package>python3-</package>.
	  Public Python 2 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.
	</p>
	<p>
	  The binary package for module <var>foo</var> should preferably be
	  named <package>python3-<var>foo</var></package> (for Python 3)
	  or <package>python-<var>foo</var></package> (for Python 2), if the
	  module name allows. This is not required if the binary package
	  installs multiple modules, in which case the maintainer shall
	  choose the name of the module which best represents the package.
	</p>
	<p>
	  For subpackages such as <var>foo.bar</var>, the recommendation is
	  to name the binary
	  package <package>python3-<var>foo.bar</var></package> (for Python
	  3) or <package>python-<var>foo.bar</var></package> (for Python 2).
	</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 3.3,
	  3.4, and 3.5 are supported, the Python statement
	  <example>
import foo
	  </example>
	  should import the module when the program interpreter is any
	  of <prgn>/usr/bin/python3.3</prgn>, <prgn>/usr/bin/python3.4</prgn>,
	  and <prgn>/usr/bin/python3.5</prgn>. This requirement also applies
	  to extension modules; binaries for all the supported Python
	  versions should be included in a single package.
	</p>
	<p>
          Packages intended for use with Django (<package>python3-django</package>/
          <package>python-django</package>) are installed in the same namespace as
          other python packages for a variety of reasons.  Many such packages are
          named django_$name upstream.  These are then packaged as
          <package>python3-django-$name</package> and
          <package>python-django-$name</package>.
          This makes it clear that they are intended for use with Django
          and not general purpose Python modules.  Debian maintainers are
          encouraged to work with their upstreams to support consistent use of
          this approach.
      </sect>
      <sect id="specifying_versions">
	<heading>Specifying Supported Versions</heading>
	<p>
	  The <file>debian/control</file> source paragraph may contain
	  optional fields to specify the versions of Python the package
	  supports.
	</p>
	<p>
	  The optional <tt>X-Python3-Version</tt> field specifies the
	  versions of Python 3 supported. When not specified, it defaults to
	  all currently supported Python 3 versions.
	</p>
	<p>
	  Similarly, the optional fields <tt>X-Python-Version</tt>
	  or <tt>XS-Python-Version</tt> were used to specify the versions of
	  Python 2 supported by the source package. They are obsolete and
	  can be removed now that only Python 2.7 is supported.
	</p>
	<p>
	  These fields 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: &gt;= X.Y
X-Python3-Version: &gt;= A.B, &lt;&lt; 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 2 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 2 versions and must be ignored for Python 3 versions.
	</p>
	<p>
	  A comma-separated list of multiple individual versions
	  (e.g. <tt>3.3, 3.4, 3.5</tt>) in <tt>XS-Python-Version</tt> will
	  continue to be supported, but is not recommended. The use of
	  multiple individual versions in <tt>X-Python-Version</tt>
	  or <tt>X-Python3-Version</tt> is not supported 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 Python 2
	  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>
	  Any package that installs modules for the default Python version
	  (or many versions including the default) as described
	  in <ref id="package_names">, must declare a dependency on the
	  default Python runtime package. If it requires other modules to
	  work, the package must declare dependencies on the corresponding
	  packaged modules. The package must not declare dependency on any
	  version-specific Python runtime or module package.
	</p>
	<p>
	  For Python 3, the correct dependencies are <tt>Depends:
	  python3&nbsp;(&gt;=&nbsp;3.<var>Y</var>)</tt> and any
	  corresponding <package>python3-<var>foo</var></package> packages.
	</p>
	<p>
	  For Python 2, the correct dependencies are <tt>Depends:
	  python&nbsp;(&gt;=&nbsp;2.<var>Y</var>)</tt> and any
	  corresponding <package>python-<var>foo</var></package> packages.
	</p>
	<p>
	  Any package that installs Python modules or Python 3 binary
	  extensions must also declare a maximum version it supports as
	  currently built. This is accomplished by declaring a maximum
	  version constraint strictly less than one higher than the current
	  maximum version, i.e. <tt>Depends:
	  python3&nbsp;(&lt;&lt;&nbsp;<var>X</var>.<var>Y</var>)</tt>.
	</p>
      </sect>

      <sect id="provides">
	<heading>Provides</heading>
	<p>
	  Binary packages that declare Provides dependencies 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 2. 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="interpreter-directive">
	<heading>Interpreter directive (“Shebang”)</heading>
	<p>
	  Executables written for interpretation by Python must use an
	  appropraite interpreter directive, or “shebang”, as the first line
	  of the program. This line should be of the
	  form <tt>#!<var>interpreter_location</var></tt>.
	  See <ref id="interpreter_name"> for the interpreter name to use.
	</p>
	<p>
	  As noted in <ref id="interpreter_loc">, the
	  form <tt>#!/usr/bin/env <var>interpreter_name</var></tt> is
	  deprecated.
	</p>
      </sect>

      <sect id="version_indep_progs">
	<heading>Programs using the default Python</heading>
	<p>
	  A package that installs a program that can be run by any version
	  of Python 3 must declare a dependency
	  on <package>python3</package>, with a versioned dependency if
	  necessary.
	</p>
	<p>
	  A package that installs a program that can be run by any version
	  of Python 2 must declare a dependency
	  on <package>python2</package>, with a versioned dependency if
	  necessary.
	</p>
	<p>
	  If the program needs the public Python module <tt>foo</tt>, the
	  package must depend on the binary package that installs
	  the <tt>foo</tt> module. See <ref id="package_names"> for the
	  naming of packages that install public Python modules.
	</p>

	<sect1 id="current_version_progs">
	  <heading>Programs Shipping Private Modules</heading>
	  <p>
	    A program that specifies <prgn>python3</prgn>
	    or <prgn>python</prgn> as its interpreter may require its own
	    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:
	    python3&nbsp;(&gt;=&nbsp;3.5),
	    python3&nbsp;(&lt;&lt;&nbsp;3.6)</tt>.
	  </p>
	</sect1>
      </sect>

      <sect id="version_dep_progs">
	<heading>Programs Using a Particular Python Version</heading>
	<p>
	  A program which requires a specific minor version of Python must
	  specify the versioned
	  interpreter <prgn>python<var>X</var>.<var>Y</var></prgn>. The
	  package that installs the programs must also specify a dependency
	  on
	  <package>python<var>X</var>.<var>Y</var></package> and on any
	  packages that install 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>
	  Any package that installs a program which embeds 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.
      </p>
      <p>
	The <package>python3-all-dev</package> should be used when building
	extensions for any or all Python 3 versions.
	The <package>python-all-dev</package> should be used when building
	extensions for any or all Python 2 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 avoid
	dependency on the <package>-dev</package> packages, and declare
	<tt>Build-Depends</tt> on the runtime environment only
	(<package>python3</package>, <package>python3-all</package>,
	<package>python</package>, <package>python-all</package>). 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 (&gt;= 2.6-1)
Build-Depends: python (&gt;= 2.6.6-9)
Build-Depends: python-all

Build-Depends: python2.7-dev
Build-Depends: python3.5-dev (&gt;= 3.5.1-1)
Build-Depends: python-dev (&gt;= 2.6.6-9)
Build-Depends: python-all-dev
Build-Depends: python3-all-dev (&gt;= 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="setuptools">
        <heading>setuptools</heading>
        <p>
          The related Python <tt>setuptools</tt> module has been modified in
          Debian along the same lines as <tt>distutils</tt>.
        </p>
        <p>
          Upstream focus on developments and improvements for Python packaging
          tools has largely shifted away from <tt>distutils</tt> and to
          <tt>setuptools</tt>.  They offer a similar API and at some point in
          the future, <tt>setuptools</tt> may fully replace <tt>distutils</tt>
          in Debian package builds.
        </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 Debian Python
	  maintainers.
	</p>
	<p>
	  See <tt>man dh_python3</tt> or <tt>man dh_python2</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 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 : -->