Viewing file:  ch-module_packages.html (8.26 KB) -rw-r--r--
Select action/file-type:
 (+) | (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
Debian Python Policy - Packaged Modules
[ previous ]
[ Contents ]
[ 1 ]
[ 2 ]
[ 3 ]
[ 4 ]
[ 5 ]
[ A ]
[ B ]
[ C ]
[ next ]
Debian Python Policy
Chapter 2 - Packaged Modules
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-bytecompiling 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.
2.1 Types of Python Modules
There are two kinds of Python modules, "pure" Python modules, and
extension modules. Pure Python modules are Python source code that works
across many versions of Python. Extensions are C code compiled and linked
against a specific version of the libpython library, and so can only be used by
one version of Python.
Python packages are directories containing at least a __init__.py,
other modules, extensions and packages (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.
There are two ways to distribute Python modules. Public modules are installed
in one of the directories listed in Module
Path, Section 1.4. They are accessible to any program. Private modules
are installed in a directory such as
/usr/share/packagename or
/usr/lib/packagename. They are generally only
accessible to a specific program or suite of programs included in the same
package.
2.2 Module Package Names
Public modules should be packaged with a name of
python-foo, where foo is the name of the
module. Such a package should support the current Debian Python version, and
more if possible (there are several tools to help implement this, see Packaging Tools, Appendix B). For example,
if Python 2.3, 2.4, and 2.5 are supported, the Python command
import foo
should import the module when the user is running any of
/usr/bin/python2.3, /usr/bin/python2.4, and
/usr/bin/python2.5. This requirement also applies to extension
modules; binaries for all the supported Python versions should be included in a
single package.
2.3 Specifying Supported Versions
The XS-Python-Version field in debian/control
specifies the versions of Python supported by the package. This is used to
track packages during Python transitions, and is also used by some packaging
scripts to automatically generate appropriate Depends and Provides lines. The
format of the field may be one of the following:
XS-Python-Version: all
XS-Python-Version: current
XS-Python-Version: current, >= X.Y
XS-Python-Version: >= X.Y
XS-Python-Version: >= A.B, << X.Y
XS-Python-Version: A.B, X.Y
Where "all" means the package supports any Python version available,
and "current" means it supports Debian's current Python version.
Explicit Versions or version ranges can also be used.
Your control file should also have a line:
XB-Python-Version: ${python:Versions}
The python:Versions is substituted by the supported Python versions of the
binary package, based on XS-Python-Version. (If you are not using
dh_python you will need to handle this substitution yourself.) The
format of the field XB-Python-Version is the same as the
XS-Python-Version field for packages not containing extensions.
Packages with extensions must list the versions explicitely.
If your package is used by another module or application that requires a
specific Python version, it should also Provide:
pythonX.Y-foo for each version it supports.
2.4 Dependencies
Packaged modules available for the default Python version (or many versions
including the default) as described in Module
Package Names, Section 2.2 must depend on "python
(>= X.Y)". If they require other
modules to work, they must depend on the corresponding python-foo.
They must not depend on any pythonX.Y-foo.
Packaged modules available for one particular version of Python must depend on
the corresponding pythonX.Y package instead.
If they need other modules, they must depend on the corresponding
pythonX.Y-foo packages, and must not depend
on any python-foo.
2.5 Provides
Provides in packages of the form python-foo must be
specified, if the package contains an extension for more than one python
version. Provides should also be added on request of maintainers who depend on
a non-default python version.
Packaged modules available for one particular version of Python must depend on
the corresponding pythonX.Y package instead.
If they need other modules, they must depend on the corresponding
pythonX.Y-foo packages, and must not depend
on any python-foo.
2.6 Modules Bytecompilation
If a package provides any binary-independent modules (foo.py
files), the corresponding bytecompiled modules (foo.pyc files) and
optimized modules (foo.pyo 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
foo.pyc and foo.pyo are removed.
A package should only byte-compile the files which belong to the package.
The file /etc/python/debian_config allows configuration how
modules should be byte-compiled. The postinst scripts should respect these
settings.
Modules in private installation directories and in
/usr/lib/site-python should be byte-compiled, when the default
python version changes.
[ previous ]
[ Contents ]
[ 1 ]
[ 2 ]
[ 3 ]
[ 4 ]
[ 5 ]
[ A ]
[ B ]
[ C ]
[ next ]
Debian Python Policy
version 0.4.1.0
Neil Schemenauer nas@debian.org
Matthias Klose doko@debian.org
Gregor Hoffleit flight@debian.org
Josselin Mouette joss@debian.org
Joe Wreschnig piman@debian.org
|