Melhores Práticas de Empacotamento
Regras para pacotes que instalam de forma limpa, versionam de forma previsível e publicam de forma segura.
Como Usar Esta Lista
- Aplique ao criar um novo pacote ou preparar um lançamento
- Bibliotecas seguem regras mais rigorosas do que aplicações internas
- Revise antes de cada publicação no PyPI
A - Estrutura do Projeto
- Layout src/. Testes importam o pacote instalado.
- Apenas pyproject.toml. Sem setup.py, setup.cfg ou requirements.txt como fonte da verdade.
- Backend de build hatchling. A menos que extensões exijam maturin/setuptools.
- README no PyPI.
readme = "README.md"em[project].
B - Metadados
- Nome e descrição claros. Pesquisáveis no PyPI.
- requires-python definido. Corresponde às versões suportadas reais.
- Licença declarada. Identificador SPDX em
[project]. - Classificadores precisos. Versão do Python, SO, tags de framework.
C - Versionamento e Lançamentos
- SemVer para bibliotecas. MAJOR para quebras, MINOR para recursos, PATCH para correções.
- CHANGELOG atualizado. Cada lançamento documentado.
- Tag Git corresponde à versão. Tag
v1.2.3para lançamento1.2.3. - TestPyPI primeiro. Verifique a instalação antes do PyPI de produção.
D - Build e Publicação
- Build em CI. Artefatos reproduzíveis de um ambiente limpo.
- Teste o wheel.
pip install dist/*.whlem um venv novo antes do upload. - Publicação confiável. Tokens OIDC, não senhas em CI.
- Ambos wheel e sdist. Publique ambos os formatos.
E - Segurança
- Sem segredos no pacote. Tokens, chaves e senhas nunca no código fonte ou metadados.
- Dependências mínimas. Menos dependências = menor superfície de ataque.
- Yank, não delete. Lançamentos ruins yanked (removidos temporariamente) no PyPI com explicação.
- 2FA na conta PyPI. Obrigatório para todos os publicadores.
FAQs
Empacotamento de biblioteca ou aplicação?
Bibliotecas: PyPI com semver. Aplicações: Docker ou pipx.
Devo publicar no PyPI?
Se outras equipes ou a comunidade o instalarem. Apenas interno: índice privado.
Como escolho um nome de pacote?
Verifique pypi.org para disponibilidade. Minúsculas, hífens, sem typosquatting.
Qual licença?
MIT ou Apache-2.0 para a maioria do código aberto. Revisão legal para proprietário.
Incluir testes no sdist?
Sim para sdist. Testes não são instalados com wheel (excluir via configuração).
Como faço para descontinuar um pacote?
Aviso no README, classificador PyPI Development Status :: 7 - Inactive, lançamento final.
Publicação em Monorepo?
Versões independentes por pacote. Projetos PyPI separados.
Assinando lançamentos?
PyPI suporta atestações assinadas por PGP. Publicação confiável é o padrão moderno.
Com que frequência lançar?
Quando mudanças significativas se acumulam. Lançamentos de patch para correções de segurança imediatamente.
E arquivos de dados?
Declare na configuração de build. Acesse via importlib.resources em tempo de execução.
Relacionados
- Noções Básicas de Empacotamento - para começar
- Publicando no PyPI - fluxo de upload
- Versionamento e Changelogs - notas de lançamento
- Melhores Práticas de Ambientes - gerenciamento de dependências
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+.