TECNOLANDIA TECH
Publicidade

Conecte-se com o Tecnolândia Tech

BLOG + INSTAGRAM + FACEBOOK

Tecnologia na prática, em todos os formatos.

Aqui no Tecnolândia Tech, você encontra artigos e guias completos. No Instagram @djwinformatica e no Facebook TecnoInfo, acompanhe vídeos, dicas e novidades de IA, automação e tecnologia. São nossos canais oficiais.

Como Publicar Seu Pacote no PyPI em 10 Minutos

Como Publicar Seu Pacote no PyPI em 10 Minutos

Imagem: Pexels

Publicar código no PyPI deixou de ser ritual obscuro: a partir do momento em que seu projeto tem um pyproject.toml válido, o caminho até um pip install seu-pacote tem quatro comandos. O que ainda derruba iniciante não é o upload — é nome já ocupado, versão duplicada e credencial errada. Este guia cobre o fluxo completo, com TestPyPI como campo de treino, na ordem que evita retrabalho.

1. Escolha o nome antes de escrever o código

Nome no PyPI é global e permanente. Procure no site pypi.org antes de se apegar a um nome: se já existir, você vai precisar de outro (nomes com prefixo do projeto, como meuapp-utils, resolvem a maioria dos conflitos). Regra de higiene: minúsculas, hífen como separador, sem data nem "2" no fim — versão é versão, não nome. Verifique também se o mesmo nome está livre no pip para evitar confusão de instalação.

2. pyproject.toml: o arquivo que o moderno exige

Setup.py é legado. O padrão atual é pyproject.toml com o build backend setuptools (ou hatchling, se preferir). Estrutura mínima que funciona:

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

[project]
name = "meu-utils"
version = "0.1.0"
description = "Funções utilitárias para o dia a dia"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "MIT"}

[project.urls]
Homepage = "https://github.com/seu-usuario/meu-utils"

O name aqui é o que o pip vai usar; o version é o que o PyPI valida como único — subir duas vezes a mesma versão gera erro e você é obrigado a incrementar. Coloque também um README.md decente: ele vira a página do pacote e é a primeira coisa que alguém lê antes de instalar.

3. Build: gerando os artefatos

Instale as ferramentas de publicação e gere a distribuição:

python -m pip install build twine
python -m build

O resultado é a pasta dist/ com um .tar.gz (sdist) e um .whl (wheel). Publique os dois — o wheel para instalação rápida, o sdist para quem precisa compilar. Antes do upload, valide os metadados:

python -m twine check dist/*

Erros de reStructuredText no readme aparecem aqui, não no PyPI. Corrija e rebuild antes de seguir.

4. Treino no TestPyPI, publicação de verdade no PyPI

TestPyPI é um servidor espelho para praticar sem sujar o registro oficial. Crie uma conta em test.pypi.org (separada da conta real), gere um API token no site apontando para o TestPyPI, e envie:

python -m twine upload --repository testpypi dist/*

Instale do TestPyPI para conferir que o pacote funciona de verdade:

pip install --index-url https://test.pypi.org/simple/ meu-utils

Passou? Repita com a conta e token do PyPI real, sem o --repository:

python -m twine upload dist/*

O token vai no formato __token__ como usuário e o valor do token como senha — ou no arquivo ~/.pypirc, se você publica com frequência. Nunca commite token no repositório; vale mais uma cópia manual do que um pacote comprometido.

5. Publicar de novo: bump de versão e CI

Cada alteração exige nova versão. Adote SemVer de verdade: 0.1.1 para correção, 0.2.0 para funcionalidade nova compatível, 1.0.0 quando a API estiver estável. Fluxo manual: editou o código, subiu o número no pyproject.toml, apagou dist/, rebuild, upload. Em projeto ativo, automatize: GitHub Actions com Trusted Publishing (PyPI confia no repositório via OIDC, sem token guardado) dispara em cada tag v0.2.0 e publica sozinho.

6. Erros clássicos do primeiro dia

  • 400 ou "file already exists": versão repetida — incremente o version e rebuild.
  • Nome rejeitado: conflito ou violação de regras de nome do PyPI.
  • 403 de permissão: token errado, token de teste apontando para o PyPI real, ou conta sem 2FA quando o PyPI exige.
  • Instala mas não importa: falta de [tool.setuptools] com pacotes corretos no pyproject — confira se o import bate com a estrutura de pastas.

Feito o primeiro upload, trate o pacote como produto: changelog, tags no Git e CI publicando por versão. E se o pacote for para uso interno da empresa sem necessidade de exposição, lembre que existe o pip install de um wheel direto do repositório — PyPI é para código que outras pessoas fora do seu time vão instalar.

Publicidade