Differences between revisions 21 and 22
Revision 21 as of 2013-09-25 20:46:26
Size: 7309
Comment: update dh_python2.rst link; drop PyDist one
Revision 22 as of 2015-06-19 09:09:59
Size: 7424
Comment: link pysupport-deprecation in the BTS
Deletions are marked like this. Additions are marked like this.
Line 62: Line 62:
 * The python-support deprecation is not yet tracked.  * The python-support deprecation is [[https://bugs.debian.org/cgi-bin/pkgreport.cgi?tag=pysupport-deprecation;users=debian-python@lists.debian.org|tracked in the BTS]]

Transition to dh_python2

Rationale: The two traditionally popular Python helpers, python-support and python-central have both been deprecated in favor of dh_python2. This page explains how to convert your existing pycentral or pysupport packages to dh_python2.

Before you begin

  • Check if you can do the conversion. All packages that use the same namespace have to be converted at the same time(1). Be sure to use Breaks or Depends relationships to ensure you cannot mix installation of python-support-based packages with dh_python2-based ones.

    • apt-file search -lx '(packages|pyshared|python-support/[^/]+)/foo/' might help finding packages with the same namespace (replace foo with your namespace).

  • A trick would be inserting the following code snippet in the namespace's __init__.py of the package coming first in sys.path: http://docs.python.org/library/pkgutil.html#pkgutil.extend_path

Common recommendations

  • debian/control

    • Replace python-central or python-support with dh-python in Build-Depends

    • Bump minimum required python-all (or python, python-dev, python-all-dev) package version to 2.6.6-3~

      • (read /usr/share/doc/python/changelog.Debian.gz to check if you need a newer version)
    • Remove all XB-Python-Version lines

    • If you use CDBS bump the minimum required cdbs version to 0.4.90~

    • XS-Python-Version is still supported, but X-Python-Version is preferred. It supports the same syntax, except current and all keywords are gone. If you don't know what the package's minimum required Python version is, don't add this field until a bug report informs you that foo doesn't work with an older Python version.

  • debian/rules

    • Remove the DEB_PYTHON_SYSTEM line, e.g.

      • For python-support, run sed -i -e '/DEB_PYTHON_SYSTEM[[:space:]]*[?:]*=[[:space:]]*pysupport/d' debian/rules

      • For python-central, run sed -i -e '/DEB_PYTHON_SYSTEM[[:space:]]*[?:]*=[[:space:]]*pycentral/d' debian/rules

    • If you are using CDBS and any of the modules are in a (Debian binary) package whose name isn't "python-*", set DEB_PYTHON2_MODULE_PACKAGES to the space-separated list of (Debian binary) package names you're building.

    • If you use dh sequencer, add python2 to dh's --with

    • If you use pure debhelper, replace the old helper with dh_python2, e.g.

      • For python-support, run sed -i -e 's/dh_pysupport/dh_python2/' debian/rules

      • For python-central, run sed -i -e 's/dh_pycentral/dh_python2/' debian/rules

  • Check if debian/*.install and other files need additions. dh_python2 ships the actual files in /usr/share/pyshared, plus the symlinks in /usr/lib/python2.x/*-packages.

  • debian/pyversions

    • Remove this file.
    • Use X-Python-Version in debian/control instead (see above, and also policy for syntax, example: ">= 2.5")

  • debian/pycompat

    • Remove this file (this should have been done long ago).

Special cases

  • If you depend on python-support's "namespace feature", remember to provide the namespace's __init__.py file in only one binary package. If you cannot use an existing binary package, create a new binary package, e.g. python-foo-common to hold the namespace's __init__.py file. dh_python2 will include all __init__.py files, even empty ones (unless the namespace is listed in namespace_packages.txt or added via --namespace).

  • Some packages include /usr/share/pycentral-data/pycentral.mk for its sitedir definition. py_libdir from /usr/share/python/python.mk serves the same purpose, but note that it includes the /usr/lib/pythonX.Y/ prefix.

  • DH_PYCENTRAL=include-links can be dropped; dh_python2 does this by default.

  • DH_PYCENTRAL=nomove can be dropped; dh_python2 does this by default, except that it replaces files with symlinks to pyshared if they can be shared between Python versions.

  • If you have both public and private modules, and your rules file runs dh_python2 explicitly, you'll need to run it twice, since the compilation of public and private modules are done separately. See the manpage for details, e.g.

    • dh_python2

    • dh_python2 /path/to/private/dir

  • python-support's debian/package.private files are not supported, add dh_python2 private_dir (next to dh_python2 call) to debian/rules instead

  • If you have extension modules, and a setup.py that builds them, dh will do the right thing unless your package also has a top-level Makefile. The Makefile will be used instead of setup.py, so you'll need to override this by adding a --buildsystem python_distutils to your dh line. Also, be sure to Build-Depend on python-all or python-all-dev to build it for all supported Pythons.

Helpful hints

  • Be careful to run a test build! In some cases this reveals new dependencies, because dh_python2 guesses dependencies from egg-info metadata, so if that metadata is wrong then new dependencies may appear. Sometimes the correct fix is to fix the metadata; in other cases the path of least resistance may be to use dh_python2 --no-guessing-deps.

  • Build the package both before and after your conversion to dh_python2, then use debdiff on the two .deb files to see the differences in the contents of the packages.

    • TBD: expected changes...


  • dh_python2 was released with squeeze, so your backported package transitions should work in squeeze too.

Bug and Status Tracking


Packages which build-depend on python-central and python-support



(1) This is because of the way namespace packages __init__.py files are handled. Until PEP 382 or 402 lands (which won't help Python 2 at all), you have package collisions for namespace __init__.py files. Each Python packaging regime has its own way of handling this and you don't want conflicting regimes or you're just asking for trouble. Thus all packages which share a namespace must use the same Python helper.