|
Python Packaging Guidelines
|
|
|
This version of Python Packaging Guidelines is in effect since 2021 and represents a major rewrite and paradigm shift. Not all packages are updated to reflect this. Older guidelines are still being kept up to date, and existing packages *MAY* use them instead of this document:
|
|
|
xref:Python_201x.adoc[“201x-era” Python packaging guidelines] (Packages using these usually use the <<py3_install,`+%py3_install+`>> or <<py3_install_wheel,`+%py3_install_wheel+` macro>> or call `+setup.py install+`.)
|
|
|
xref:Python_Appendix.adoc#_python_2_packages[Python 2 appendix] Note that Python 2 packages require a FESCo exception.
|
|
|
These guidelines only support current Fedora releases. For older releases (such as in EPEL 8), consult the xref:Python_201x.adoc[201x-era guidelines].
|
|
|
The two <<Distro-wide guidelines>> below apply to all software in Fedora that uses Python at build- or run-time.
|
|
|
The rest of the Guidelines apply to packages that ship code that can be imported with Python’s `+import+` statement. Specifically, that is all packages that install files under `+/usr/lib*/python*/+`.
|
|
|
Except for the two “Distro-wide guidelines”, these Guidelines do not apply to simple one-file scripts or utilities, especially if these are included with software not written in Python. However, if an application (e.g. CLI tool, script or GUI app) needs a more complex Python library, the library *SHOULD* be packaged as an importable library under these guidelines.
|
|
|
A major goal for Python packaging in Fedora is to _harmonize with the wider Python ecosystem_, that is, the https://pypa.io[Python Packaging Authority] (PyPA) standards and the https://pypi.org/[Python Package Index] (PyPI). Packagers *SHOULD* be prepared to get involved with upstream projects to establish best practices as outlined here. We wish to improve both Fedora and the wider Python ecosystem.
|
|
|
Some build tools (like CMake or autotools) may not work with the latest PyPA standards yet. (For example, they might generate `+.egg-info+` directories rather than `+.dist-info+`.) While this document's normative points (MUST/SHOULD) are tool-agnostic, many of the practical tips and helper macros will not be applicable. If this affects you, consider contacting the https://lists.fedoraproject.org/archives/list/python-devel@lists.fedoraproject.org/[Python SIG] for guidance and/or following the xref:Python_201x.adoc[older guidelines] for the time being.
|
|
|
Fedora’s Python SIG not only develops these guidelines, but it’s also involved in PyPA standards and Python packaging best practices. Check out https://fedoraproject.org/wiki/SIGs/Python[the wiki] or https://lists.fedoraproject.org/archives/list/python-devel@lists.fedoraproject.org/[mailing list] if you need help or wish to help out.
|
|
|
Distro-wide guidelines
|
|
|
BuildRequire python3-devel
|
|
|
*Every* package that uses Python (at runtime and/or build time)
and/or installs Python modules
*MUST* explicitly include `+BuildRequires: python3-devel+`
in its `+.spec+` file,
even if Python is not actually invoked during build time.
|
|
|
If the package uses an alternate Python interpreter instead of `+python3+` (e.g. `+pypy+`, `+jython+`, `+python2.7+`), it *MAY* instead require the corresponding `+*-devel+` package.
|
|
|
The `+*-devel+` package brings in relevant RPM macros. It may also enable automated or manual checks: for example, Python maintainers use this requirement to list packages that use Python in some way and might be affected by planned changes.
|
|
|
Mandatory macros
|
|
|
The following macros *MUST* be used where applicable.
|
|
|
The expansions in parentheses are provided only as reference/examples.
|
|
|
The macros are defined for you in all supported Fedora and EPEL versions.
|
|
