Setup e Wheels

O termo “third party” (com um “pacote de terceiros”) referencia-se a alguém que tenha como principal função desenvolvedor do core do Python (“primeiro grupo”) ou o desenvolvedor local (“segundo grupo”).

Instalamos pacotes do “primeiro grupo” na instalação do Python. Usamos o pip e virtualenv para instalar “pacotes de terceiros”. Agora vamos para o segundo grupo.

Vamos ver novas adições, como pyproject.toml e flit. Contudo, é importante entender a maneira clássica de fazer as coisas. Por um lado, demora um tempo para aplicar as novas práticas recomendadas. Por outro lado, há práticas que são baseadas na setup.py, e isso continuará por muito tempo.

O arquivo descrito no setup.py, no código, na nossa “distribuição”. Veja que “distribuição” é diferente do “pacote”. Um pacote é um diretório com (geralmente) __init__.py o qual o Python pode importar.

Uma distribuição pode conter vários pacotes ou até mesmo nenhum! Contudo, é uma boa ideia manter a relação 1-1-1: um distribuição, um pacote, com o mesmo nome.

Geralmente, setup.py irá começar importando setuptools ou distutils. Enquanto distutils já vem com a ferramenta, setuptools não é. Contudo, ele quase sempre é instalado primeiro no ambiente virtual, devido a sua grande popularidade.

Distutils não é recomendado: por não ter uma atualização a muito tempo. Veja que setup.py não pode significativamente, explicitamente, declarar que precisamos do setuptools nem explicitar a necessidade de uma versão específica.

O mínimo setup.py irá funcionar assim:

A documentação oficial chama muitos outros campos “necessários” por alguma razão, o pacote pode ser construído mesmo que o pacote esteja faltando. Para alguns, os pacotes ficará com um nomes horríveis, tais como UNKNOWN.

Muito desses campos, claro, são bons para ter. Mas essa estrutura do setup.py não é suficiente para criar uma distribuição local de pacotes do Python no diretório.

Admito que quase sempre, terá outros campos para adicionar. É definitivamente o caso que há outros campos que você precisará adicionar nesse pacote, eles serão carregados em um pacote indexado, mesmo se for um indexado privado.

É uma boa ideia adicionar pelo menos o “nome” do campo. Isso te dará um nome para a distribuição. É quase sempre um boa ideia nomeá-lo depois do pacote top-level da distribuição.

Uma típica hierarquia de código, seria parecido com essa:

Outro campo que é uma boa ideia ter é a versão. Versionar um software é sempre difícil. Mesmo sendo um número contínuo, é uma boa maneira de responder: “O que está rodando, uma versão nova ou velha?”

Há algumas ferramentas que podem ajudar com o controle da versão, especialmente assumindo que queremos disponibilizar para o Python em execução.

Especialmente se fizer com o Calendar Versioning, que automatiza algumas coisas que são chatas. bumpversion é uma ferramenta útil, especialmente quando escolhemos uma versão semântica.

Finalmente, o versioneer tem uma fácil integração com o sistema de controle de versão git, então uma tag é tudo o que precisa ser feito para uma nova versão.

Outro campo popular no setup.py, o qual não é marcado como “necessário” na documentação, mas está presente em quase todos os pacotes, é o install_requires.

Isso é como marcamos outras distribuições que nosso código utiliza. É uma boa prática colocar “loose” dependências no setup.py. Isso contrasta com dependências exatas, o qual específica uma versão específica.

Uma dependência loose é algo assim: Twisted >=17.5 – especificando a mínima versão, mas não a máxima. Dependências exatas é algo assim: Twisted==18.1, é uma má ideia fazer isso no setup.py. Só se for em um caso especial.

Por fim, é uma boa idéia fornecer aos find_packages uma lista de permissões, para evitar arquivos espúrios. Por exemplo,

setuptools.find_packages(include=[“my_package∗”])

Tendo o setup.py e algum código Python, podemos criar uma distribuição. Há vários formatos de distribuição, veremos o wheel. Se meu-diretorio é o que tem o setup.py, execute pip wheel meu-diretorio, isso produzirá um wheel, como também os wheels de todas as dependências.

Por padrão coloca-se o wheels no diretório que se encontra, mas geralmente não é o que queremos. Utilizando –wheels-dir<diretório-de-saída> você pode colocar o wheel e qualquer dependência na pasta que você deseja.

Há muitas coisas que nós podemos fazer com o wheels, mas o importante é que podemos fazer é pip install <arquivo wheel>. Podemos também fazer assim: pip install <arquivo wheel> –wheel-dir <diretório de saída>, então o pip usará o wheels no diretório e não sairá do PyPI. Isso é útil para reproduzir instalações, ou fornecer no modo air-gapped.

Fonte: DevOps in Python: Infrastructure as Python