Pautas del Empaquetado de Python

Cada paquete que usa Python (en tiempo de ejecución y/o en tiempo de compilación) y/o instala módulos Python * DEBE* tener un dependencia en tiempo de compilación sobre python3-devel , incluso en el caso de que no se invoque realmente a Python durante el tiempo de compilación.

Tener solo una dependencia transitoria en tiempo de compilación sobre python3-devel no es suficiente. Si el paquete utiliza un intérprete de Python alternativo en lugar de python3 (por ejemplo, pypy,jython, python2.7), PUEDE requerir, en su lugar el paquete *-devel correspondiente.

El paquete *-devel incluye macros RPM relevantes. También puede habilitar controles automáticos o manuales: por ejemplo, los mantenedores de Python usan este requisito para listar los paquetes que usan Python de alguna manera y podrían ser afectados por cambios planeados.

Las siguientes macros DEBEN ser utilizadas conde sean aplicables.

Las expansiones entre paréntesis se proporcionan sólo como referencia/ejemplo.

Las macros están definidas para usted en todas las versiones admitidas de Fedora y EPEL.

El resto de este documento utilice estas macros, junto con %{_bindir} (/usr/bin/), en vez de los nombres de ruta en crudo.

Destinos CPython primario de Fedora, la implementación referencial del lenguaje Python. Generalmente utilizamos “Python” para significar CPython.

Implementaciones alternas como pypy están disponibles, pero actualmente carecen de herramientas y directrices comprensivas para empaquetado. Al dirigirse a ellos, no hay reglas estrictas (excepto las directrices generales de empaquetado de Fedora). Pero intenta respetar el espíritu de estas directrices. En caso de duda, considere consultar el SIG de Python.

Los paquetes de Fedora NO DEBEN depender de otras versiones del intérprete CPython que no sean el python3 actual.

En Fedora, las bibliotecas de Python son empaquetados para una versión única de Python, invocada como python3. Por ejemplo, en Fedora 32, python3 es Python 3.8.

En el pasado había múltiples pilas Python, por ejemplo`python3.7` y python2.7, instalables juntas en la misma máquina. Ese es también el caso de algunos proyectos que se basan en Fedora, como RHEL, EPEL y CentOS. Fedora podría volver a introducir pilas instalables en paralelo en el futuro (por ejemplo si un cambio a una nueva versión de Python necesita de un período de transición o si hay bastantes mantenedores interesados en que algo así aparezca).

Fedora incluye versiones alternativas del intérprete, por ejemplo, python2.7 o python3.5, pero estas están destinadas únicamente a desarrolladores que necesitan probar código upstream. Las correcciones de errores y seguridad para estos intérpretes solo cubren este caso de uso. Los paquetes como pip o tox, que permiten configurar entornos aislados e instalar paquetes de terceros en ellos, PUEDEN, como excepción a la regla anterior, utilizar estos intérpretes siempre que se coordine con los mantenedores del intérprete de Python correspondiente.

La mayoría de estos nombres identificadores compatibles con máquinas que distinguen entre mayúsculas y minúsculas, pero el nombre del proyecto tiene una semántica amigable para el humano: no distingue entre mayúsculas y minúsculas y trata algunos conjuntos de caracteres (como ._-) especialmente. Para un uso automatizado, necesita ser normalizado a un formato canónico usado por las herramientas Python y los servicios como setuptools, pip y PyPI. Por ejemplo, el nombre canónico del proyecto Django es django (en minúsculas). Esta estandarización está definida en PEP 503, y la macro <<py_dist_name,the %{py_dist_name} la implementa para el empaquetamiento Fedora. El nombre canónico se obtiene cambiando el nombre del proyecto a minúsculas y convirtiendo todas las series de caracteres no alfanuméricos en caracteres simples“-”. Ejemplo: “The $$$ Tree” se convierte en “the-tree”.

En otra parte de este texto, la metavariable DISTNAME refiere al formulario canónico del nombre de proyecto.

Tenga en cuenta que, en algunos casos, se debe utilizar el nombre original del proyecto, sin normalizar. Por ejemplo, la macro «pypi_source,%pypi_source» y la macro %autosetup necesitan Django, no django.

El carácter + en los nombres de los paquetes compilados (es decir, que no son SRPM) que incluyen los directorios .dist-info o .egg-info está reservado para Extras y NO DEBE utilizarse para ningún otro fin.

Como una excepción, los caracteres + PUEDEN aparecer al final de tales nombres.

El carácter + activa el generador automático de dependencias para los adicionales.

Reemplaza cualquier signo + en el nombre del upstream por -. Omite los signos «+» al principio del nombre. Considera la posibilidad de añadir Provides para el nombre original con los caracteres + para que los usuarios puedan encontrar el paquete más fácilmente.

Un paquete integrado (es decir no SRPM) para una librería Python DEBE ser denominado con el prefijo python3-. Un paquete fuente que contiene principalmente una librería Python DEBE ser denominado con el prefijo python-.

El nombre del paquete Fedora CONTENDRÍA el «nombre canónico del proyecto». Si es posible, el nombre del proyecto SERÍA el mismo que el nombre del módulo importable principal, en minúsculas, con los guiones bajos (_) sustituidos por guiones (-).

Si el nombre del módulo importable y el nombre del proyecto no coinciden, los usuarios suelen acabar confundidos. En este caso, los empaquetadores ASEGURARÍAN que el desarrollador original sea consciente del problema y (especialmente en el caso de paquetes nuevos en los que sea posible cambiar el nombre) esforzarse por cambiar el nombre del paquete. El SIG de Python está disponible para ayudar.

Una biblioteca Python es un paquete destinado a ser importado en Python, como con import requests. Las herramientas como Ansible o IDLE, cuyo código es importable pero no está destinado principalmente a ser importado desde otro software, no se consideran bibliotecas en este sentido. Por lo tanto, esta sección no se aplica a ellas. (Consulte las directrices generales sobre bibliotecas y aplicaciones para obtener orientación general).

El nombre del componente Fedora (paquete fuente) para una biblioteca debe formarse tomando el nombre canónico del proyecto y anteponiéndole python- si aún no comienza con python-. Esto puede dar lugar a conflictos (por ejemplo, entre bugzilla y python-bugzilla). En ese caso, asegúrese de que el desarrollador original sea consciente de la posible confusión en la nomenclatura y aplique su mejor criterio.

Los paquetes que proporcionan principalmente aplicaciones, servicios o cualquier tipo de ejecutables DEBERÍAN nombrarse de acuerdo con las directrices generales Directrices de nomenclatura de Fedora (por ejemplo, ansible).

Considera añadir un proveedor virtual según lo indicado en «Nombres de bibliotecas» más arriba (por ejemplo, python3-PROJECTNAME), si ello ayuda a los usuarios a encontrar el paquete.

Los paquetes DEBEN incluir el archivo fuente (*.py) Y la caché de código byte (*.pyc) para cada módulo importable de Python puro. Los archivos fuente DEBEN incluirse en el mismo paquete que la caché de bytecode.

Los scripts que no se pueden importar (típicamente los que se encuentran en %{_bindir} o %{_libexecdir}) NO DEBEN compilarse en byte.

Los archivos de caché se encuentran en un directorio __pycache__ y tienen una extensión dependiente del intérprete, como .cpython-39.pyc.

La caché no es necesaria para ejecutar el software, pero si no se encuentra, Python intentará crearla cuando se importe un módulo. Si esto logran, el archivo no es rastreado por RPM y permanecerá en el sistema después de la desinstalación. Si no lo logran, los usuarios pueden obtener denegaciones AVC de SELinux espurias en las bitácoras.

Normalmente, la compilación de bytes (generación de los archivos de caché) la realiza el script brp-python-bytecompile BRP, que se ejecuta automáticamente después de que se haya procesado la sección %install del archivo de especificaciones. Compila en bytes cualquier archivo .py que encuentre en %{python3_sitelib} o %{python3_sitearch}.

Debe incluir estos archivos en su paquete (es decir, en la sección %files).

Si el código se encuentra en un subdirectorio (paquete importable), incluya todo el directorio:

Añadir la barra al final es una buena práctica para los directorios.

Sin embargo, esto no se puede utilizar para módulos de nivel superior (los que se encuentran directamente en, p.e. %{python3_sitelib}), ya que tanto %{python3_sitelib} como %{python3_sitelib}/__pycache__/ son propiedad del propio Python. En este caso, la macro %pycached puede ser de ayuda. Se expande al archivo fuente *.py dado y a sus archivos de caché correspondientes. Por ejemplo:

se expande aproximadamente a:

Cada paquete de Python DEBE incluir Metadatos de Distribución de Paquete conformes con Especificaciones PyPA (especialmente, Registrando proyectos instalados).

Los metadatos SERÍAN incluidos en el mismo subpaquete como el módulo importable principal, si hay uno.

Esto aplica a bibliotecas (p.e. python-requests) así como herramientas (p.ej. ansible).

Cuando el software se desglose en varios subpaquetes, es CORRECTO para solo trasladar metadatos en una creación de RPM. En este caso, considere trabajar con desarrollo para además desglosar el proyecto en desarrollo.

Los metadatos toman la forma de un directorio .dist-info instalado en %{python3_sitelib} o %{python3_sitearch} y contienen información que herramientas como importlib.metadata utiliza para inspeccionar librerías instaladas.

Por ejemplo, un proyecto llamado MyLib con el paquete importable mylib podría ser empaquetado con:

Tenga en cuenta que algunas herramientas más antiguas en su lugar ponen los metadatos en un directorio .egg-info o incluso un único archivo. Esto no sucede si usted usa la macro %pyproject_wheel. Si su paquete usa un sistema de compilación que genera un directorio o archivo .egg-info, contacte, por favor, con Python SIG.

Como una excepción, la librería estándar Python PODRÍA distribuirse sin estos metadatos.

Los paquetes *NO DEBEN*poseer directorios compartidos propiedad del mismo Python, como los directorios de alto nivel __pycache__ (%{python3_sitelib}/__pycache__, %{python3_sitearch}/__pycache__).

De forma similar a la regla general, los empaquetadores NO DEBERÍAN simplemente usar comodines para todos lo que se encuentre bajo un directorio compartido.

Además de la lista general, NO DEBERÍA usarse lo siguiente en %files:

Esta regla sirve como comprobación de los errores comunes que por otro lado son difíciles de detectar. Esto limita algunas posibilidades de automatización.

Los errores más comunes que esta regla previene son:

Para cualquier módulo destinado a ser utilizado en Python 3 con import MODNAME, el paquete que incluye PROPORCIONARÍA python3-MODNAME, con guiones bajos (_) sustituidos por guiones (-).

Esto, por suspuesto, ocurre siempre si el paquete se llama python3-MODNAME. Si el subpaquete tiene algún otro nombre, añada %py_provides python3-MODNAME explícitamente. Vea la siguiente sección para aprender sobre %py_provides.

Para cualquier FOO, un paquete que proporciona python3-FOO DEBERÍA usar %py_provides o un generador automático para también proporcionar python-FOO y python3.X-FOO, donde X es la versión menor del intérprete.

Los proporcionado NO DEBERÍA ser añadido manualmente: si no se usa un generador o una macro, no añada de ninguna manera python-FOO / python3.X-FOO.

Esto se hace automáticamente para los nombres de paquete por un generador. Si es absolutamente necesario, el generador puede ser deshabilitado indefiniendo the %__pythonname_provides macro.

Para lo proporcionado que no son nombres de paquete o (por razones técnicas) para paquetes sin archivos, el generador no trabajará. Para estos casos, se proporcionará la siguiente invocación python3-FOO, python-FOO y python3.X-FOO:

La utilización del generador o la macro es importante, porque la forma específica proporcionada puede cambiar en el futuro.

Cada paquete Python DEBE proporcionar python3dist(DISTNAME) y python3.Xdist(DISTNAME), donde X es la versión menor del intérprete y DISTNAME es el Nombre canónico del proyecto correspondiente a los [Metadator de información de la distribución]. Por ejemplo, python3-django proporcionaría python3dist(django) y python3.9dist(django).

Esto se genera automáticamente desde los metadatos de información de distribución. Lo que proporciona NO DEBERÍA ser añadido manualmente: si el generador falla al añadirlo, se DEBE corregir los metadatos.

Estos Provides son usados automáticamente para Requires generados.

Si es absolutamente necesario, el generador automático puede ser deshabilitado quitando la definición de la %{?__pythondist_provides} macro. Considere debatir su caso de uso con el Python SIG si usted necesita hacer esto.

Como se menciona anteriormente, cada paquete Python DEBE explícitamente BuildRequire python3-devel.

Los paquetes NO DEBEN teneer dependencias (ni en tiempo de compilación ni de ejecución) con el prefijo sin versión python- si se puede usar la correspondiente dependencia python3- en su lugar.

Los paquetes NO DEBERÍAN tener dependencias explícitas (ni en tiempo de compilación ni de ejecución) con un prefijo de versión menor como python3.8- o python3.8dist(. Tales dependencias DEBERÍAN ser generadas automáticamente o se debería usar una macro para obtener la versión.

Los paquetes NO DEBERÍAN tener una dependencia explícita en tiempo de ejecución sobre python3.

En lugar de dependender de python3, los paquetes tienen una dependencia automática sobre python(abi) = 3.X cuando instalan archivos en %{python3_sitelib} o %{python3_sitearch}, o tiene una dependencia automática en /usr/bin/python3 si tienen scripts Python ejecutables o tienen una dependencia automática en libpython3.X.so.1.0() si incorporan Python.

Estas reglas ayudan a tener una actualización sin problemas cuando se actualiza python3 en nuevas versiones de Fedora.

Los paquetes DEBEN usar el generador automático Python de dependencia en tiempo de ejecución.

Los paquetes DEBERÍAN usar el generador opt-in build-dependency si es posible.

El empaquetador DEBE inspeccionar lo requerido generado para ver que es correcto. Todas las dependencias DEBEN ser resueltas dentro de la versión de Fedora objetivo.

Cualquier cambio necesario DEBE ser hecho mediante parches o modificando la fuente (por ejemplo. con sed), en lugar de deshabilitar el generador. El cambio resultante DEBERÍA ser ofrecido a desarrollador. Como excepción, el filtrado PODRÍA ser usado para soluciones temporales y arranque inicial.

Las dependencias cubiertas por los generadores NO DEBERÍAN ser repetidas en el archivo .spec. (Por ejemplo, si el generador encuentra una dependencia requests, Requires: python3-requests es redundante.)

Los requeridos generados automáticamente están en el formato python3.Xdist(DISTNAME), aumentados potencialmente con los requisitos de versión o combinados junto con dependencias ricas. Cualquier sufijo .0 es eliminado de los números de versión para coincidir con el comportamiento de las herramientas Python. (PEP 440 especifica que X.Y y X.Y.0 son tratados como iguales.)

Tenga en cuenta que los generadores solo cubren los paquetes Python. Otras dependencias, con frecuencia librerías C como openssl-devel, deben ser especificadas en el archivo .spec manualmente.

La forma en que se especifican los requisitos en el código fuente depende del sistema de compilación y de las preferencias de cada proyecto. Las ubicaciones comunes son pyproject.toml, setup.py, setup.cfg, config.toml.

Vea la sección [Tests].

Los extras de Python son una manera de que los proyectos Python requieren dependencias extras para funcionalidad adicional.

Por ejemplo, requests tiene varias dependencias estándar (por ejemplo`urllib3). Pero tambíen declara un extra denominado `requests[security], que enumera dependencias adicionales (por ejemplo, cryptography). A diferencia de los subpaquetes RPM, los extras pueden especificar solo dependencias adicionales, no archivos adicionales. El paquete principal funcionará si la dependencia opcional no está instalada, pero podría tener la funcionalidad limitada.

Las herramientas Python tratan los extras como paquetes virtuales. Por ejemplo, si un usuario ejecuta pip install 'requests[security]' o instala un proyecto que depende de requests[security], serán instalados requests y cryptography.

En Fedora, los extras son proporcionados normalmente por paquetes sin archivos. En lugar de corchetes, los nombres de paquetes Fedora usan convencionalmente el carácter + (que es válido en los nombres de paquete RPM, pero no en los nombres canónicos de proyectos Python ni en los identificadores de extras).

Líneas Shebang para invocar Python DEBE utilizar %{python3} como el interpretador.

Shebang lines to invoke Python SHOULD be #!%{python3} -%{py3_shebang_flags} and they MAY include extra flags.

Si (algunos) de los indicadores por defecto desde la macro %{py3_shebang_flags} no es deseable, los paquetes explícitamente REDEFINIRÍA la macro para retirarlas por desdefinir la macro %{_py3_shebang_...} relevante.

Using #!%{python3} (#!/usr/bin/python3) rather than e.g. #!/usr/bin/env python ensures that the system-wide Python interpreter is used to run the code, even if the user modifies $PATH (e.g. by activating a virtual environment).

Por defecto, -%{py3_shebang_flags} expande a -sP (o sólo -s en la versión de Python más baja que 3.11 y Fedora Linux más antiguo que 37).

The -s flag, stored in the %{_py3_shebang_s} macro, means don’t add user site directory to sys.path. That ensures the user’s Python packages (e.g. installed by pip install --user, or just placed in the current directory) don’t interfere with the RPM installed software. Sometimes, such content is desirable, such as with plugins.

The -P flag, stored in the %{_py3_shebang_P} macro, means don’t add the script’s directory to sys.path. Sometimes, adding the script’s directory to sys.path is desirable, such as with executable Python scripts installed in a custom directory, importing each other.

Removing the undesired flag(s) from the %{py3_shebang_flags} macro rather than not using the macro at all, ensures that existing or future automation won’t add the flag.

The %pyproject_install macro automatically changes all Python shebangs in %{buildroot}%{_bindir}/* to use %{python3} and add contents of the %{py3_shebang_flags} macro to the existing flags. If you’re not using that macro or you need to change a shebang in a different directory, you can use the %py3_shebang_fix macro as follows:

Every executable TOOL for which the current version of Python matters SHOULD also be invokable by python3 -m TOOL.

If the software doesn’t provide this functionality, packagers SHOULD ask the upstream to add it.

This applies to tools that modify the current Python environment (like installing or querying packages), use Python for configuration, or use Python to run plugins. It does not apply to tools like GIMP or Bash which support plugins in multiple languages and/or have other means to specify the interpreter.

For example, pip can be invoked as python3 -m pip.

This allows users to accurately specify the Python version used to run the software. This convention works across different environments that might not always set $PATH or install scripts consistently.

If a test suite exists upstream, it SHOULD be run in the %check section. If that is not possible with reasonable effort, at least a basic smoke test (such as importing the packaged module) MUST be run in %check.

You MAY exclude specific failing tests. You MUST NOT disable the entire testsuite or ignore its result to solve a build failure.

As an exception, you MAY disable tests with an appropriate %if conditional (e.g. bcond) when bootstrapping.

Most errors in Python happen at run-time, so tests are extremely important to root out issues, especially when mass rebuilds are required.

Common reasons for skipping tests in %check include requiring network access, dependencies not packaged in Fedora, and/or specialized hardware or resources.

In these cases, you can use the %pyproject_check_import or the %py3_check_import macro to test that installed modules are importable.

One part of the Python packaging ecosystem that is still not standardized is specifying test dependencies (and development dependencies in general).

A good, common way for upstreams to specify test dependencies is using an extra like [test], [testing] or [dev]. In this case, upstream’s instructions to install test dependencies might look like $ pip install -e.[test].

Another way to specify test dependencies is using a dedicated dependency group (PEP 735).

Projects using tox usually specify test dependencies in a tox-specific format: a requires key in the configuration.

These three forms are handled by the %pyproject_buildrequires macro.

If upstream does not use either form, list test dependencies as manual BuildRequires in the spec file, for example:

If you need to do this, consider asking upstream to add a [test] extra or a test dependency group.

In %check, packages SHOULD NOT run “linters”: code style checkers, test coverage checkers and other tools that check code quality rather than functionality.

Tools like black, pylint, flake8, or mypy are often “opinionated” and their “opinions” change frequently enough that they are nuisance in Fedora, where the linter is not pinned to an exact version. Furthermore, some of these tools take a long time to adapt to new Python versions, preventing early testing with Alpha and Beta releases of Python. And they are just not needed: wrongly formatted code is not important enough for the Fedora packager to bug the upstream about it. Making such an issue break a package build is entirely unreasonable.

Linters do make sense in upstream CI. But not in Fedora.

If a linter is used, disable it and remove the dependency on it. If that is not easy, talk to upstream about making it easy (for example with a configuration option or a separate tox environment).

For packages that contain such linters, use them at runtime or extend them, you will usually need to run the linter in %check. Run it to test functionality, not code quality of the packaged software.

The “pyproject macros” are most useful for packaging Python projects that use the pyproject.toml file defined in PEP 518 and PEP 517, which specifies the package’s build dependencies (including the build system, such as setuptools, flit or poetry).

If pyproject.toml is not found, the macros automatically fall backs to using setuptools with configuration in setup.cfg/setup.py.

A full tutorial and discussion for the macros is available in the macros’ README.

The following macros are available for cases where automatic generation is turned off. They can also be useful for handling files in non-standard locations where the generators don’t look.

The following macros can be redefined for special use cases.

When comparing Python versions (e.g. to ask: is %{python3_version} greater than 3.8?), using naïve %if %{python3_version} > 3.8 or %if "%{python3_version}" > "3.8" is not possible, because the comparison is performed alphabetically on strings. Hence it is true that "3.10" < "3.8" (which is not desired).

It is possible to explicitly compare version literals by using the v prefix, similar to the Python string prefixes:

The following macros can turn off Python-specific automation.

Consider contacting the Python SIG if you need to do this.

The following macros are deprecated. See the 201x-era Python Packaging guidelines for how some of them were used.