============
PyDist files
============

DISTNAME [VRANGE] [DEPENDENCY][; [PEP386|PEP440] [RULES]]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PyDist files help tools like dh_python3 to translate Python dependencies
(from setup.py's install_requires or egg's requires.txt file) to Debian
dependencies if given Python distribution file / directory is not installed
(hint: add proper package to Build-Depends and PyDist file might not be needed)
or if detection is not correct.

Before checking for package that provides installed egg-info file or directory
dh_python3 is checking these locations for overrides:

 * debian/py3dist-overrides
 * /usr/share/python3/dist/*
 * /usr/share/dh-python/dist/cpython3_fallback

debian/python3-foo.pydist is copied into /usr/share/python3/dist/ automatically.

*NOTE:* There's no need to add an override if build-depending on a package that
provides searched egg-info results in correctly recognized dependency.

Required fields:
~~~~~~~~~~~~~~~~

DISTNAME
````````
Python distribution name (you can find it at the beginning of .egg-info
file/directory name that your package provides).
This should ideally be normalized
(https://packaging.python.org/en/latest/specifications/simple-repository-api/#normalized-names),
but dh_python3 will still tolerate it if it isn't.

Examples:
 * jinja2
 * numpy
 * sqlalchemy


Optional fields:
~~~~~~~~~~~~~~~~

VRANGE
``````
Python version or version range the line applies to.

Examples:
 * 3.1		(Python 3.1 only)
 * 3.1-		(Python 3.1 and newer)
 * 3.1-3.3	(Python 3.1 or 3.2)
 * -3.4		(Python 3.3 or older)

DEPENDENCY
``````````
Debian dependency, multiple packages or versions are allowed.
If not set, given Python distribution name will be ignored.

Examples:
 * python-mako
 * python-jinja2 | python (>= 2.6)
 * python-sqlalchemy (>= 0.5), python-sqlalchemy (<< 0.6)

 * python3-mako
 * python3-jinja2 | python3 (>= 3.0)
 * python3-sqlalchemy (>= 0.5), python3-sqlalchemy (<< 0.6)

PEP440
``````
Standards flag: upstream uses versioning schema described in PEP 440.
If a package declares this, dependencies on it will be versioned.

PEP386
``````
Standards flag: upstream uses versioning schema described in PEP 386.
If a package declares this, dependencies on it will be versioned.

RULES
`````
Rules needed to translate upstream version to Debian one. If
PEP386 or PEP440 is set, its rules will be applied later. Multiple rules
are allowed, separate them with a space.

Examples:
 * s/^/2:/
 * s/alpha/~alpha/ s/^/1:/


Notes:
~~~~~~

You can use multiple lines if binary package provides more than one Python
distribution or if you want to specify different dependencies for each Python
version or version range.

If you use dh_python3, it will install debian/binary_package_name.pydist file
to /usr/share/dh-python/dist/cpython3/binary_package_name automatically.


Complete examples:
~~~~~~~~~~~~~~~~~~
 * sqlalchemy python3-sqlalchemy (>= 0.5), python3-sqlalchemy (<< 0.6)
 * mako python3-mako; PEP386
 * foo -3.2 python3-oldfoo; s/^/3:/
 * foo 3.2- python3-foo; PEP440
 * bar 2.6-

.. vim: ft=rst
