Transformação de setup.py para pyproject.toml com automação prática

Ao gerenciar múltiplos projetos em Python, uma das tarefas que frequentemente aparecem é a migração de arquivos de configuração tradicionais, como setup.py, para o formato mais moderno e padronizado de pyproject.toml. Essa mudança não é apenas uma questão de atualização de padrão, mas também uma estratégia para melhorar a manutenção, facilitar integrações e acelerar o feedback durante o desenvolvimento.

Diagnóstico do problema

O desafio central na conversão de setup.py para pyproject.toml está na complexidade de automatizar o processo, dado que setup.py pode incluir lógica customizada, scripts de instalação, comandos específicos e variáveis dinâmicas. Essa flexibilidade, embora útil, torna difícil uma conversão direta e confiável, especialmente sem intervenção manual. Além disso, muitas equipes ainda possuem projetos com configurações dispersas que dificultam um script único e universal para a migração.

Abordagem de solução

Para contornar esses obstáculos, é possível combinar ferramentas que convertem configurações INI/CFG em toml, com scripts que transformam a configuração de setup.py em setup.cfg, um formato intermediário mais estruturado e compatível com o padrão PEP 621.

Primeiro, utiliza-se um projeto que converte arquivos INI/CFG para toml, facilitando a preparação de um pyproject.toml compatível. Depois, emprega-se uma ferramenta que converte setup.py em setup.cfg, permitindo uma transição gradual e controlada. Essas etapas podem ser automatizadas com scripts que encadeiam os comandos, gerando um arquivo de configuração atualizado e compatível.

Exemplo técnico de automação

pip install 'ini2toml[full]' setuptools-py2cfg

# Converte setup.py para setup.cfg
setuptools-py2cfg setup.py -o setup.cfg

# Converte setup.cfg para pyproject.toml
cat setup.cfg | ini2toml - > pyproject.toml

Esse fluxo simplificado permite que, com poucos comandos, equipes possam transformar o seu projeto antigo em uma configuração moderna, com menos risco de erros humanos e maior controle sobre o processo. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Limites e cuidados

Apesar da praticidade, é importante validar o resultado gerado. A lógica customizada no setup.py, por exemplo, pode não ser totalmente capturada pela conversão automática, exigindo ajustes manuais posteriores. Além disso, a compatibilidade entre as ferramentas ainda está em estágio experimental, então testes aprofundados em ambientes de CI/CD são recomendados. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Passos acionáveis

1. Avalie o conteúdo do seu setup.py e identifique lógicas complexas.
2. Execute as ferramentas de conversão em um projeto de teste.
3. Faça validações de instalação e build localmente.
4. Ajuste manualmente configurações específicas que não foram cobertas pelo script.
5. Atualize sua documentação de build e deployment.

Com essa abordagem, a transição fica mais segura e controlada, além de oferecer uma oportunidade de revisão geral das configurações do projeto, promovendo uma manutenção mais sustentável a longo prazo. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.