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

<!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 - Packaged Modules</title>

<link href="index.html" rel="start">
<link href="ch-python.html" rel="prev">
<link href="ch-programs.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-version_indep_progs" rel="section" title="4.1 Programs using the default python">
<link href="ch-programs.html#s-version_dep_progs" rel="section" title="4.2 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-pysupport" rel="section" title="B.2 python-support (deprecated)">
<link href="ap-packaging_tools.html#s-pycentral" rel="section" title="B.3 python-central (removed)">
<link href="ap-packaging_tools.html#s-cdbs" rel="section" title="B.4 CDBS">
<link href="ap-packaging_tools.html#s-dh_python2_3" rel="section" title="B.5 dh_python2 and dh_python3">
<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.1.1 Programs Shipping Private Modules">

</head>

<body>

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

<p>
[ <a href="ch-python.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch-python3.html">1</a> ]
[ <a href="ch-python.html">2</a> ]
[ 3 ]
[ <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-programs.html">next</a> ]
</p>

<hr>

<h1>
Debian Python Policy
<br>Chapter 3 - Packaged Modules
</h1>

<hr>

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

<hr>

<h2 id="s3.1">3.1 Types of Python Modules</h2>

<p>
There are two kinds of Python modules, &quot;pure&quot; 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 <code>/usr/bin/python<var>X</var>.<var>Y</var></code> 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 <code><a
href="http://docs.python.org/tutorial/modules.html#packages">Python's
documentation</a></code> 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 <a href="ch-python.html#s-paths">Module
Path, Section 2.5</a>.  They are accessible to any program.  Private modules
are installed in a private directory such as
<code>/usr/share/<var>package-name</var></code> or
<code>/usr/lib/<var>package-name</var></code>.  They are generally only
accessible to a specific program or suite of programs included in the same
package.
</p>

<hr>

<h2 id="s-wheels">3.2 Wheels</h2>

<p>
<code><a href="http://legacy.python.org/dev/peps/pep-0427/">PEP 427</a></code>
defines a built-package format called &quot;wheels&quot;, which is a zip format
archive containing Python code and a &quot;dist-info&quot; 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 &quot;import&quot; 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 <code>pip</code> 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 <code>pyvenv</code> and <code>pip</code> are named
with the <var>python-</var> prefix, and the <var>-whl</var> suffix, e.g.
<code>python-chardet-whl</code>.  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 <samp>--universal</samp> flag so as to
generate wheels compatible with both Python 2 and Python 3.
</p>

<hr>

<h2 id="s-package_names">3.3 Module Package Names</h2>

<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
<code>python-<var>foo</var></code>, 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 <code>python-<var>foo.bar</var></code> and
<code>python3-<var>foo.bar</var></code>.  Such a package should support the
current Debian Python version, and more if possible (there are several tools to
help implement this, see <a href="ap-packaging_tools.html">Packaging Tools,
Appendix B</a>).  For example, if Python 2.5, 2.6, and 2.7 are supported, the
Python statement
</p>

<pre>
     import foo
</pre>

<p>
should import the module when the user is running any of
<code>/usr/bin/python2.5</code>, <code>/usr/bin/python2.6</code>, and
<code>/usr/bin/python2.7</code>.  This requirement also applies to extension
modules; binaries for all the supported Python versions should be included in a
single package.
</p>

<hr>

<h2 id="s-specifying_versions">3.4 Specifying Supported Versions</h2>

<p>
The optional <samp>X-Python-Version</samp> (preferred) or
<samp>XS-Python-Version</samp> field in the general paragraph (the first one,
for the source package) of <code>debian/control</code> specifies the versions
of Python (not versions of Python 3) supported by the source package.
Similarly, <samp>X-Python3-Version</samp> 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:
</p>

<pre>
     X-Python-Version: &gt;= X.Y
     X-Python-Version: &gt;= A.B, &lt;&lt; X.Y
     XS-Python-Version: A.B, X.Y
     XS-Python-Version: all
</pre>

<p>
The keyword &quot;all&quot; means that the package supports any Python version
available but might be deprecated in the future since using version numbers is
clearer than &quot;all&quot; and encodes more information.  The keyword
&quot;all&quot; 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
<samp>XS-Python-Version</samp> and will continue to be supported, but are not
recommended and are not supported by <samp>X-Python-Version</samp> or
<samp>X-Python3-Version</samp> for Wheezy and later releases.  The keyword
&quot;current&quot; 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>

<hr>

<h2 id="s-dependencies">3.5 Dependencies</h2>

<p>
Packaged modules available for the default Python version (or many versions
including the default) as described in <a href="#s-package_names">Module
Package Names, Section 3.3</a> must depend on &quot;<code>python
(&gt;=&nbsp;<var>X</var>.<var>Y</var></code>)&quot;.  If they require other
modules to work, they must depend on the corresponding <code>python-foo</code>.
They must not depend on any <code>python<var>X</var>.<var>Y</var>-foo</code>.
</p>

<p>
Packaged modules available for one particular version of Python must depend on
the corresponding <code>python<var>X</var>.<var>Y</var></code> package instead.
If they need other modules, they must depend on the corresponding
<code>python<var>X</var>.<var>Y</var>-foo</code> packages, and must not depend
on any <code>python-foo</code>.
</p>

<hr>

<h2 id="s-provides">3.6 Provides</h2>

<p>
Provides in binary packages of the form
<code>python-<var>X</var>.<var>Y</var><var>&gt;foo</var></code> 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>

<hr>

<h2 id="s-byte_compilation">3.7 Modules Byte-Compilation</h2>

<p>
If a binary package provides any binary-independent modules
(<code>foo.py</code> files), the corresponding byte-compiled modules
(<code>foo.pyc</code> files) and optimized modules (<code>foo.pyo</code> 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 <code>foo.pyc</code> and <code>foo.pyo</code> are
removed.
</p>

<p>
A binary package should only byte-compile the files which belong to the
package.
</p>

<p>
The file <code>/etc/python/debian_config</code> 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>

<hr>

<p>
[ <a href="ch-python.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch-python3.html">1</a> ]
[ <a href="ch-python.html">2</a> ]
[ 3 ]
[ <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-programs.html">next</a> ]
</p>

<hr>

<p>
Debian Python Policy
</p>

<address>
version 0.10.0.2<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>
<br>
</address>
<hr>

</body>

</html>
python 2.7.11-1 / usr / share / doc / python / python-policy.html / ch-module_packages.html
