Noções Básicas de Empacotamento

9 exemplos para você começar com Empacotamento e Publicação - 6 básicos e 3 intermediários.

Pré-requisitos

• Python 3.14.0 com uv 0.6+ ou pip
• Um projeto com pyproject.toml e layout src/
• Conta PyPI (ou TestPyPI) para exemplos de publicação

Exemplos Básicos

1. Construir um Wheel

Um wheel (.whl) é o formato de distribuição binária padrão.

uv build
ls dist/
# myapp-0.1.0-py3-none-any.whl
# myapp-0.1.0.tar.gz

• uv build cria wheel e sdist em dist/
• py3-none-any significa Python puro, qualquer plataforma
• Wheels instalam mais rápido que sdists (sem etapa de build)
• Nunca comite dist/ - construa em CI

Relacionado: Build Backends - hatchling vs setuptools

2. pyproject.toml para Empacotamento

Metadados do pacote ficam em [project].

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = ["httpx>=0.28"]
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

• name é o nome do pacote PyPI (minúsculas, hifens)
• version segue SemVer
• [build-system] declara o backend de build
• O nome de importação pode ser diferente do nome do pacote (my_app vs my-app)

Relacionado: pyproject.toml Explicado

3. Layout src

Mantenha o código fonte em src/ para empacotamento e testes confiáveis.

myapp/
├── pyproject.toml
├── src/myapp/
│   ├── __init__.py
│   └── core.py
└── tests/

• src/ impede importações acidentais da raiz do repositório
• O backend de build descobre pacotes a partir da configuração
• Testes importam o pacote instalado
• Padrão da indústria para novos projetos

4. Instalar a Partir de um Build Local

Teste seu pacote antes de publicar.

uv build
uv pip install dist/myapp-0.1.0-py3-none-any.whl
python -c "import myapp; print(myapp.__version__)"

• Instale o wheel para verificar se o empacotamento está correto
• Detecta arquivos ausentes e erros de importação
• Teste em um venv novo para precisão
• Teste também pip install . (caminho sdist)

5. Versionar seu Pacote

Exponha a versão em __init__.py ou use versionamento dinâmico.

[project]
version = "0.1.0"

# src/myapp/__init__.py
__version__ = "0.1.0"

• Fonte única de verdade em pyproject.toml é preferível
• Versionamento dinâmico a partir de tags git com hatchling
• SemVer: MAJOR.MINOR.PATCH
• Pré-lançamento: 0.2.0b1

Relacionado: Versionamento e Changelogs

6. Ponto de Entrada de Script de Console

Envie um comando CLI com seu pacote.

[project.scripts]
myapp = "myapp.cli:main"

# src/myapp/cli.py
def main() -> None:
    print("Hello from myapp CLI")

• Instalado em .venv/bin/myapp ao usar pip install
• Usa project.scripts em pyproject.toml
• A função não recebe argumentos (usa argparse/click internamente)
• Teste com uv pip install -e . e depois myapp

Relacionado: Entry Points & Console Scripts

Exemplos Intermediários

7. Publicar no TestPyPI

Simule a publicação antes do PyPI de produção.

uv build
uv publish --index testpypi
# Instalar teste:
uv pip install --index-url https://test.pypi.org/simple/ myapp

• TestPyPI é um registro sandbox
• Verifique se os metadados, a instalação e a CLI funcionam
• Use publicação confiável (OIDC) em CI, não senhas
• Promova para PyPI após a verificação no TestPyPI

Relacionado: Publicando no PyPI

8. Incluir Dados do Pacote

Envie arquivos não-Python (templates, configurações padrão).

[tool.hatch.build.targets.wheel]
packages = ["src/myapp"]
 
[tool.hatch.build.targets.wheel.force-include]
"src/myapp/templates" = "myapp/templates"

• Templates, esquemas JSON e assets estáticos precisam de inclusão explícita
• force-include mapeia a origem para o caminho de instalação
• Use importlib.resources para acessar em tempo de execução
• Verifique com pip install e inspecione o site-packages

9. Construir em CI

Automatize a construção de wheels em cada tag de release.

- run: uv build
- uses: actions/upload-artifact@v4
  with:
    name: dist
    path: dist/

• Artefatos de build anexados a releases do GitHub
• O mesmo wheel publicado no PyPI a partir da CI
• Assinatura GPG opcional para pacotes de alta segurança
• cibuildwheel para extensões nativas multi-plataforma

Relacionado: Melhores Práticas de Empacotamento

Versões da Stack: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.