Python package guidelines (Português)
32-bit – CLR – CMake – Cross – DKMS – Eclipse – Electron – Fonte – Free Pascal – GNOME – Go – Haskell – Java – KDE – Kernel – Lisp – Meson – MinGW – Node.js – Nonfree – OCaml – Perl – PHP – Python – R – Ruby – Rust – Shell – VCS – Web – Wine
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.
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
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.
depends
caso contrário elas não serão instaladas.Baseado em padrões (PEP 517)
$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 emdepends
), 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 parainstaller
, mas o padrão é escolhido com sensatez, então isso não deve ser necessário.
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).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çãobuild()
, 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
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
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.