Empacotamento Python

Guia completo para criar, estruturar e distribuir pacotes Python usando ferramentas de empacotamento modernas, pyproject.toml e publicação no PyPI.

Quando Usar Esta Habilidade

• Criar bibliotecas Python para distribuição
• Construir ferramentas de linha de comando com pontos de entrada (entry points)
• Publicar pacotes no PyPI ou em repositórios privados
• Configurar a estrutura de projetos Python
• Criar pacotes instaláveis com dependências
• Construir distribuições wheel e de código-fonte (source distributions)
• Versionar e lançar pacotes Python
• Criar pacotes de namespace (namespace packages)
• Implementar metadados e classificadores de pacotes

Conceitos Principais

1. Estrutura do Pacote

• Layout de origem (Source layout): src/package_name/ (recomendado)
• Layout plano (Flat layout): package_name/ (mais simples, mas menos flexível)
• Metadados do pacote: pyproject.toml, setup.py ou setup.cfg
• Formatos de distribuição: wheel (.whl) e distribuição de código-fonte (.tar.gz)

2. Padrões Modernos de Empacotamento

• PEP 517/518: Requisitos do sistema de build
• PEP 621: Metadados em pyproject.toml
• PEP 660: Instalações editáveis (editable installs)
• pyproject.toml: Única fonte de configuração

3. Backends de Build

• setuptools: Tradicional, amplamente utilizado
• hatchling: Moderno, opinativo
• flit: Leve, para Python puro
• poetry: Gerenciamento de dependências + empacotamento

4. Distribuição

• PyPI: Python Package Index (público)
• TestPyPI: Teste antes da produção
• Repositórios privados: JFrog, AWS CodeArtifact, etc.

Início Rápido

Estrutura Mínima de Pacote

my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
└── tests/
    └── test_module.py

pyproject.toml Mínimo

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "0.1.0"
description = "A short description"
authors = [{name = "Your Name", email = "you@example.com"}]
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=22.0",
]

Padrões de Estrutura de Pacote

Padrão 1: Layout de Origem (Recomendado)

my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── .gitignore
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       ├── utils.py
│       └── py.typed          # For type hints
├── tests/
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
└── docs/
    └── index.md

Vantagens:

• Impede a importação acidental a partir do código-fonte
• Importações de teste mais limpas
• Melhor isolamento

pyproject.toml para layout de origem:

[tool.setuptools.packages.find]
where = ["src"]

Padrão 2: Layout Plano

my-package/
├── pyproject.toml
├── README.md
├── my_package/
│   ├── __init__.py
│   └── module.py
└── tests/
    └── test_module.py

Mais simples, mas:

• Permite importar o pacote sem instalá-lo
• Menos profissional para bibliotecas

Padrão 3: Projeto com Múltiplos Pacotes

project/
├── pyproject.toml
├── packages/
│   ├── package-a/
│   │   └── src/
│   │       └── package_a/
│   └── package-b/
│       └── src/
│           └── package_b/
└── tests/

Padrões Detalhados e Exemplos Práticos

A documentação detalhada dos padrões está em references/details.md. Leia este arquivo quando a navegação acima for insuficiente.