dh-python provides various tools that help packaging Python related files in Debian.

• pybuild is a tool that implements dh sequencer's dh_auto_foo commands (but it can be used outside dh as well). It builds and installs files.

• dh_python2 / dh_python3 / dh_pypy are tools that take what pybuild produces and generates runtime dependencies and maintainer scripts. It fixes some common mistakes, like installing files into site-packages instead of dist-packages, /usr/local/bin/ shebangs, removes .py files from -dbg packages, etc.)

  To translate requires.txt (a file installed in dist-packages/foo.egg-info/) into Debian dependencies, a list of packages that provide given egg distribution is used. If the dependency is not found there, dpkg -S is used (i.e. a given dependency has to be installed; you need it in Build-Depends in order to run tests anyway). See dependencies section in dh_python3's manpage for more details.

  • dh_python2 works on ./debian/python-foo/ files and other binary packages that have ${python:Depends} in the Depends field. It ignores Python 3.X and PyPy specific directories. See dh_python2 manpage for more details.
  • dh_python3 works on ./debian/python3-foo/ files and other binary packages that have ${python3:Depends} in the Depends field. It ignores Python 2.X and PyPy specific directories. See dh_python3 manpage for more details.
  • dh_pypy works on ./debian/pypy-foo/ files and other binary packages that have ${pypy:Depends} in the Depends field. It ignores Python 2.X and Python 3.X specific directories. See dh_pypy manpage for more details.

A simplified work flow looks like this:

# dh_auto_clean stage
for interpreter in REQUESTED_INTERPRETERS:
    for version in interpreter.REQUESTED_VERSIONS:
        PYBUILD_BEFORE_CLEAN
        pybuild --clean
        PYBUILD_AFTER_CLEAN

plenty_of_other_dh_foo_tools_invoked_here

# dh_auto_configure stage
for interpreter in REQUESTED_INTERPRETERS:
    for version in interpreter.REQUESTED_VERSIONS:
        PYBUILD_BEFORE_CONFIGURE
        pybuild --configure
        PYBUILD_AFTER_CONFIGURE

plenty_of_other_dh_foo_tools_invoked_here

# dh_auto_build stage
for interpreter in REQUESTED_INTERPRETERS:
    for version in interpreter.REQUESTED_VERSIONS:
        PYBUILD_BEFORE_BUILD
        pybuild --build
        PYBUILD_AFTER_BUILD

plenty_of_other_dh_foo_tools_invoked_here

# dh_auto_test stage
for interpreter in REQUESTED_INTERPRETERS:
    for version in interpreter.REQUESTED_VERSIONS:
        PYBUILD_BEFORE_TEST
        pybuild --test
        PYBUILD_AFTER_TEST

plenty_of_other_dh_foo_tools_invoked_here

# dh_auto_install stage
for interpreter in REQUESTED_INTERPRETERS:
    for version in interpreter.REQUESTED_VERSIONS:
        PYBUILD_BEFORE_INSTALL
        pybuild --install
        PYBUILD_AFTER_INSTALL

plenty_of_other_dh_foo_tools_invoked_here

dh_python2
dh_python3
dh_pypy

plenty_of_other_dh_foo_tools_invoked_here

This command is auto-detected, it currently supports distutils, autotools, cmake and a custom build system where you can define your own set of commands. Why do we need it? dh_auto_foo doesn't know each command has to be invoked for each interpreter and version.

is parsed from Build-Depends if --buildsystem=pybuild is set. If it's not, you have to pass --interpreter to pybuild (more in its manpage)

• python{3,}-all{,-dev} - all CPython interpreters (for packages that provide public modules / extensions)
• python{3,}-all-dbg - all CPython debug interpreters (if -dbg package is provided)
• python{3,} - default CPython or closest to default interpreter only (use this if you build a Python application)
• python{3,}-dbg - default CPython debug (or closest to the default one) only
• pypy - PyPy interpreter

is parsed from X-Python{,3}-Version and Build-Depends (the right X-*-Version is parsed based on interpreters listed in Build-Depends, see above) See also Debian Python Policy for X-Python-Version description.

can be different for each interpreter and/or version, examples:

• PYBUILD_AFTER_BUILD_python3.5=rm {destdir}/{build_dir}/foo/bar2X.py
• PYBUILD_BEFORE_INSTALL_python3=touch {destdir}/{install_dir}/foo/bar/__init__.py

These commands should be used only if overriding dh_auto_foo is not enough (example below)

override_dh_auto_install:
      before_auto_install_commands
      dh_auto_install
      after_auto_install_commands

See the pybuild manpage for more details (search for BUILD SYSTEM ARGUMENTS)

• Each pybuild call can be disabled (for given interpreter, version or stage). See the pybuild manpage for more details (search for --disable description).

• You can pass options in override_dh_auto_foo via command line options:

  dh_auto_test -- --system=custom --test-args='{interpreter} setup.py test'

  or env. variables:

  PYBUILD_SYSTEM=custom PYBUILD_TEST_ARGS='{interpreter} setup.py test' dh_auto_test

• You can export env. variables globally at the beginning of debian/rules

  export PYBUILD_TEST_ARGS={dir}/tests/

• via command line, f.e.

override_dh_python3:
     dh_python3 --shebang=/usr/bin/python3