Empacotamento é o processo de organizar código em pacotes reutilizáveis.
Distribuição significa publicar esses pacotes para outras pessoas.
Primeiramente, um pacote Python é uma pasta com um arquivo __init__.py.
Esse arquivo pode estar vazio ou conter código de inicialização.
Além disso, usamos o setuptools para criar pacotes distribuíveis.
O arquivo setup.py descreve metadados como nome e versão.
Quando utilizar empacotamento? Sempre que seu código for reutilizado em múltiplos projetos.
Por exemplo, uma biblioteca de validação ou utilitários matemáticos.
A voz passiva é usada aqui: “as dependências são listadas no install_requires“.
Portanto, o empacotamento evita copiar e colar arquivos manualmente.
Também facilita o controle de versões e a instalação via pip.
Outra ferramenta moderna é o pyproject.toml (PEP 621).
Ela substitui setup.py com uma sintaxe mais simples e declarativa.
Vamos explorar os principais conceitos passo a passo.
Estrutura básica de um pacote
Um pacote bem estruturado segue uma convenção clara.
Crie uma pasta principal com o nome do seu projeto.
Dentro dela, coloque um arquivo __init__.py (pode ser vazio).
Adicione seus módulos .py ao lado desse arquivo.
Por exemplo, meu_pacote/calculadora.py contendo funções matemáticas.
Fora da pasta, crie setup.py ou pyproject.toml.
Também é comum incluir README.md, LICENSE e tests/.
A estrutura mínima se parece com isto:
|
1 2 3 4 5 6 7 8 |
meu_projeto/ ├── meu_pacote/ │ ├── __init__.py │ └── core.py ├── tests/ │ └── test_core.py ├── setup.py └── README.md |
Essa organização é reconhecida pelo setuptools e pelo pip.
Quando usar essa estrutura? Em qualquer biblioteca que você planeja publicar.
Mesmo pacotes internos de empresas se beneficiam dela.
Foi observado que projetos sem empacotamento viram “spaguetti code”.
Portanto, invista meia hora para estruturar corretamente desde o início.
Criando e instalando com setup.py
O arquivo setup.py é o coração do empacotamento tradicional.
Ele usa a função setup() do módulo setuptools.
Você define nome, versão, autor e dependências.
Um exemplo típico contém os seguintes parâmetros:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# setup.py from setuptools import setup, find_packages setup( name="meu_pacote", version="0.1.0", author="Seu Nome", description="Um pacote exemplo", packages=find_packages(), install_requires=[ "requests>=2.25.0", "numpy", ], python_requires=">=3.8", ) |
Após criar esse arquivo, instale o pacote em modo desenvolvimento:
pip install -e .
O flag -e significa editável – mudanças no código refletem imediatamente.
Para gerar um arquivo distribuível (wheel), execute:
python setup.py bdist_wheel
O arquivo .whl será criado na pasta dist/.
Esse wheel pode ser instalado com pip install meu_pacote-0.1.0-py3-none-any.whl.
A voz passiva é aplicada: “o wheel é gerado com o comando acima”.
Assim, você pode compartilhar o binário sem enviar o código-fonte.
Contudo, para pacotes abertos, prefira publicar no PyPI (Python Package Index).
Publicando no PyPI e usando pyproject.toml
O PyPI é o repositório oficial de pacotes Python.
Publicar nele permite instalação com pip install seu_pacote.
Primeiro, crie uma conta em pypi.org e obtenha um token de API.
Depois, instale twine com pip install twine.
Envie seu pacote com twine upload dist/*.
Mas atenção: a ferramenta moderna recomenda pyproject.toml.
Esse arquivo unifica configurações de build, lint e testes.
Um exemplo mínimo de pyproject.toml:
|
1 2 3 4 5 6 7 8 9 10 11 |
[build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "meu_pacote" version = "0.1.0" description = "Exemplo com pyproject.toml" authors = [{name = "Seu Nome", email = "email@exemplo.com"}] dependencies = ["requests>=2.25.0"] requires-python = ">=3.8" |
Com esse arquivo, não precisa mais de setup.py.
Execute python -m build para gerar os distributíveis.
O comando cria pastas dist/ e build/ automaticamente.
Quando usar pyproject.toml? Em todos os projetos novos.
Ele é o padrão da comunidade e será o futuro do empacotamento.
Por fim, lembre-se de versionar seu pacote semanticamente.
Use \(\text{versão} = \text{major.minor.patch}\) conforme a especificação.
Isso ajuda usuários a saber se há mudanças que quebram compatibilidade.
Distribuir bem seu código é um ato de generosidade com a comunidade.
Comece hoje mesmo a empacotar suas próprias bibliotecas!