DH_PYTHON2(1)

πŸ“¦ version 5.20220403, in ubuntu jammy

πŸ’– DH_PYTHON2(1) πŸ’–

okay bestie, sit down, hydrate, because we're doing the DH_PYTHON2(1) manual page and it's actually kind of iconic. this is dh_python2 β€” yes, the Debian helper that does your Python dependency math, drops maintainer scripts in so your files get byte compiled, all of that. it's giving ✨essential build infrastructure✨ and i'm obsessed. no cap.

✨ NAME ✨

dh_python2 β€” calculates Python dependencies, adds maintainer scripts to byte compile files, etc.

like. that's the whole job description and honestly? slay.

πŸŽ€ SYNOPSIS πŸŽ€

dh_python2 -p PACKAGE [-V [X.Y][-][A.B]] DIR_OR_FILE [-X REGEXPR]

πŸ¦‹ DESCRIPTION πŸ¦‹

🌸 QUICK GUIDE FOR MAINTAINERS 🌸

okay so here's the checklist, do them in order, don't skip, i will know:

  • if necessary, describe supported Python versions via X-Python-Version field in debian/control,
  • build depend on dh-python
  • build-depend on python or python-all or python-all-dev (>= 2.6.6-3~),
  • build module/application using its standard build system, remember to build extensions for all supported Python versions (loop over pyversions -vr),
  • install files to the standard locations, add --install-layout=deb to setup.py's install command if your package is using distutils,
  • add python2 to dh's --with option, or:
  • include /usr/share/cdbs/1/class/python-distutils.mk in debian/rules and depend on cdbs (>= 0.4.90), or:
  • call dh_python2 in the binary-* target,
  • add ${python:Depends} to Depends

periodt. πŸ’…

πŸ“ NOTES πŸ“

so here's the tea: to support more than one Python version in the same binary package, dh_python2 (unlike dh_pycentral and dh_pysupport) creates symlinks to all supported Python versions at build time. what that means for you is: the second your list of supported Python versions changes, you need a binNMU (or a sourceful upload if we're talking architecture independent packages). it's the price of admission. but bestie β€” it's faster and more robust than its competitors, though. worth it. πŸ”₯

πŸ” dependencies πŸ”

dh_python2 tries to translate Python dependencies from the requires.txt file into Debian dependencies. in so many cases this just works with zero extra config, because dh_python2 ships with a build-in mapping of Python module names to Debian packages that gets periodically regenerated from the Debian archive. by default, the version information in the Python dependencies is discarded. so if you want dh_python2 to generate more strict dependencies (like, say, to avoid ABI problems), or if the automatic mapping is just not doing it for your package, you gotta hand dh_python2 some extra rules for translating Python module β†’ Debian package dependencies.

so like, for a package python-foo that depends on a package python-bar, there are two files that may provide those rules:

  1. If the python-foo source package ships with a debian/pydist-overrides file, this file is used by dh_python during the build of python-foo.
  2. If the python-bar source package ships with a debian/python-bar.pydist file (and uses dh_python), this file will be included in the binary package as /usr/share/dh-python/dist/cpython2/python-bar. During the build of python-foo, dh_python will then find and use the file.

both files have the same format, described in /usr/share/doc/dh-python/README.PyDist. and if all you want is to generate versioned dependencies (and we're assuming the python-bar package provides the pybar Python module), in most cases it'll be enough to put this line:

pybar python-bar; PEP386

into either of the above files. easy. πŸ’–

🧚 namespace feature 🧚

dh_python2 parses Egg's namespace_packages.txt files (in addition to the --namespace command line argument(s)) and drops empty __init__.py files from the binary package. pycompile will regenerate them at install time and pyclean will remove them at uninstall time (if they're no longer used in installed packages). still, it's a good idea to provide an __init__.py file in one of the binary packages (even if all the other packages use this feature). just saying. πŸ™ˆ

πŸ“ private dirs πŸ“

/usr/share/foo, /usr/share/games/foo, /usr/lib/foo and /usr/lib/games/foo private directories are scanned for Python files by default (where foo is the binary package name). if your package ships Python files somewhere else entirely, just add another dh_python2 call in debian/rules with the directory name as an argument β€” and yes you can use a totally different set of options in that call. but if you need to change options (f.e. a list of supported Python versions) for a private directory that's checked by default, invoke dh_python2 with --skip-private and add another call with a path to this directory and your new options. 🫢

πŸ’€ debug packages πŸ’€

in binary packages whose name ends with -dbg, all files in /usr/lib/python2.X/{site,dist}-packages/ directory that have extensions different than so or h are removed by default. if you do not want that, use the --no-dbg-cleaning option to disable this feature.

🌈 pyinstall files 🌈

files listed in debian/pkg.pyinstall file will be installed as public modules (i.e. into .../dist-packages/ directory) for all requested Python versions (dh_install doesn't know about python's site- vs. dist-packages issue, bless it).

Syntax: path/to/file [NAMESPACE] [VERSION_RANGE]

the debian directory is automatically removed from the path, so you can place your files in debian/ directory and install them from this location (if you want to install them in the debian namespace, set NAMESPACE to debian). if NAMESPACE is set, all listed files will be installed in .../dist-packages/NAMESPACE/ directory.

Examples, my beloved:

  • foo.py installs .../dist-packages/foo.py for all supported Python versions
  • foo/bar.py 2.6- installs .../dist-packages/foo/bar.py for versions >= 2.6
  • foo/bar.py spam installs .../dist-packages/spam/bar.py
  • debian/*.py spam.egg 2.5 installs .../python2.5/site-packages/spam/egg/*.py files

🌟 pyremove files 🌟

if you want to remove some public modules (i.e. files in .../dist-packages/ directory) installed by build system (from all supported Python versions or only from a subset of these versions), add them to debian/pkg.pyremove file.

Examples:

  • *.pth removes .pth files from .../dist-packages/
  • bar/baz.py 2.5 removes .../python2.5/site-packages/bar/baz.py

πŸ’œ overriding supported / default Python versions πŸ’œ

if you want to override the system's list of supported Python versions or the default one (f.e. to build a package that includes symlinks for an older version of Python or compile .py files only for a given interpreter version), you can do that via the DEBPYTHON_SUPPORTED and/or DEBPYTHON_DEFAULT env. variables.

Example: 2.5,2.7 limits the list of supported Python versions to Python 2.5 and Python 2.7. main character energy, honestly. πŸ‘‘

✨ OPTIONS ✨

  • --version β€” show program's version number and exit
  • -h, --help β€” show help message and exit
  • --no-guessing-versions β€” disable guessing other supported Python versions
  • --no-guessing-deps β€” disable guessing dependencies
  • --no-dbg-cleaning β€” do not remove any files from debug packages
  • --no-ext-rename β€” do not add magic tags nor multiarch tuples to extension file names
  • --no-shebang-rewrite β€” do not rewrite shebangs
  • --skip-private β€” don't check private directories
  • -v, --verbose β€” turn verbose mode on
  • -i, --indep β€” act on architecture independent packages
  • -a, --arch β€” act on architecture dependent packages
  • -q, --quiet β€” be quiet
  • -p PACKAGE, --package=PACKAGE β€” act on the package named PACKAGE
  • -N NO_PACKAGE, --no-package=NO_PACKAGE β€” do not act on the specified package
  • -V VRANGE β€” specify list of supported Python versions. see pycompile(1) for examples
  • -X REGEXPR, --exclude=REGEXPR β€” exclude items that match given REGEXPR. you may use this option multiple times to build up a list of things to exclude.
  • --compile-all β€” compile all files from given private directory in postinst/rtupdate, not just the ones provided by the package (i.e. do not pass the --package parameter to pycompile/pyclean)
  • --accept-upstream-versions β€” accept upstream versions while translating Python dependencies into Debian ones
  • --depends=DEPENDS β€” translate given requirements into Debian dependencies and add them to ${python:Depends}. use it for missing items in requires.txt
  • --depends-section=SECTION β€” translate requirements from given sections of requres.txt file into Debian dependencies and add them to ${python:Depends}.
  • --recommends=RECOMMENDS β€” translate given requirements into Debian dependencies and add them to ${python:Recommends}
  • --recommends-section=SECTION β€” translate requirements from given sections of requres.txt file into Debian dependencies and add them to ${python:Recommends}.
  • --suggests=SUGGESTS β€” translate given requirements into Debian dependencies and add them to ${python:Suggests}
  • --suggests-section=SECTION β€” translate requirements from given sections of requres.txt file into Debian dependencies and add them to ${python:Suggests}.
  • --requires=FILENAME β€” translate requirements from given file(s) into Debian dependencies and add them to ${python:Depends}
  • --namespace=NAME β€” use this option (multiple time if necessary) if namespace_packages.txt is not complete
  • --ignore-namespace β€” ignore Egg's namespace declaration and --namespace option. this option will disable removing (and recreating at install time) empty __init__.py files. removing namespace_packages.txt from egg-info directory has the same effect.
  • --clean-pycentral β€” generate maintainer script that will remove byte code generated by python-central helper
  • --shebang=COMMAND β€” use given command as shebang in scripts
  • --ignore-shebangs β€” do not translate shebangs into Debian dependencies

πŸŽ€ SEE ALSO πŸŽ€

πŸ’– AUTHOR πŸ’–

Piotr OΕΌarowski, 2012-2013

and that's the whole page bestie!! 🫢 this was DH_PYTHON2(1) (yes, that's the manual name and the footer, it contains multitudes), written by Piotr OΕΌarowski, 2012-2013, and if you need the most recent version of this document it's at http://deb.li/dhp2. go forth and byte compile, you absolute icon. πŸ’…βœ¨πŸŒˆ

πŸ“¦ where this page comes from