Python Modules (GNU Guix Reference Manual)

22.4.7 Python Modules

We currently package Python 2 and Python 3, under the Scheme variable names python-2 and python as explained in Version Numbers. To avoid confusion and naming clashes with other programming languages, it seems desirable that the name of a package for a Python module contains the word python.

Some modules are compatible with only one version of Python, others with both. If the package Foo is compiled with Python 3, we name it python-foo. If it is compiled with Python 2, we name it python2-foo. Packages should be added when they are necessary; we don’t add Python 2 variants of the package unless we are going to use them.

If a project already contains the word python, we drop this; for instance, the module python-dateutil is packaged under the names python-dateutil and python2-dateutil. If the project name starts with py (e.g. pytz), we keep it and prefix it as described above.

Note: Currently there are two different build systems for Python packages in Guix: python-build-system and pyproject-build-system. For the longest time, Python packages were built from an informally specified setup.py file. That worked amazingly well, considering Python’s success, but was difficult to build tooling around. As a result, a host of alternative build systems emerged and the community eventually settled on a formal standard for specifying build requirements. pyproject-build-system is Guix’s implementation of this standard. It is considered “experimental” in that it does not yet support all the various PEP-517 build backends, but you are encouraged to try it for new Python packages and report any problems. It will eventually be deprecated and merged into python-build-system.

Specifying Dependencies

22.4.7.1 Specifying Dependencies

Dependency information for Python packages is usually available in the package source tree, with varying degrees of accuracy: in the pyproject.toml file, the setup.py file, in requirements.txt, or in tox.ini (the latter mostly for test dependencies).

Your mission, when writing a recipe for a Python package, is to map these dependencies to the appropriate type of “input” (see inputs). Although the pypi importer normally does a good job (see Invoking guix import), you may want to check the following check list to determine which dependency goes where.

We currently package Python with setuptools and pip installed per default. This is about to change, and users are encouraged to use python-toolchain if they want a build environment for Python.
guix lint will warn if setuptools or pip are added as native-inputs because they are generally not necessary.
Python dependencies required at run time go into propagated-inputs. They are typically defined with the install_requires keyword in setup.py, or in the requirements.txt file.
Python packages required only at build time—e.g., those listed under build-system.requires in pyproject.toml or with the setup_requires keyword in setup.py—or dependencies only for testing—e.g., those in tests_require or tox.ini—go into native-inputs. The rationale is that (1) they do not need to be propagated because they are not needed at run time, and (2) in a cross-compilation context, it’s the “native” input that we’d want.
Examples are the pytest, mock, and nose test frameworks. Of course if any of these packages is also required at run-time, it needs to go to propagated-inputs.
Anything that does not fall in the previous categories goes to inputs, for example programs or C libraries required for building Python packages containing C extensions.
If a Python package has optional dependencies (extras_require), it is up to you to decide whether to add them or not, based on their usefulness/overhead ratio (see guix size).