Diretrizes de Empacotamento Python

Every package that uses Python (at run-time and/or build-time) and/or installs Python modules MUST have a build-time dependency on python3-devel, even if Python is not actually invoked during build-time. Such a package MUST use one of the following in its .spec file:

Only having a transitive build-time dependency on python3-devel is not sufficient. 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.

O pacote *-devel traz macros RPM relevantes. Também pode permitir verificações automatizadas ou manuais: por exemplo, os mantenedores do Python usam esse requisito para listar pacotes que usam o Python de alguma forma e podem ser afetados por mudanças planejadas.

As macros a seguir DEVEM ser usadas quando aplicável.

As expansões entre parênteses são fornecidas apenas como referência/exemplos.

As macros são definidas para você em todas as versões suportadas do Fedora e EPEL.

O restante deste documento usa essas macros, junto com %{_bindir} (/usr/bin/), em vez dos nomes de caminho brutos.

O Fedora tem como alvo principal CPython, a implementação de referência da linguagem Python. Geralmente usamos “Python” para significar CPython.

Implementações alternativas como pypy estão disponíveis, mas atualmente carecem de ferramentas e diretrizes abrangentes para empacotamento. Ao direcioná-los, não existem regras rígidas (exceto as diretrizes gerais de empacotamento do Fedora). Mas, por favor, tente respeitar o espírito destas diretrizes. Em caso de dúvida, considere consultar o Python SIG.

Os pacotes do Fedora NÃO DEVEM depender de outras versões do interpretador CPython além do atual python3.

No Fedora, as bibliotecas Python são empacotadas para uma única versão do Python, chamada python3. Por exemplo, no Fedora 32, python3 é Python 3.8.

No passado, havia várias pilhas Python, por exemeplo python3.7 e python2.7, instaláveis juntos na mesma máquina. Esse também é o caso de alguns projetos construídos em cima do Fedora, como RHEL, EPEL e CentOS. O Fedora pode reintroduzir pilhas instaláveis em paralelo no futuro (por exemplo, se uma mudança para uma nova versão do Python precisar de um período de transição, ou se de alguma forma aparecerem mantenedores interessados suficientes).

O Fedora inclui versões alternativas de intérpretes, por exemplo python2.7 ou python3.5, mas estes são destinados apenas para desenvolvedores que precisam testar o código upstream. Correções de bugs e segurança para esses interpretadores cobrem apenas este caso de uso. Pacotes como pip ou tox, que permitem configurar ambientes isolados e instalar pacotes de terceiros neles, PODE, como exceção à regra acima, usar esses interpretadores desde que isso seja coordenado com os mantenedores do interpretador Python relevante.

A maioria desses nomes são identificadores amigáveis à máquina que diferenciam maiúsculas de minúsculas, mas o nome do projeto tem uma semântica amigável: não diferencia maiúsculas de minúsculas e trata alguns conjuntos de caracteres (como ._-) especialmente. Para uso automatizado, ele precisa ser normalizado para um formato canônico usado por ferramentas e serviços Python, como setuptools, pip e PyPI. Por exemplo, o nome canônico do projeto Django é django (em letras minúsculas). Esta normalização é definida em PEP 503 e a macro %{py_dist_name} implementa para empacotamento do Fedora. O nome canônico é obtido mudando o nome do projeto para minúsculas e convertendo todas as execuções de caracteres não alfanuméricos em caracteres “-” únicos. Exemplo: “A árvore $$$” se torna “a-arvore”.

Em outra parte deste texto, a metavariável DISTNAME refere-se à forma canônica do nome do projeto.

Observe que em alguns lugares, o nome do projeto original e não normalizado deve ser usado. Por exemplo, a macro %pypi_source e a macro %autosetup precisam de Django, não de django.

O caractere + em nomes de pacotes construídos (ou seja, não SRPM) que incluem os diretórios .dist-info ou .egg-info é reservado para Extras e NÃO DEVE ser usado para qualquer outro fim.

Como exceção, os caracteres + PODEM aparecer no final de tais nomes.

O caractere + aciona o gerador automático de dependência para extras.

Substitua qualquer sinal + no nome upstream por -. Omita os sinais + no início do nome. Considere adicionar Provides ao nome original com caracteres + para tornar o pacote mais fácil de ser encontrado pelos usuários.

Um pacote compilado (ou seja, não SRPM) para uma biblioteca Python DEVE ser nomeado com o prefixo python3-. Um pacote fonte contendo principalmente uma biblioteca Python DEVE ser nomeado com o prefixo python-.

RECOMENDA-SE que o nome do pacote Fedora contenha o Nome canônico do projeto. Se possível, RECOMENDA-SE que o nome do projeto seja igual ao nome do módulo principal importável, em letras minúsculas, com sublinhados (_) substituídos por traços (-).

Se o nome do módulo importável e o nome do projeto não corresponderem, os usuários frequentemente ficarão confusos. Neste caso, RECOMENDA-SE que os empacotadores garantam que o upstream esteja ciente do problema e (especialmente para novos pacotes onde a renomeação é viável) se esforçar para renomear o pacote. O Python SIG está disponível para assistência.

Uma biblioteca Python é um pacote destinado a ser importado em Python, como import requests. Ferramentas como Ansible ou IDLE, cujo código é importável, mas não se destina principalmente a ser importado de outro software, não são consideradas bibliotecas neste sentido. Portanto, esta seção não se aplica a eles. (Consulte diretrizes gerais de bibliotecas e aplicativos para obter orientação geral.)

O nome do componente Fedora (pacote fonte) para uma biblioteca deve ser formado pegando o nome canônico do projeto e acrescentando python- se ainda não começar com python-. Isso pode levar a conflitos (por exemplo, entre bugzilla e python-bugzilla). Nesse caso, certifique-se de que o upstream esteja ciente da nomenclatura potencialmente confusa e aplique o melhor julgamento.

Para pacotes que forneçam principalmente aplicativos, serviços ou qualquer tipo de executável É RECOMENDÁVEL que sejam nomeados de acordo com as diretrizes de nomenclatura do Fedora gerais (por exemplo, ansible).

Considere adicionar um "provides" virtual de acordo com Nomenclatura de biblioteca acima (por exemplo, python3-PROJECTNAME), se isso ajudar os usuários a encontrar o pacote.

Os pacotes DEVEM incluir o arquivo fonte (*.py) E o cache de bytecode (*.pyc) para cada módulo importável em Python puro. Os arquivos fonte DEVEM ser incluídos no mesmo pacote que o cache de bytecode.

Para scripts que não são importáveis (normalmente aqueles em %{_bindir} ou %{_libexecdir}) É RECOMENDÁVEL que NÃO sejam compilados em bytes.

Os arquivos de cache são encontrados em um diretório __pycache__ e possuem um sufixo dependente do interpretador como .cpython-39.pyc.

O cache não é necessário para executar o software, mas se não for encontrado, o Python tentará criá-lo quando um módulo for importado. Se isso for bem-sucedido, o arquivo não será rastreado pelo RPM e permanecerá no sistema após a desinstalação. Se não tiver êxito, os usuários podem obter negações falsas de SELinux AVC nos logs.

Normalmente, a compilação de bytes (gerando os arquivos de cache) é feita para você pelo brp-python-bytecompile script BRP, que é executado automaticamente após a seção %install do arquivo spec foi processado. Ele compila qualquer arquivo .py que encontrar em %{python3_sitelib} ou %{python3_sitearch}.

Você deve incluir esses arquivos do seu pacote (ou seja, na seção %files).

Se o código estiver em um subdiretório (pacote importável), inclua o diretório inteiro:

Adicionar a barra final é uma prática recomendada para diretórios.

No entanto, isso não pode ser usado para módulos de nível superior (aqueles diretamente em, por exemplo, %{python3_sitelib}), porque ambos %{python3_sitelib} e %{python3_sitelib}/__pycache__/ são de propriedade do próprio Python. Aqui, a macro %pycached pode ajudar. Ele se expande para o arquivo fonte *.py fornecido e seus arquivos de cache correspondentes. Por exemplo:

expande aproximadamente para:

Cada pacote Python DEVE incluir Metadados de distribuição de pacotes em conformidade com especificações do PyPA (especificamente, Gravação de projetos instalados).

RECOMENDA-SE que os metadados sejam incluídos no mesmo subpacote que o módulo principal importável, se houver.

Isso se aplica a bibliotecas (por exemplo, python-requests), bem como a ferramentas (por exemplo, ansible).

Quando o software é dividido em vários subpacotes, não há problema em enviar metadados apenas em um RPM construído. Neste caso, considere trabalhar com o upstream para também dividir o projeto upstream.

Os metadados assumem a forma de um diretório .dist-info instalado em %{python3_sitelib} ou %{python3_sitearch} e contém informações que ferramentas como importlib.metadata usado para examinar bibliotecas instaladas.

Por exemplo, um projeto chamado MyLib com pacote importável mylib poderia ser empacotado com:

Observe que algumas ferramentas mais antigas colocam metadados em um diretório .egg-info ou até mesmo em um único arquivo. Isso não acontecerá se você usar a macro %pyproject_wheel. Se o seu pacote usa um sistema de construção que gera um diretório ou arquivo .egg-info, entre em contato com a Python SIG.

Como exceção, a biblioteca padrão Python PODE ser enviada sem esses metadados.

Os pacotes NÃO DEVEM possuir diretórios compartilhados pertencentes ao próprio Python, como os diretórios __pycache__ de nível superior (%{python3_sitelib}/__pycache__, %{python3_sitearch}/__pycache__).

Da mesma forma que a regra geral, RECOMENDA-SE que os empacotadores simplesmente agrupem tudo em um diretório compartilhado.

Além da lista geral, RECOMENDA-SE que o seguinte NÃO seja usado em %files:

Esta regra serve como uma verificação contra erros comuns que, de outra forma, seriam difíceis de detectar. Isso limita algumas possibilidades de automação.

Os erros mais comuns que esta regra evita são:

Para qualquer módulo destinado a ser usado em Python 3 com import MODNAME, RECOMENDA-SE que o pacote que o inclui forneça python3-MODNAME, com sublinhados (_) substituídos por traços (-).

É claro que este é sempre o caso se o pacote for denominado python3-MODNAME. Se o subpacote tiver algum outro nome, adicione %py_provides python3-MODNAME explicitamente. Consulte a seção a seguir para aprender sobre %py_provides.

Para qualquer FOO, RECOMENDA-SE que um pacote que fornece python3-FOO use %py_provides ou um gerador automático para fornecer também python-FOO e python3.X-FOO, onde X é a versão secundária do interpretador.

RECOMENDA-SE que o provide NÃO seja adicionado manualmente: se um gerador ou macro não for usado, não adicione os provides python-FOO / python3.X-FOO.

Isso é feito automaticamente para nomes de pacotes por um gerador. Se for absolutamente necessário, o gerador pode ser desativado indefinindo a macro %__pythonname_provides.

Para provides que não sejam nomes de pacotes ou (por motivos técnicos) para pacotes sem arquivos, o gerador não funcionará. Para estes casos, a seguinte invocação fornecerá python3-FOO, python-FOO e python3.X-FOO:

Usar o gerador ou macro é importante, pois a forma específica de fornecimento pode mudar no futuro.

Todo pacote Python DEVE fornecer python3dist(DISTNAME) e python3.Xdist(DISTNAME), onde X é a versão secundária do interpretador e DISTNAME é o Nome canônico do projeto correspondente aos [metadados Dist-info]. Por exemplo, python3-django forneceria python3dist(django) e python3.9dist(django).

Isso é gerado automaticamente a partir dos metadados dist-info. RECOMENDA-SE que o provide NÃO seja adicionado manualmente: se o gerador não conseguir adicioná-lo, os metadados DEVEM ser corrigidos.

Esses Provides são usados para Requires gerados automaticamente.

Se for absolutamente necessário, o gerador automático pode ser desativado indefinindo a macro %{?__pythondist_provides}. Considere discutir seu caso de uso com o Python SIG se você precisar fazer isso.

Como mencionado acima, cada pacote Python DEVE explicitamente ter BuildRequire python3-devel.

RECOMENDA-SE que os pacotes NÃO tenham dependências (em tempo de construção ou tempo de execução) com o prefixo não versionado python- se a dependência python3- correspondente puder ser usada em seu lugar.

RECOMENDA-SE que os pacotes NÃO tenham dependências explícitas (em tempo de construção ou tempo de execução) com um prefixo de versão secundária, como python3.8- ou python3.8dist(. RECOMENDA-SE que essas dependências sejam automaticamente geradas ou uma macro deve ser usada para obter a versão.

RECOMENDA-SE que os pacotes NÃO tenham uma dependência explícita de tempo de execução em python3.

Em vez de depender de python3, os pacotes têm uma dependência automática de python(abi) = 3.X quando instalam arquivos em %{python3_sitelib} ou %{python3_sitearch}, ou eles têm uma dependência automática de /usr/bin/python3 se tiverem scripts Python executáveis, ou têm uma dependência automática de libpython3.X.so.1.0() se incorporarem Python.

Essas regras ajudam a garantir um caminho de atualização tranquilo quando python3 é atualizado em novas versões do Fedora.

Os pacotes DEVEM usar o gerador automático de dependência em tempo de execução do Python.

RECOMENDA-SE que os pacotes usem o gerador de dependência de construção opcional, se possível.

O empacotador DEVE inspecionar os requisitos gerados quanto à correção. Todas as dependências DEVEM ser resolvidas na versão alvo do Fedora.

Quaisquer alterações necessárias DEVEM ser feitas por patches ou modificação da fonte (por exemplo, com sed), em vez de desabilitar o gerador. RECOMENDA-SE que a mudança resultante seja oferecida ao upstream. Como exceção, filtrado PODE ser usada para soluções alternativas temporárias e bootstrapping.

Dependencies covered by the generators SHOULD NOT be repeated in the .spec file. (For example, if the generator finds a requests dependency, then Requires: python3-requests is redundant.)

The automatically generated requirements are in the form python3.Xdist(DISTNAME), potentially augmented with version requirements or combined together with rich dependencies. Any .0 suffixes are removed from version numbers to match the behavior of Python tools. (PEP 440 specifies that X.Y and X.Y.0 are treated as equal.)

Note that the generators only cover Python packages. Other dependencies, often C libraries like openssl-devel, must be specified in the .spec file manually.

Where the requirements are specified in the source depends on each project’s build system and preferences. Common locations are pyproject.toml, setup.py, setup.cfg, config.toml.

See the Tests section.

Python extras are a way for Python projects to declare that extra dependencies are required for additional functionality.

For example, requests has several standard dependencies (e.g. urllib3). But it also declares an extra named requests[security], which lists additional dependencies (e.g. cryptography). Unlike RPM subpackages, extras can only specify additional dependencies, not additional files. The main package will work if the optional dependency is not installed, but it might have limited functionality.

Python tools treat extras as virtual packages. For example, if a user runs pip install 'requests[security]', or installs a project that depends on requests[security], both requests and cryptography will be installed.

In Fedora, extras are usually provided by packages with no files. Instead of square brackets, Fedora package names conventionally use the + character (which is valid in RPM package names, but not in Python canonical project names nor in extras identifiers).

Shebang lines to invoke Python MUST use %{python3} as the interpreter.

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

If (some of) the default flags from the %{py3_shebang_flags} macro are not desirable, packages SHOULD explicitly redefine the macro to remove them by undefining the relevant %{_py3_shebang_...} macro.

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).

By default, -%{py3_shebang_flags} expands to -sP (or just -s on Python version lower than 3.11 and Fedora Linux older than 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.