O fluxo do empacotamento

O documento visa delinear o fluxo envolvido na publicação/distribuição de um pacote de distribuição, geralmente para o Python Package Index (PyPI). Ele é escrito para editores de pacotes, que são considerados os autores do pacote.

Enquanto o tutorial percorre o processo de preparação de um pacote simples para lançamento, ele não enumera completamente quais etapas e arquivos são necessários e para qual finalidade.

A publicação de um pacote requer um fluxo do código-fonte do autor para o ambiente Python de um usuário final. Os passos para conseguir isso são:

  • Tenha uma árvore de fontes contendo o pacote. Este é normalmente um checkout de um sistema de controle de versão (VCS).

  • Prepare um arquivo de configuração descrevendo os metadados do pacote (nome, versão e assim por diante) e como criar os artefatos de construção. Para a maioria dos pacotes, este será um arquivo pyproject.toml, mantido manualmente na árvore de fontes.

  • Crie artefatos de construção para serem enviados ao serviço de distribuição de pacotes (geralmente PyPI); normalmente serão uma distribuição fonte (“sdist”) e uma ou mais distribuições construídas (“wheels”). Eles são feitos por uma ferramenta de construção usando o arquivo de configuração da etapa anterior. Muitas vezes, há apenas uma wheel genérica para um pacote puro Python.

  • Envie os artefatos de construção para o serviço de distribuição de pacotes.

Nesse ponto, o pacote está presente no serviço de distribuição de pacotes. Para usar o pacote, os usuários finais devem:

  • Baixe um dos artefatos de construção do pacote do serviço de distribuição de pacotes.

  • Instale-o em seu ambiente Python, geralmente em seu diretório site-packages. Esta etapa pode envolver uma etapa de construção/compilação que, se necessário, deve ser descrita pelos metadados do pacote.

Estes últimos 2 passos são normalmente executados por pip quando um usuário final executa pip install.

As etapas acima são descritas com mais detalhes abaixo.

A árvore fonte

A árvore fonte contém o código-fonte do pacote, geralmente um checkout de um VCS. A versão específica do código usado para criar os artefatos de compilação normalmente será um checkout com base em uma tag associada à versão.

O arquivo de configuração

O arquivo de configuração depende da ferramenta usada para criar os artefatos de construção. A prática padrão é usar um arquivo pyproject.toml no formato TOML.

No mínimo, o arquivo pyproject.toml precisa de uma tabela [build-system] especificando sua ferramenta de construção. Existem muitas ferramentas de construção disponíveis, incluindo, mas não se limitando a flit, hatch, pdm, poetry, setuptools, ` trampolim`_ e whey. A documentação de cada ferramenta mostrará o que colocar na tabela [build-system].

Por exemplo, aqui está uma tabela para usar hatch:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Com tal tabela no arquivo pyproject.toml, uma ferramenta “frontend” como construir pode executar o “backend” da ferramenta de compilação escolhida para criar os artefatos de compilação. Sua ferramenta de compilação também pode fornecer seu próprio frontend. Uma ferramenta de instalação como pip também atua como frontend quando executa o backend da sua ferramenta de construção para instalar a partir de uma distribuição fonte.

A ferramenta de construção específica que você escolhe determina quais informações adicionais são necessárias no arquivo pyproject.toml. Por exemplo, você pode especificar:

Artefatos de construção

A distribuição fonte (sdist)

Uma distribuição fonte contém o suficiente para instalar o pacote fonte no ambiente Python de um usuário final. Como tal, ele precisa da fonte do pacote e também pode incluir testes e documentação. Eles são úteis para usuários finais que desejam desenvolver suas fontes e para sistemas de usuários finais onde alguma etapa de compilação local é necessária (como uma extensão C).

O pacote construir sabe como invocar sua ferramenta de construção para criar uma destas:

python3 -m build --sdist source-tree-directory

Ou sua ferramenta de construção pode fornecer sua própria interface para criar um sdist.

As distribuições de construídas (wheels)

Uma distribuição construída contém apenas os arquivos necessários para o ambiente Python de um usuário final. Nenhuma etapa de compilação é necessária durante a instalação, e o arquivo wheel pode simplesmente ser descompactado no diretório site-packages. Isso torna a instalação mais rápida e conveniente para os usuários finais.

Um pacote puro Python normalmente precisa apenas de um wheel “genérico”. Um pacote com extensões binárias compiladas precisa de um wheel para cada combinação suportada de interpretador Python, sistema operacional e arquitetura de CPU que ele suporta. Se um arquivo wheel adequado não estiver disponível, ferramentas como pip voltarão a instalar a distribuição fonte.

O pacote construir sabe como invocar sua ferramenta de construção para criar uma destas:

python3 -m build --wheel source-tree-directory

Ou sua ferramenta de construção pode fornecer sua própria interface para criar um wheel.

Nota

O comportamento padrão do construir é fazer tanto um sdist quanto um wheel da fonte no diretório atual; os exemplos acima são deliberadamente específicos.

Enviando os arquivos de distribuição

A ferramenta twine pode enviar artefatos de construção para PyPI para distribuição, usando um comando como:

twine upload dist/package-name-version.tar.gz dist/package-name-version-py3-none-any.whl

Ou sua ferramenta de construção pode fornecer sua própria interface para envio.

Baixando e instalando

Agora que o pacote foi publicado, os usuários finais podem baixar e instalar o pacote em seu ambiente Python. Normalmente isso é feito com pip, usando um comando como:

python3 -m pip install package-name

Os usuários finais também podem usar outras ferramentas como Pipenv, poetry ou pdm.