Backends de Build
Backends de build transformam sua árvore de código-fonte em wheels e sdists distribuíveis. Hatchling é o padrão moderno; setuptools continua comum para projetos legados.
Receita
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"uv buildQuando usar isso:
- Configurando como seu pacote é construído
- Migrando de
setup.pyparapyproject.toml - Construindo pacotes com módulos de extensão
Exemplo Funcional
[project]
name = "invoice-sdk"
version = "0.2.0"
requires-python = ">=3.14"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["src/invoice_sdk"]
[tool.hatch.build.targets.sdist]
include = ["src/", "tests/", "README.md"]uv build
tar -tzf dist/invoice-sdk-0.2.0-py3-none-any.whl | head
# invoice_sdk/__init__.py
# invoice_sdk/client.pyO que isso demonstra:
- Backend
hatchling.buildespecificado em[build-system] packagesinforma ao hatchling onde o código-fonte resideuv buildproduz wheel e sdist- O conteúdo do wheel pode ser inspecionado antes da publicação
Mergulho Profundo
Comparação de Backends
| Backend | Melhor para | Configuração |
|---|---|---|
| hatchling | Novos projetos | [tool.hatch.*] |
| setuptools | Legado, extensões | [tool.setuptools.*] |
| poetry-core | Projetos Poetry | [tool.poetry] |
| maturin | Extensões Rust | [tool.maturin] |
| cffi/setuptools | Extensões C | setup.py + pyproject |
Armadilhas
- Configuração de
packagesausente - wheel vazio. Correção: configure a descoberta de pacotes em[tool.hatch.build]. - Backend de build incorreto para extensões - build falha. Correção: maturin para Rust, setuptools para C.
setup.pydesatualizado ao lado de pyproject - metadados conflitantes. Correção: migre completamente; exclua setup.py.- Construindo na plataforma errada - wheel específico da plataforma no SO errado. Correção: cibuildwheel para multiplataforma.
- Não testar o wheel construído - arquivos ausentes descobertos na publicação. Correção:
pip install dist/*.whlantes do upload.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| setuptools | Configuração setuptools existente | Projeto Greenfield |
| flit | Pacote único simples | Monorepos complexos |
| PDM backend | Projeto gerenciado por PDM | Loja uv/hatchling |
FAQs
Qual backend para novos projetos?
hatchling. Configuração mínima, rápido, nativo PEP 621.
Preciso de setup.py?
Não com a configuração pyproject.toml do hatchling ou setuptools.
Como construir apenas um sdist?
uv build --sdist ou python -m build --sdist.
Posso personalizar o conteúdo do wheel?
Opções force-include, exclude e artifacts do hatchling.
Como construir em modo editável?
pip install -e . ou uv pip install -e . - não é um build de wheel.
O que é PEP 517?
Padrão para especificar backends de build em pyproject.toml.
Como adicionar uma dependência de build?
[build-system] requires = ["hatchling", "cython"].
Builds de Monorepo?
pyproject.toml separado por pacote ou workspace uv com builds por membro.
Como verificar o wheel?
tar -tzf dist/*.whl ou unzip -l dist/*.whl.
Migração do setuptools?
Mova os metadados para [project], configure [tool.setuptools.packages.find].
Relacionados
- Noções Básicas de Empacotamento - introdução ao build
- Extensões Nativas e Wheels - pacotes compilados
- Publicando no PyPI - fluxo de upload
- pyproject.toml Explicado
Versões de 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+.