Jump to content

# Python package guidelines (Português)

4 languages

- English
- 日本語
- Русский
- 中文（简体）

From ArchWiki
Status de tradução: Esse artigo é uma tradução de Python package guidelines. Data da última tradução: 2024-02-27. Você pode ajudar a sincronizar a tradução, se houver alterações na versão em inglês.

Esse documento cobre padrões e diretrizes na escrita de PKGBUILDs para softwares Python.

## Nome do pacote

Para módulos de biblioteca do Python 3, use `python-nomemódulo`. Também use o prefixo se o pacote fornece um programa fortemente atrelado ao ecossistema do Python (p. ex. pip or tox). Para outros aplicativos, use apenas o nome do programa.

Nota: O nome do pacote deve estar todo em minúsculo.

## Arquitetura

Veja PKGBUILD (Português)#arch.

Um pacote Python que contenha extensões C é dependente de arquitetura. Do contrário, muito provavelmente terá nenhuma dependência de arquitetura.

Pacotes compilados usando setuptools definem suas extensões C usando a palavra-chave `ext_modules` no `setup.py`.

## Fonte

Nota: Com RFC0020, o padrão é usar tarballs fonte fornecidas pelo upstream, em vez dos tarballs sdist fornecidos pelo PyPI.

As URLs de download vinculadas do site do PyPI incluem um hash imprevisível que precisa ser obtido no site do PyPI sempre que um pacote precisar ser atualizado. Isso os torna inadequados para uso em um PKGBUILD. PyPI fornece um esquema estável alternativo: array PKGBUILD (Português)#source `source=()` deve usar os seguintes modelos de URL:

Pacote fonte
  `https://files.pythonhosted.org/packages/source/${_name::1}/$_name/$_name-$pkgver.tar.gz`
Pacote wheel Python puro
  `https://files.pythonhosted.org/packages/py2.py3/${_name::1}/$_name/${_name//-/_}-$pkgver-py2.py3-none-any.whl` (Bilíngue compatível com Python 2 e Python 3):`https://files.pythonhosted.org/packages/py3/${_name::1}/$_name/${_name//-/_}-$pkgver-py3-none-any.whl` (Python 3 apenas)
  Note que o nome da distribuição pode conter traços, enquanto sua representação em um nome de arquivo wheel não pode (eles são convertidos em sublinhados).
Pacote wheel específico para arquitetura
  Arrays adicionais específicos para arquiteturas podem ser adicionados adicionando ao final um underscore e o nome da arquitetura, por exemplo, `source_x86_64=('...')`. Também `_py=cp310` pode ser usado para não repetir a versão do Python:
  `https://files.pythonhosted.org/packages/$_py/${_name::1}/$_name/{_name//-/_}-$pkgver-$_py-${_py}m-manylinux1_x86_64.whl`

Note que uma variável personalizada `$_name` é usada em vez de `pkgname` já que nomes de pacotes python são geralmente prefixados com `python-`. Essa variável pode ser definida genericamente da seguinte forma:

    _name=${pkgname#python-}

## Métodos de instalação

Os pacotes Python geralmente são instalados usando um gerenciador de pacotes específico da linguagem, como o pip, o qual busca pacotes de um repositório online (geralmente PyPI, o Python Package Index) e rastreia os arquivos relevantes.

No entanto, para gerenciar pacotes Python de dentro de `PKGBUILD`s, é necessário "instalar" o pacote Python no local temporário `$pkgdir/usr/lib/python<versão do Python>/site-packages/$pkgname`.

Para pacotes Python usando metadados padrão para especificar seu back-end de compilação em `pyproject.toml`, isso pode ser alcançado mais facilmente usando python-build e python-installer. Pacotes antigos podem não especificar que usam setuptools e oferecer apenas um `setup.py` que deve ser invocado manualmente.

Nota: As dependências dos metadados do pacote devem ser definidas no array `depends` caso contrário elas não serão instaladas.

### Baseado em padrões (PEP 517)

Dica: Ao construir a partir de tarballs fonte fornecidos pelo upstream e o upstream depende do git para derivar uma string de versão para o projeto, é necessário definir variáveis de ambiente específicas da ferramenta para `$pkgver` antes de construir uma wheel:

- python-setuptools-scm and python-hatch-vcs: `SETUPTOOLS_SCM_PRETEND_VERSION`
- python-pbr: `PBR_VERSION`
- python-pdm-backend: `PDM_BUILD_SCM_VERSION`

Um fluxo de trabalho baseado em padrões é simples: gere um wheel usando python-build e instale-o em `$pkgdir` usando python-installer:

    makedepends=(python-build python-installer python-wheel)

    build() {
        cd "$_name-$pkgver"
        python -m build --wheel --no-isolation
    }

    package() {
        cd "$_name-$pkgver"
        python -m installer --destdir="$pkgdir" dist/*.whl
    }

sendo:

- `--wheel` resulta em apenas um arquivo wheel a ser construído, sem distribuição de código-fonte.
- `--no-isolation` significa que o pacote é compilado usando o que está instalado em seu sistema (que inclui pacotes que você especificou em `depends`), por padrão a ferramenta cria um pacote isolado ambiente virtual e executa a construção lá.
- `--destdir="$pkgdir"` evita a tentativa de instalar diretamente no sistema hospedeiro em vez do arquivo de pacote, que resultaria em um erro de permissão
- `--compile-bytecode=...` ou `--no-compile-bytecode` pode ser passado para `installer`, mas o padrão é escolhido com sensatez, então isso não deve ser necessário.

Atenção: Ignorar `build` e colocar o arquivo `.whl` em seu array `source` é desencorajado em favor da compilação a partir do código-fonte e só deve ser usado quando o esta última não é uma opção viável (por exemplo, pacotes que apenas vêm com fontes wheel e, portanto, não podem ser compilados a partir do código-fonte).
Atenção: Se o seu pacote for um pacote VCS (`python-…-git`), inclua o comando `git -C "${srcdir}/${pkgname}" clean -dfx` em sua função `prepare`. Isso remove wheels obsoletos junto com outros artefatos de compilação e ajuda a evitar problemas futuros. Consulte também problemas upstream para setuptools e Poetry.

### setuptools ou distutils

Se nenhum `pyproject.toml` puder ser encontrado ou não contiver uma tabela `[build-system]`, significa que o projeto está usando o antigo formato legado, que usa um setup.py arquivo que invoca setuptools ou distutils. Observe que embora distutils esteja incluído na biblioteca padrão do Python, ter setuptools instalado significa que você usa uma versão corrigida de distutils.

    makedepends=('python-setuptools')  # a menos que exiga somente distutils

    build() {
        cd "$_name-$pkgver"
        python setup.py build
    }

    package() {
        cd "$_name-$pkgver"
        python setup.py install --root="$pkgdir" --optimize=1
    }

sendo:

- `--root="$pkgdir"` funciona igual ao `--destdir` acima
- `--optimize=1` compila arquivos de bytecode otimizados (.opt-1.pyc) para que possam ser rastreados pelo pacman em vez de serem criados no sistema host em demanda.
- Adicionar `--skip-build` otimiza a tentativa desnecessária de executar novamente as etapas de construção já executadas na função `build()`, se for esse o caso.

Alguns pacotes tentam usar setuptools e voltam para distutils se setuptools não puder ser importado. Neste caso, setuptools deve ser adicionado como `makedepends`, para que os metadados Python resultantes sejam melhores.

Se um pacote precisar que setuptools seja compilado devido à inclusão de executáveis (o que não é suportado por distutils), mas apenas importa distutils, então a compilação gerará um aviso, e o pacote resultante estará quebrado (não conterá os executáveis):

    /usr/lib/python3.8/distutils/dist.py:274: UserWarning: Unknown distribution option: 'entry_points'
      warnings.warn(msg)

Neste caso, deve-se relatar um bug no upstream. Para contornar o problema, um recurso de ferramentas de configuração não documentado pode ser usado:

    # fails because of distutils
    python setup.py build

    # works by using a setuptools shim
    python -m setuptools.launch setup.py build

Se um pacote usar python-setuptools-scm, o pacote provavelmente não será compilado com um erro como:

    LookupError: setuptools-scm was unable to detect version for /build/python-jsonschema/src/jsonschema-3.2.0.

    Make sure you're either building from a fully intact git repository or PyPI tarballs. Most other sources (such as GitHub's tarballs, a git checkout without the .git folder) don't contain the necessary metadata and will not work.

Para corrigir a compilação, `SETUPTOOLS_SCM_PRETEND_VERSION` deve ser exportado como uma variável de ambiente com `$pkgver` como valor:

    export SETUPTOOLS_SCM_PRETEND_VERSION=$pkgver

## Verificação

Atenção: Evite usar o `tox` para executar os testsuites, pois ele é projetado explicitamente para testar as configurações repetidas baixadas do PyPI enquanto `tox` está sendo executado, e não testa a versão que será instalado pelo pacote. Isso anula o propósito de ter uma função check.

A maioria dos projetos Python que fornecem testsuites (que são conjunto ou coleção de testes) usam nosetests ou pytest para executar os testes com `test` no nome do arquivo ou diretório contendo a testsuite. Em geral, só executar `nosetests` ou `pytest` é o suficiente para executar a testsuite.

    check(){
        cd "$srcdir/foo-$pkgver"

        # Para nosetests
        nosetests

        # Para pytest
        pytest
    }

Se houver uma extensão C compilada, os testes precisam ser executados usando um `$PYTHONPATH`, que reflete a versão maior e menor do Python, para localizá-la e carregá-la.

    check(){
      cd "$pkgname-$pkgver"
      local python_version=$(python -c 'import sys; print("".join(map(str, sys.version_info[:2])))')
      # Para nosetests
      PYTHONPATH="$PWD/build/lib.linux-$CARCH-cpython-${python_version}" nosetests

      # Para pytest
      PYTHONPATH="$PWD/build/lib.linux-$CARCH-cpython-${python_version}" pytest
    }

Alguns projetos fornecem pontos de entrada no `setup.py` para executar o teste. Isso funciona para `pytest` e `nosetests`.

    check(){
        cd "$srcdir/foo-$pkgver"

        # para nosetests
        python setup.py nosetests

        # Para pytest - precisa de python-pytest-runner
        python setup.py pytest
    }

## Dicas e truques

### Descobrindo assinaturas PGP desanexadas no PyPI

Atenção: Em 2023-05-23, o PyPI removeu a funcionalidade para fornecer assinaturas OpenPGP desanexadas.

Se existirem assinaturas PGP desanexadas para um determinado tarball sdist do Python, elas deverão ser usadas para verificar o tarball. No entanto, os arquivos de assinatura não aparecem diretamente na seção de download de arquivos de qualquer projeto em pypi.org. Para descobrir os tarballs sdist e seus possíveis arquivos de assinatura, é possível usar este serviço para obter uma visão geral por projeto: https://pypi.debian.net/

Para python-requests, seria https://pypi.debian.net/requests.

### Usando versão do Python

Às vezes, durante a preparação, compilação, teste ou instalação, é necessário consultar a versão principal e secundária do Python do sistema. Não codifique isso (por exemplo, `3.9` ou `3.10`) e, em vez disso, use uma chamada ao interpretador Python para recuperar as informações e armazená-las em uma variável local:

    check(){
      local python_version=$(python -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
      ...
    }

### Usando site-packages

Às vezes, durante a compilação, o teste ou a instalação, é necessário consultar o diretório `site-packages` do sistema. Não adicione este diretório literalmente (hardcoded) e, em vez disso, use uma chamada para o interpretador Python para recuperar o caminho e armazená-lo em uma variável local:

    check(){
      local site_packages=$(python -c "import site; print(site.getsitepackages()[0])")
      ...
    }

### Diretório de teste em site-package

Certifique-se de não instalar um diretório de nome `tests` ao `site-packages` (ou seja, `/usr/lib/pythonX.Y/site-packages/tests/`). Projetos de pacotes Python que usam setuptools às vezes são configurados incorretamente para incluir o diretório que contém seus testes como um pacote Python de nível superior. Se você encontrar isso, você pode ajudar registrando um problema no projeto do pacote e pedindo que eles corrijam isso. Por exemplo, assim.

Category:

- Arch package guidelines (Português)