[[setup-py]]
=== setup.py (Python3, CLI)

Many interesting upstream Python program packages are packaged using the *setuptools* based *setup.py*.  Usually, these source packages are built into Python specific binary distribution format *wheel* and *wheel* packages are distributed to end users.  Then, end users find these from package listing sites such as https://pypi.org/[the Python Package Index (PyPI)] and install these *wheel* packages using *pip* to the user's environment.

In order to make Debian package of these Python programs, you must start with their source packages. The current Debian packaging practice of such Python programs uses `dh_python3`(1) and `pybuild`(1) from `dh_python` package.  Although *setuptools* isn't mentioned in `pybuild`(1), you can treat these as if these are packaged using the *distutils* based *setup.py* since https://setuptools.pypa.io/en/latest/setuptools.html[setuptools] is an enhanced extension of https://docs.python.org/3/library/distutils.html[distutils]. footnote:[If the source package is lacks *setup.py* but still based on *setuptools*, you need to add a boiler plate *setup.py*.  If the source package is based on other build systems such as *flit*, you need to use respective plugins.]

Let's assume the upstream tarball to be *debhello-1.1.tar.gz*.

"https://docs.python.org/3/install/index.html#install-index[Installing Python Modules (Legacy version)]" explains how to install source to the system using *distutils*.  Essentially, the source is installed using *distutils* as:

----
 $ tar -xzmf debhello-1.1.tar.gz
 $ cd debhello-1.1
 $ python3 setup.py install
----

Debian packaging requires changing the last line to ``*python3 setup.py install --install-layout=deb*'' to install files into the target system image location.  This is automatically addressed when using the *dh* command for Debian packaging.

Here is an example of creating a simple Debian package from a Python3 CLI program using the *setuptools* based *setup.py* as its build system.

Let's get the source and make the Debian package.

.Download *debhello-1.1.tar.gz*
----
include::../examples/debhello-1.1_build-1/step000.slog[]
----

Here, the content of this *debhello* source tree as follows.

.*setup.py* (v=1.1) -- a boilar plate *setup.py* for the backward compatibility
----
include::../examples/debhello-1.1_build-1/step101.slog[]
----

.*setup.cfg* (v=1.1) -- modern static metadata
----
include::../examples/debhello-1.1_build-1/step102.slog[]
----

.*pyproject.toml* (v=1.1) -- https://www.python.org/dev/peps/pep-0517/[PEP 517] configuration
----
include::../examples/debhello-1.1_build-1/step103.slog[]
----

.*MANIFEST.in* (v=1.1) -- for *distutils* to make *sdist*
----
include::../examples/debhello-1.1_build-1/step104.slog[]
----

.*src/debhello/\_\_init__.py* (v=1.1) -- program version definition
----
include::../examples/debhello-1.1_build-1/step105.slog[]
----

.*src/debhello/\_\_main__.py* (v=1.1) -- command entry point
----
include::../examples/debhello-1.1_build-1/step106.slog[]
----

Let's package this with the *debmake* command.  Here, the *-b\':py3'* option is used to specify the generated binary package containing Python3 script and module files.

----
sys::[head -n3 ../examples/debhello-1.1_build-1/step200.slog]
 ...
sys::[grep -A12  '^I: sanity check of parameters' ../examples/debhello-1.1_build-1/step200.slog]
 ...
----

Let's inspect the notable template files generated.

.*debian/rules* (template file, v=1.1):
----
include::../examples/debhello-1.1_build-1/step202.slog[]
----

This is essentially the standard *debian/rules* file with the *dh* command.

The use of the ``*--with python3*'' option invokes *dh_python3* to calculate Python dependencies, add maintainer scripts to byte compiled files, etc. See *dh_python3*(1).

The use of the ``*--buildsystem=pybuild*'' option invokes various build systems for requested Python versions in order to build modules and extensions.  See *pybuild*(1).

.*debian/control* (template file, v=1.1):
----
include::../examples/debhello-1.1_build-1/step203.slog[]
----

Since this is the Python3 package, the *debmake* command sets ``*Architecture: all*'' and ``*Multi-Arch: foreign*''.  Also, it sets required *substvar* parameters as ``*Depends: $\{python3:Depends}, $\{misc:Depends}*''.  These are explained in <<basics>>.

Let's make this Debian package better as the maintainer.

.*debian/rules* (maintainer version, v=1.1):
----
include::../examples/debhello-1.1_build-1/step301.slog[]
----

.*debian/control* (maintainer version, v=1.1):
----
include::../examples/debhello-1.1_build-1/step302.slog[]
----

There are several other template files under the *debian/* directory.  These also need to be updated.

This *debhello* command comes with the upstream-provided manpage and desktop file but the upstream *setup.cfg* doesn't install them.  So you need to update *debian/install* and *debian/manpages*  as follows:

.*debian/install* (maintainer version, v=1.1):
----
include::../examples/debhello-1.1_build-1/step303.slog[]
----

.*debian/manpages* (maintainer version, v=1.1):
----
include::../examples/debhello-1.1_build-1/step304.slog[]
----

The rest of the packaging activities are practically the same as the ones in <<makefile-sh>>.

.Template files under *debian/*. (v=1.1):
----
include::../examples/debhello-1.1_build-1/step400.slog[]
----

Here is the generated dependency list of *debhello_1.1-1_all.deb*.

.The generated dependency list of *debhello_1.1-1_all.deb*:
----
include::../examples/debhello-1.1_build-1/step702.slog[]
----

