<!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>
      <version>version 0.10.0.2</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&mdash;2014 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 is available as
	  <tt>/usr/share/common-licences/GPL</tt> in the Debian GNU/Linux
	  distribution or on the World Wide Web at
	  <url id="http://www.gnu.org/copyleft/gpl.html"
	  name="The GNU General Public License">.
	</p>
	<p>
	  You can also obtain it by writing to the
	  Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
	  Boston, MA 02110-1301, USA.
	</p>
      </copyright>
    </titlepag>

    <toc detail="sect1">

    <chapt id="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="http://legacy.python.org/dev/peps/pep-0404/"
	  name="PEP 404"> states that no more major Python 2 releases
	  are planned, although the last released major version 2.7
	  will see some extended support, documented in 
	  <url id="http://legacy.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 python3
	  should be treated as separate runtime systems with minimal
	  interdependencies.  In some cases, Python policy explicitly references
	  Python helper programs such as python-support and python-central.  None of
	  these references apply to Python 3.  It is a design goal to fully specify
	  required interfaces and functions in policy for Python 3 and to avoid
	  enshrining specific 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 release that can be fully integrated in the distribution.
	  There may be newer supported or unsupported versions included in
	  the distribution if they are not fully integrated for a particular
	  release.
	</p>
	<p>
	  Apart from the default version, legacy versions of Python
	  or beta versions of future releases
	  may be included as well in the distribution, as long as they
	  are needed by other packages, or as long as it seems
	  reasonable to provide them.  (Note: For the scope of this
	  document, Python versions are synonymous to feature
	  releases, i.e. Python 2.7 and 2.7.1 are sub-minor versions of
	  the same Python version 2.7, but Python 2.6 and 2.7 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 set of
	  currently supported python3 versions can be found
	  in <file>/usr/share/python3/debian_defaults</file>.  These
	  files are in
	  Python ConfigParser format and defines four variables in its
	  DEFAULT section: default-version which is the current default
	  Python runtime, supported-versions which is the set of runtimes
	  currently supported and for which modules should be built and
	  byte-compiled, old-versions which is the list of runtimes which
	  might still be on the system but for which should not be built
	  anymore, and unsupported-versions which is the list of runtimes
	  which should not be supported at all, that is modules should not be
	  built or byte-compiled for these.  The supported interface to this
	  file is <file>/usr/bin/pyversions</file>.  The Python 3 interface is
	  through <file>/usr/bin/py3versions</file>.
	</p>
	<p>
	  unsupported-versions is a superset of (includes) old-versions and
	  the default-version is always in supported-versions.
	</p>
	<p>
	  Newer versions might also appear in unsupported-versions before
	  being moved to supported-versions.
	</p>

      </sect>

      <sect id="base">
	<heading>Main packages</heading>
	<p>
	  For every Python version provided in the distribution, the binary
	  package <package>python<var>X</var>.<var>Y</var></package> shall
	  provide a complete distribution for <em>deployment</em> of Python
	  scripts and applications. The package must ensure that the binary
	  <file>/usr/bin/python<var>X</var>.<var>Y</var></file> is provided.
	</p>
	<p>
	  Installation of <package>python<var>X</var>.<var>Y</var></package>
	  shall provide the modules of the upstream Python distribution with
	  some exceptions.
	</p>
	<p>
	  Excluded are modules  that cannot be included for licensing
	  reasons (for example the profile module), for dependency tracking
	  purposes (for example the GPL-licensed gdbm module) or that should
	  not be included for packaging reasons (for example the tk module
	  which depends on Xorg).

	  Some tools and files for the <em>development</em> of Python
	  modules are split off in a separate binary package
	  <package>python<var>X</var>.<var>Y</var>-dev</package>.

	  Documentation will be provided separately as well.
	</p>
	<p>
	  At any time, the <package>python</package> binary package must
	  ensure that <file>/usr/bin/python</file> is provided as a symlink
	  to the current <file>python<var>X</var>.<var>Y</var></file>
	  executable.

	  The <package>python</package> binary package must also depend on
	  the appropriate <package>python<var>X</var>.<var>Y</var></package>
	  to ensure this runtime is installed.
	</p>
	<p>
	  The version of the <package>python</package> binary package must
	  be greater than or equal to <var>X</var>.<var>Y</var> and smaller
	  than <var>X</var>.<var>Y+1</var>.
	</p>
	<p>
	  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="http://www.python.org/dev/peps/pep-0394/" name="PEP-0394">
	  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 the distribution, the
	  binary package
	  <package>python<var>X</var>.<var>Y</var></package>-minimal might
	  exist and should not be depended upon by other packages except the
	  Python runtime packages themselves.
	</p>
      </sect>

      <sect id="interpreter">
        <heading>Python Interpreter</heading>
        <sect1 id="interpreter_name">
          <heading>Interpreter Name</heading>
          <p>
	    Python scripts depending on the default Python version (see <ref
	    id="base">) or not depending on a specific Python version should
	    use <file>python</file> (without a version) as the interpreter name.
	    </p>
          <p>
	    Python scripts that only work with a specific Python version must
	    explicitly use the versioned interpreter name
	    (<file>python<var>X</var>.<var>Y</var></file>).
          </p>
        </sect1>
        <sect1 id="interpreter_loc">
          <heading>Interpreter Location</heading>
          <p>
	    The preferred specification for the Python interpreter is
            <file>/usr/bin/python</file> or
            <file>/usr/bin/python<var>X</var>.<var>Y</var></file>.
	    This ensures that a Debian installation of python is used
	    and all dependencies on additional python modules are met.
          </p>
          <p>
	    Maintainers should 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 PYTHONPATH environment variable and in the sys.path Python
	  variable.  Since python2.4 version 2.4.5-3, python2.5 version
	  2.5.2-7, python2.6 version 2.6.2-1, and in all python2.7 versions,
          sys.path does not include a
	  /usr/lib/python<var>X</var><var>Y</var>.zip entry anymore.

	  Directories with private Python modules must be absent from the
	  sys.path.

	  Public Python modules not handled by python-central or
	  python-support must be installed in the system Python modules
	  directory, /usr/lib/python<var>X</var>.<var>Y</var>/dist-packages
	  for python2.6 and later, and
	  /usr/lib/python<var>X</var>.<var>Y</var>/site-packages for
	  python2.5 and earlier. Public Python 3 modules must be installed in
	  /usr/lib/python3/dist-packages.

	  Modules managed by python-support are installed in another
	  directory which is added to the sys.path using the .pth mechanism.
	  The .pth mechanism is documented in the Python documentation of the
	  <tt>site</tt> module.

	  A special directory is dedicated to public Python modules
	  installed by the local administrator,
	  /usr/lib/python3/dist-packages for all python3 versions, 
	  /usr/local/lib/python2.<var>Y</var>/dist-packages for python2.6 and
	  later, and /usr/local/lib/python2.<var>Y</var>/site-packages for
	  python2.5 and earlier.

	  For a local installation by the administrator of python2.6 and
	  later, a special directory is reserved to Python modules which
	  should only be available to this Python,
	  /usr/local/lib/python2.<var>Y</var>/site-packages (and
	  /usr/local/lib/python3/site-packages for all python3 versions).
	  Unfortunately, for python2.5 and earlier this directory is also
	  visible to the system Python.

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

	<p>
	  When binary packages ship identical source code for multiple
	  Python versions, for instance
	  /usr/lib/python2.6/dist-packages/foo.py and
	  /usr/lib/python2.5/site-packages/foo.py, these should point to a
	  common file. Version specific directories for identical source code
          are not required for python3 and must not be used for this.

	  Since python2.7 is the last python2 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 /usr/share/pyshared.  For
          python2.7, use of /usr/lib/python2.7/dist-packages is sufficient.
          For python3, a special location is not required, use
	  /usr/lib/python3/dist-packages
	</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.

	  This mechanism is required to handle changes of the default Python
	  runtime in some packages and to enable the Python packaging
	  helpers.

	  There are three supported hook types which come in the form of
	  scripts which are invoked from the maintainer scripts of the
	  Python runtime packages when specific installations,
	  removals, or upgrades occur.
	</p>
	<p><enumlist>
	  <item>
	    <p>
	      /usr/share/python/runtime.d/*.rtinstall: these are called when
	      a runtime is installed or becomes supported.  The first
	      argument is "rtinstall", the second argument is the affected
	      runtime (for example python<var>X</var>.<var>Y</var>) and the
	      third and fourth argument are the old and new version of this
	      packaged runtime if this runtime was already installed but
	      unsupported.
	    </p>
	  </item>
	  <item>
	    <p>
	      /usr/share/python/runtime.d/*.rtremove: these are called when
	      a runtime is removed or stops being supported.  The first
	      argument is "rtremove", and the second argument is the
	      affected runtime (for example
	      python<var>X</var>.<var>Y</var>).
	    </p>
	  </item>
	  <item>
	    <p>
	      /usr/share/python/runtime.d/*.rtupdate: these are called when
	      the default runtime changes.  The first argument is either
	      "pre-rtupdate", called before changing the default runtime, or
	      "rtupdate", called when changing the default runtime, or
	      "post-rtupdate", called immediately afterwards.  The second
	      argument is the old default runtime (for example
	      python<var>X</var>.<var>Y</var>), and the third argument is
	      the new default runtime (for example
	      python<var>X</var>.<var>Z</var>).
	    </p>
	  </item>
	</enumlist></p>
      </sect>

      <sect id="docs">
	<heading>Documentation</heading>
	<p>
	  Python documentation is split out in separate binary packages
	  <package>python<var>X</var>.<var>Y</var>-doc</package>. The binary
	  package <package>python-doc</package> will always provide the
	  documentation for the default Debian Python version.
	</p>
	<p>
	  TODO: Policy for documentation of third party packages.
	</p>
      </sect>
    </chapt>

    <chapt id="module_packages">
      <heading>Packaged Modules</heading>
      <p>
	The goal of these policies is to reduce the work necessary for
	Python transitions. Python modules are internally very
	dependent on a specific Python version. However, we want to
	automate recompiling modules when possible, either during the
	upgrade itself (re-byte-compiling pyc and pyo files) or shortly
	thereafter with automated rebuilds (to handle C
	extensions). These policies encourage automated dependency
	generation and loose version bounds whenever possible.
      <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.

	  Some distributions link extensions to libpython, but this is not
	  the case in Debian as symbols might as well be resolved by
	  <file>/usr/bin/python<var>X</var>.<var>Y</var></file> which is not
	  linked to libpython.
	</p>
	<p>
	  Python packages are a way of structuring Python’s module namespace
	  by using “dotted module names”.  See 
	  <url id="http://docs.python.org/tutorial/modules.html#packages"
	  name="Python's documentation"> 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="http://legacy.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 "dist-info" metadata
          directory, in a single file named with the .whl 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 "import"
          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 sys.path, cannot be easily grepped, and stack traces
          through zips 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): chardet, distlib, html5lib, python-colorama,
          python-pip, python-setuptools, python-urllib3, requests, and six.
        </p><p>
          Wheel packages supporting <prgn>pyvenv</prgn> and <prgn>pip</prgn>
          are named with the <var>python-</var> prefix, and the <var>-whl</var>
          suffix, e.g. <package>python-chardet-whl</package>.  When these
          binary packages are installed, their .whl files must be placed in
          the /usr/share/python-wheels 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 <var>python-</var>.  It is recommended
	  to use this prefix for all packages with public modules as they may
	  be used by other packages in the future.  Python 3 modules must be
	  in a separate binary package prefixed with <var>python3-</var> to
	  preserve run time separation between python and python3.

	  The binary package for module foo should preferably be named
	  <package>python-<var>foo</var></package>, if the module name
	  allows, but this is not required if the binary package ships
	  multiple modules.  In the latter case the maintainer chooses the
	  name of the module which represents the package the most.

          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>.

	  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> specifies the
	  versions of Python (not versions of Python 3) supported by the
	  source package. Similarly, <tt>X-Python3-Version</tt> is used to
	  specify the versions of Python 3 supported by the package.  When not
	  specified, they default to all currently supported Python (or Python 3)
	  versions.

	  They are used by some packaging scripts to automatically generate
	  appropriate Depends and Provides lines. The format of the
	  field may be one of the following:
	  <example>
X-Python-Version: >= X.Y
X-Python-Version: >= A.B, << X.Y
XS-Python-Version: A.B, X.Y
XS-Python-Version: all
	  </example>
	  The keyword "all" means that the package supports any Python
	  version available but might be deprecated in the future since
	  using version numbers is clearer than "all" and encodes more
	  information.  The keyword "all" is limited to Python versions and
	  must be ignored for Python 3 versions. Lists of multiple individual
	  versions (e.g. 2.4, 2.5, 2.6) work for <tt>XS-Python-Version</tt> and
	  will continue to be supported, but are not recommended and are not
	  supported by <tt>X-Python-Version</tt> or <tt>X-Python3-Version</tt>
	  for Wheezy and later releases.

	  The keyword "current" has been deprecated and used to mean that
	  the package would only have to support a single version (even
	  across default version changes).  It must be ignored for Python 3
	  versions. 
	</p>
	<p>
	  The use of XB-Python-Version in the binary package paragraphs of
	  debian/control file has been deprecated and should be removed in the
	  normal course of package updates. It never achieved sufficient
	  deployment to support it's intended purpose of managing Python
          transitions.  This can be adequately accomplished by examining
	  package dependencies.
	</p>
      </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 depend on "<package>python
	  (&gt;=&nbsp;<var>X</var>.<var>Y</var></package>)". If they
	  require other modules to work, they must depend on the
	  corresponding <package>python-foo</package>. They must not
	  depend on
	  any <package>python<var>X</var>.<var>Y</var>-foo</package>.
	</p>
	<p>
	  Packaged modules available for one particular version of Python must
	  depend on the corresponding
	  <package>python<var>X</var>.<var>Y</var></package> package instead.
	  If they need other modules, they must depend on the corresponding
	  <package>python<var>X</var>.<var>Y</var>-foo</package> packages, and
	  must not depend on any <package>python-foo</package>.
	</p>
      </sect>

      <sect id="provides">
	<heading>Provides</heading>
	<p>
          Provides in binary packages of the form
          <package>python-<var>X</var>.<var>Y</var><var>>foo</var></package>
	  must be specified if the package contains an extension for more
	  than one python version and an other package with version specific
	  dependencies on the package require it.  Provides are only for
	  extensions, not modules.  Provides should only be rarely used for
          Python packages and never for Python 3.
	</p>
      </sect>

      <sect id="byte_compilation">
        <heading>Modules Byte-Compilation</heading>
	<p>
	  If a binary package provides any binary-independent modules
	  (<file>foo.py</file> files), the corresponding byte-compiled
	  modules (<file>foo.pyc</file> files) and optimized modules
	  (<file>foo.pyo</file> files) must not ship in the
	  package. Instead, they should be generated in the package's
	  postinst, and removed in the package's prerm. The package's
	  prerm has to make sure that both <file>foo.pyc</file> and
	  <file>foo.pyo</file> are removed.
	</p>
	<p>
          A binary package should only byte-compile the files which belong to
          the package.
	</p>
	<p>
          The file <file>/etc/python/debian_config</file> allows
          configuration how modules should be byte-compiled. The
          postinst scripts should respect these settings.
	</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.

	  Public Python extensions should be bin-NMUed.

	  Private Python extensions should be subject to binary NMUs every
	  time the default interpreter changes, unless the extension is
	  updated through a .rtupdate script.
	</p>
      </sect>
    </chapt>

    <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
	    <tt>/usr/share/<var>module</var></tt>, or
	    <tt>/usr/lib/<var>module</var></tt> 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 postinst, using the current default Python
	    version, and removed in the prerm. 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.6), python (<< 2.7)</tt>. No 
	    tools currently exist to alleviate this situation.
	  </p>
	</sect1>
      </sect>

      <sect id="version_dep_progs">
	<heading>Programs Using a Particular Python Version</heading>
	<p>
	  A program which requires a specific version of Python must
	  begin with
	  <tt>#!/usr/bin/python<var>X</var>.<var>Y</var></tt> (or
	  <tt>#!/usr/bin/env python<var>X</var>.<var>Y</var></tt>). It
	  must also specify a dependency on
	  <package>python<var>X</var>.<var>Y</var></package> and on
	  any <package>python<var>X</var>.<var>Y</var>-foo</package>
	  package providing necessary modules. It should not depend on
	  any <package>python-foo</package> package, unless it
	  requires a specific version of the package (since virtual
	  packages cannot be versioned). If this is the case, it
	  should depend on both the virtual package and the main
	  package (e.g. <tt>Depends: python2.7-foo, python-foo (>=
	  1.0)</tt>).
	</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 a
	  <tt>Build-Depends</tt> on
	  <package>python<var>X</var>.<var>Y</var>-dev</package>, where
	  python<var>X</var>.<var>Y</var> is the python version the program
	  builds against. It should be the current default python version
	  unless the program does not work correctly with this version.
	</p>
      </sect>

      <sect id="embedded_deps">
	<heading>Embedded Python Dependencies</heading>
	<p>
	  Dependencies for programs linking against the shared Python
	  library will be automatically created by
	  <prgn>dpkg-shlibdeps</prgn>. The
	  <tt>libpython<var>X</var>.<var>Y</var>.so.<var>Z</var></tt> library
	  the program is built against is provided by the
	  <package>python<var>X</var>.<var>Y</var></package> package.
	</p>
      </sect>
    </chapt>

    <chapt id="other">
      <heading>Interaction with Locally Installed Python Versions</heading>
      <p>
	As long as you don't install other versions of Python in your
	path, Debian's Python versions won't be affected by a new
	version.
      </p>
      <p>
	If you install a different sub-release of the version of python
	you have got installed, you will need to be careful to install all
	the modules you use for that version of python too.
      </p>

    </chapt>

    <appendix id="build_dependencies">
      <heading>Build Dependencies</heading>
      <p>
	Build dependencies for Python dependent packages must be
	declared for every Python version that the package is built
	for. The <package>python-all-dev</package> should be used when
	building extensions for any or all Python versions. To build for
	a specific version or versions, Build-Depend on
	<package>python<var>X</var>.<var>Y</var>-dev</package>.
      </p>
      <p>
	Some applications and pure Python modules may be able to
	build-depend only on <package>python</package>
	or <package>python-all</package> and not require the -dev
	packages. Packages that do not require the -dev packages must not
	build-depend on them.
      </p>

      <p>
	Build-Depend 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: python2.6-dev (>= 2.6-1)
Build-Depends: python-dev (>= 2.6.6-9)
Build-Depends: python-all-dev
Build-Depends: python3-all-dev (>= 3.2)
	</example>
      </p>
      <p>
	If you use either <package>python-support</package> or
	<package>python-central</package> you must additionally
	Build-Depend on those. 
      </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 distutils module has been modified in Debian to
	  change the default installation directory of public Python modules
	  and to add a new flag to the "install" command to override the
	  default, <prgn>--install-layout=</prgn>.

	  To allow the use this flag, maintainers should ensure that at
	  least version 2.6.2-1 will be used for python2.6, version 2.5.4-1
	  for python2.5, and version 2.4.6-2 for python2.4.  This flag is
	  parsed but ignored in python2.4 and python2.5.

	  Public Python modules installed with a modified distutils default
	  to /usr/local/lib/python<var>X</var>.<var>Y</var>/dist-packages
	  for python2.6 and later.  This directory is seen by the
	  system-provided python2.6.

	  When using a system-provided python2.4 or python2.5, the default
	  is /usr/lib/python<var>X</var>.<var>Y</var>/site-packages which is
	  seen by the system-provided python2.4 and python2.5 versions, but
	  not by a system-provided python2.6 and later versions.

	  When using a local Python installation, the default is
	  /usr/local/lib/python<var>X</var>.<var>Y</var>/site-packages which
	  is only seen by the local Python installation.

	  Using the <prgn>--install-layout=deb</prgn> flag to the "install"
	  command of <prgn>setup.py</prgn> with a system-provided python2.6 or
	  later versions, Python modules will be installed to
	  /usr/lib/python<var>X</var>.<var>Y</var>/dist-packages which is only
	  seen by the system-provided python, not by a local installation.

	  Using the <prgn>--install-layout=deb</prgn> flag to
	  <prgn>setup.py</prgn> with a system-provided python2.4 or
	  python2.5 does not affect the default installation directory.
	</p>
      </sect>

      <sect id="pysupport">
	<heading>python-support (deprecated)</heading>
	<p>
	  python-support is deprecated. It is a system intended to provide
	  a simple way to byte-compile pure Python modules and manage dependencies.
	  It integrates with <package>debhelper</package>, manages
	  byte-compilation, private modules, integrates with runtime update
	  hooks, and will fill-in the <tt>${python:Depends}</tt>,
	  <tt>${python:Versions}</tt>, and <tt>${python:Provides}</tt>
	  substvars.

	  See the python-support documentation in
	  /usr/share/doc/python-support for details.
	</p>
      </sect>

      <sect id="pycentral">
	<heading>python-central (removed)</heading>
	<p>
	  python-central has been removed from Jessie and later releases.  It
          provided another way to manage Python modules.
	</p>
      </sect>

      <sect id="cdbs">
	<heading>CDBS</heading>
	<p>
	  The CDBS python-distutils.mk class helps packaging of setup.py
	  based Python packages.
	</p>
      </sect>
      <sect id="dh_python2_3">
	<heading>dh_python2 and dh_python3</heading>
	<p>
	 dh_python2 and dh_python3 are <package>debhelper</package> extensions
	 provided as part of Python and Python3 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.

	 See man dh_python2 or man dh_python3 for details.
	</p>

    </appendix>

    <appendix id="upgrade">
      <heading>Upgrade Procedure</heading>
      <p>
	This section describes the procedure for the upgrade when the
	default python version is changed in the <tt>unstable</tt>
	distribution, requiring recompilation of many python-related
	packages.
      </p>
      <p>
	<enumlist>
	  <item>
	    <p>
	      Selected pre-releases and release candidates of new Python
	      versions are uploaded to Experimental to support
	      pre-transition work and testing.
	    </p>
	  </item>
	  <item>
	    <p>
	      Application and module maintainers make sourceful changes where
	      needed to prepare for the new Python version when needed.
	    </p>
	  </item>
	  <item>
	    <p>
	      Have a long and heated discussion.
	    </p>
	  </item>
	  <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 Unstable.
	    </p>
	  </item>
	  <item>
	    <p>
	      Upload of the python core meta-packages <package>python</package>,
	      <package>python-dev</package>, <package>python-doc</package> and
	      several <package>python-<var>module</var></package>, depending on
	      the new <package>python<var>X</var>.<var>Y</var></package>,
	      <package>python<var>X</var>.<var>Y</var>-dev</package> and so on.
	    </p>
	  </item>
	  <item>
	    <p>
	      The release team schedules rebuilds for packages that
	      may need it. Packages that require additional manual work get
	      updated and uploaded.
	    </p>
	  </item>
	</enumlist>
      </p>
    </appendix>
  </book>
</debiandoc>
