Hints for maintainers of Debian packages of Python extensions
-------------------------------------------------------------

Most of the content of this README can be found in the Debian Python policy.
See /usr/share/doc/python/python-policy.txt.gz.

Documentation Tools
-------------------

If your package ships documentation produced in the Python
documentation format, you can generate it at build-time by
build-depending on python3.11-dev, and you will find the
templates, tools and scripts in /usr/lib/python3.11/doc/tools --
adjust your build scripts accordingly.


Makefile.pre.in issues
----------------------

Python comes with a `universal Unix Makefile for Python extensions' in
/usr/lib/python3.11/config/Makefile.pre.in (with Debian, this is included
in the python-dev package), which is used by most Python extensions.

In general, packages using the Makefile.pre.in approach can be packaged
simply by running dh_make or by using one of debhelper's rules' templates
(see /usr/doc/debhelper/examples/). Makefile.pre.in works fine with e.g.
"make prefix=debian/tmp/usr install".

One glitch: You may be running into the problem that Makefile.pre.in
doesn't try to create all the directories when they don't exist. Therefore,
you may have to create them manually before "make install". In most cases,
the following should work:

	...
	dh_installdirs /usr/lib/python3.11
	$(MAKE) prefix=debian/tmp/usr install
	...


Byte-compilation
----------------

For speed reasons, Python internally compiles source files into a byte-code.
To speed up subsequent imports, it tries to save the byte-code along with
the source with an extension .pyc (resp. pyo). This will fail if the
libraries are installed in a non-writable directory, which may be the
case for /usr/lib/python3.11/.

Not that .pyc and .pyo files should not be relocated, since for debugging
purposes the path of the source for is hard-coded into them.

To precompile files in batches after installation, Python has a script
compileall.py, which compiles all files in a given directory tree. The
Debian version of compileall has been enhanced to support incremental
compilation and to feature a ddir (destination dir) option. ddir is
used to compile files in debian/usr/lib/python/ when they will be
installed into /usr/lib/python/.


Currently, there are two ways to use compileall for Debian packages. The
first has a speed penalty, the second has a space penalty in the package.

1.) Compiling and removing .pyc files in postinst/prerm:

  Use dh_python(1) from the debhelper packages to add commands to byte-
  compile on installation and to remove the byte-compiled files on removal.
  Your package has to build-depend on: debhelper (>= 4.1.67), python.

  In /usr/share/doc/python3.11, you'll find sample.postinst and sample.prerm.
  If you set the directory where the .py files are installed, these
  scripts will install and remove the .pyc and .pyo files for your
  package after unpacking resp. before removing the package.

2.) Compiling the .pyc files `out of place' during installation:

  As of 1.5.1, compileall.py allows you to specify a faked installation
  directory using the "-d destdir" option, so that you can precompile
  the files in their temporary directory
  (e.g. debian/tmp/usr/lib/python2.1/site-packages/PACKAGE).



    11/02/98                             
    Gregor Hoffleit <flight@debian.org>


Last modified: 2007-10-14