Ferramentas de packaging Python

Ferramentas para construir o seu pacote

Existem várias ferramentas de build diferentes que você pode usar para criar as distribuições sdist e wheel do seu pacote Python. Abaixo, discutimos os recursos, benefícios e limitações das ferramentas de packaging Python mais comumente usadas. Neste guia, focamos em pacotes Python puros. No entanto, também destacamos ferramentas que atualmente dão suporte a pacotes com extensões em C/C++ e em outras linguagens.

Diagrama mostrando as diferentes ferramentas de build de front-end disponíveis para uso no ecossistema de pacotes Python que você pode escolher. Selecionamos as ferramentas para incluir neste diagrama com base na pesquisa do PyPI, que nos ajudou a entender as ferramentas mais populares do ecossistema. Cada ferramenta tem recursos diferentes, conforme destacado abaixo.

Se você quer saber mais sobre pacotes Python que têm extensões escritas em outras linguagens, confira a página sobre builds de pacotes complexos.

Ferramentas que analisamos aqui

Nesta seção, selecionamos ferramentas que apareceram como as ferramentas de packaging mais populares na pesquisa da PyPA. Você aprenderá mais sobre as seguintes ferramentas nesta página:

• Twine, Build + setuptools

• Flit

• Hatch

• PDM

• Poetry

Resumo das ferramentas Hatch vs. PDM vs. Poetry (e setuptools)

Se você está procurando um resumo rápido, leia abaixo.

• Em geral, qualquer ferramenta moderna que você selecionar desta página será ótima para construir o seu pacote. A escolha de uma ferramenta se resume aos recursos que você está procurando no seu fluxo de trabalho.

• Sugerimos que os iniciantes comecem com uma ferramenta de fluxo de trabalho moderna como o PDM, em vez de lidar com as complexidades do setuptools.

• Se você vai usar o Poetry (é a ferramenta mais popular e tem a melhor documentação), tome cuidado com as adições de dependências com limite superior e considere sobrescrever as dependências ao adicioná-las. Se você fizer isso, o Poetry funcionará bem para builds de Python puro! O Poetry também tem um discord ativo onde você pode tirar dúvidas.

Abaixo estão alguns recursos que o Hatch e o PDM oferecem e o Poetry não.

PDM:

• Dá suporte a outros back-ends, tornando-o ideal para builds que não são de Python puro. Isso significa que o PDM é uma ótima opção tanto para builds de Python puro quanto para builds Python mais complexas, pois dá suporte ao meson-python e a outros backends de build.

• Oferece flexibilidade no gerenciamento de dependências, o que apreciamos

• Oferece arquivos de lock (bloqueio) caso você precise deles

Hatch:

• Oferece gerenciamento de ambientes em matriz que permite executar testes em diferentes versões do Python. Se esse recurso é importante para você, então o Hatch é o vencedor claro.

• Oferece uma ferramenta semelhante ao Nox / Makefile para otimizar o seu fluxo de trabalho de build. Se você está buscando reduzir o número de ferramentas no seu fluxo de trabalho, o Hatch pode ser para você.

Ferramentas de front-end de build vs. back-end de build

Para entender melhor as suas opções quando se trata de construir um pacote Python, é importante primeiro entender a diferença entre uma ferramenta de front-end de build e uma de back-end de build.

Back-ends de build

A maioria das ferramentas de packaging tem uma ferramenta de build de back-end que constrói o seu pacote e cria os arquivos de distribuição (sdist e wheel) associados. Algumas ferramentas, como o Flit, dão suporte apenas a builds de pacotes de Python puro. Uma build de Python puro refere-se a uma build de pacote que não tem extensões escritas em outra linguagem de programação (como C ou C++).

Outros pacotes que têm extensões em C e C++ (ou que encapsulam outras linguagens como fortran) requerem etapas adicionais de compilação de código ao serem construídos. Back-ends como setuptools.build, meson.build e scikit-build dão suporte a builds complexas com etapas personalizadas. Se a sua build for particularmente complexa (ou seja, você tem mais do que algumas poucas extensões C/C++), então sugerimos que você use o meson.build ou o scikit-build.

Front-ends de build de pacotes Python

Uma ferramenta de front-end de packaging refere-se a uma ferramenta que facilita a execução de tarefas comuns de packaging usando comandos semelhantes. Essas tarefas incluem:

• Construir os seus pacotes (criar as distribuições sdist e wheel)

• Instalar o seu pacote em modo de desenvolvimento (para que ele seja atualizado quando você atualizar o seu código)

• Publicar no PyPI

• Executar testes

• Construir documentação

• Gerenciar um ambiente ou múltiplos ambientes nos quais você precisa executar testes e desenvolver o seu pacote

Existem várias ferramentas de packaging Python que você pode usar para builds de Python puro. Cada ferramenta de front-end discutida abaixo dá suporte a um conjunto ligeiramente diferente de tarefas de packaging Python.

Por exemplo, você pode usar as ferramentas de packaging Flit, Hatch ou PDM tanto para construir quanto para publicar o seu pacote no PyPI. No entanto, embora o Hatch e o PDM deem suporte a versionamento e gerenciamento de ambientes, o Flit não dá. Se você quer uma ferramenta que dê suporte ao bloqueio de dependências, você pode usar o PDM ou o Poetry, mas não o Hatch. Se você só precisa construir os arquivos de distribuição sdist e wheel do seu pacote, então você pode ficar com o Build da PyPA. Aí você usaria o Twine para publicar no PyPI.

Nota

Se você está usando o Setuptools, não há um front-end de build padrão e amigável que execute múltiplas tarefas. Você precisará usar o build para construir o seu pacote e o twine para publicar no PyPI.

Exemplo de etapas de build que podem ser simplificadas usando uma ferramenta de front-end

Abaixo, você pode ver como uma ferramenta de build otimiza a sua experiência de packaging. Exemplo para construir o seu pacote com o Hatch:

# Build your sDist and .whl files
hatch build

# Example to publish to PyPI:
hatch publish --repo test

Exemplo de etapas de build usando o back-end setuptools e o build:

# Build the package
python3 -m build

# Publish to test PyPI using twine
twine upload -r testpypi dist/*

Escolhendo um back-end de build

A maioria das ferramentas de packaging de front-end tem a sua própria ferramenta de build de back-end. A ferramenta de build cria os arquivos de distribuição (sdist e wheel) do seu pacote. Para pacotes de Python puro, a principal diferença entre os diferentes back-ends de build discutidos abaixo é:

• O quão configuráveis eles são - por exemplo, eles permitem que você adicione etapas de build que dão suporte a extensões não Python?

• O quanto você precisa configurá-los para garantir que os arquivos corretos sejam incluídos nas suas distribuições sdist e wheel.

Suporte de back-end de build para pacotes que não são de Python puro

É importante observar que alguns back-ends de build, como o Flit-core, dão suporte apenas a builds de Python puro. Outros back-ends dão suporte a extensões em C e C++ da seguinte forma:

• o setuptools dá suporte a builds usando extensões em C / C++

• O Hatchling (o back-end do hatch) dá suporte a extensões em C / C++ por meio de plugins que o desenvolvedor cria para personalizar uma build

• O back-end do PDM dá suporte a extensões em C / C++ usando o setuptools

• O back-end do Poetry dá suporte a extensões em C/C++, no entanto essa funcionalidade atualmente não é documentada. Por isso, não recomendamos usar o Poetry para builds complexas ou que não sejam de Python puro até que ela seja documentada.

Embora não discutamos builds mais complexas abaixo, identificaremos quais ferramentas têm suporte documentado para extensões em C / C++.

Um ecossistema de ferramentas de build Python

Abaixo, apresentamos várias das ferramentas de front-end de build de packaging Python mais comumente usadas. Destacamos os recursos que cada ferramenta oferece como uma forma de ajudar você a decidir qual ferramenta pode ser a melhor para o seu fluxo de trabalho.

Não sugerimos usar o setuptools

Sugerimos que você escolha uma das ferramentas modernas listadas acima em vez do setuptools, porque o setuptools exigirá algum conhecimento adicional para ser configurado corretamente.

Analisamos o setuptools como um back-end porque ele ainda é popular. No entanto, não é a opção mais amigável.

As ferramentas mais comumente usadas no ecossistema são o back-end setuptools (com o build) e o Poetry (uma ferramenta de front-end com diversos recursos e excelente documentação).

Os resultados da pesquisa com desenvolvedores Python (n=>8.000 usuários do PyPI) mostram o setuptools e o poetry como as ferramentas de packaging Python mais comumente usadas. As principais ferramentas que vimos sendo usadas na comunidade científica estão incluídas aqui. Você pode ver os resultados completos da pesquisa clicando aqui. NOTA: estes dados representam mantenedores de diversos domínios e provavelmente são fortemente representados por pessoas do desenvolvimento web. Portanto, isto representa um panorama de todo o ecossistema Python.

Escolha uma ferramenta de fluxo de trabalho de build

As ferramentas que analisamos abaixo incluem:

• Twine, Build + setuptools

• Flit

• Hatch

• PDM

• Poetry

Ao selecionar uma ferramenta, você pode considerar este fluxo geral de perguntas:

1. O seu pacote é Python puro? Sim? Você pode usar qualquer ferramenta que quiser! Escolha a ferramenta que tem os recursos que você quer usar no seu fluxo de trabalho de build. Sugerimos:

• Flit, Hatch, PDM ou Poetry (leia abaixo para saber mais)

1. O seu pacote tem algumas extensões em C ou C++? Ótimo, sugerimos usar o PDM por enquanto. É a única ferramenta da lista abaixo que tem tanto um fluxo de trabalho documentado para dar suporte a essas extensões quanto suporte a outros back-ends caso os build hooks não sejam suficientes para o seu fluxo de trabalho. O PDM dá suporte a outros back-ends como o scikit-build e o meson-python, que permitirão que você personalize totalmente a build do seu pacote.

NOTA: Você também pode usar o Hatch para builds que não sejam de Python puro. O Hatch, assim como o PDM, permite que você escreva os seus próprios build hooks ou plugins para dar suporte a etapas de build personalizadas. Mas, atualmente, o hatch não dá suporte a outros back-ends de build. Muitos dos principais pacotes científicos estão migrando para o meson-python para construir seus pacotes. Por isso, valorizamos o fato de o PDM poder trabalhar especificamente com o meson-python.

Resumo das ferramentas de packaging Python

Abaixo, resumimos os recursos oferecidos pelas ferramentas de front-end de build mais populares. É importante ter em mente que essas ferramentas de front-end eliminam a necessidade de usar outras ferramentas principais no seu fluxo de trabalho. Por exemplo, se você usar o setuptools, também precisará usar o Build e o Twine para construir o seu pacote e publicar no PyPI. Mas se você usar o Poetry, o Hatch ou o PDM, você pode fazer todas essas coisas usando a mesma ferramenta (por exemplo, hatch build, hatch publish ou pdm build, pdm publish).

Observe que, como o setuptools não oferece uma interface de front-end, ele não está incluído na tabela.

Tabela de recursos das ferramentas de pacote

Recurso	Flit	Hatch	PDM	Poetry
Back-end de Build Padrão	Flit-core	hatchling	PDM	Poetry-core
Usar Outros Back-ends de Build	x	✅	✅	x
Gerenciamento de dependências	x	x	✅	✅
Publicar no PyPI	✅	✅	✅	✅
Versionamento baseado em controle de versão (usando git tags)	x	✅	✅	✅
Incremento de versão	x	✅	✅	✅
Gerenciamento de Ambientes	x	✅	✅	✅
Mais de um mantenedor? (fator ônibus)	x	x	x	✅

Notas:

• O Hatch planeja dar suporte ao gerenciamento de dependências no futuro

• O Poetry dá suporte ao versionamento semântico. Assim, ele dará suporte ao incremento de versão seguindo as mensagens de commit se você usar uma ferramenta como o Python Semantic Release

PDM

O PDM é uma ferramenta de packaging e gerenciamento de dependências Python. O PDM dá suporte a builds para projetos Python puros. Ele também fornece várias camadas de suporte para projetos que têm extensões em C e C++.

Suporte do PDM para extensões em C e C++

O PDM dá suporte ao uso do back-end do PDM e do setuptools ao mesmo tempo. Isso significa que você pode executar o setuptools para compilar e construir extensões em C. O back-end de build do PDM recebe os arquivos de extensão compilados (.so, .pyd) e os empacota junto com os arquivos Python puros.

Recursos do PDM

Recurso	PDM	Notas
Usar Outros Back-ends de Build	✅	Quando você configura o PDM, ele permite que você selecione um de vários back-ends de build, incluindo: PDM-core, flit-core e hatchling. O PDM também pode trabalhar com o Meson-Python, que dá suporte a builds Python mais complexas.
Especificações de dependências	✅	O PDM tem suporte flexível para gerenciar dependências. O PDM usa por padrão uma abordagem de limite aberto (por exemplo, requests >=1.2) para as dependências. No entanto, você pode personalizar como deseja adicionar dependências caso prefira outra abordagem, como a do Poetry, que usa um limite superior.**
Arquivos de lock de ambiente	✅	O PDM e o Poetry são atualmente as únicas ferramentas que criam arquivos de lock de ambiente. Os arquivos de lock costumam ser mais úteis para desenvolvedores que criam aplicações web, onde bloquear o ambiente é essencial para uma experiência de usuário consistente. Para pacotes usados pela comunidade, é provável que você nunca queira usar um arquivo de lock.
Gerenciamento de ambientes	✅	O PDM fornece suporte ao gerenciamento de ambientes. Ele dá suporte a ambientes virtuais Python, conda e a um ambiente local __pypackages__, que é uma opção mais recente no ecossistema Python. Nenhuma extensão é necessária para esse suporte.
Selecione o tipo de ambiente na instalação	✅	Quando você executa PDM init, o PDM descobrirá os ambientes que já estão no seu sistema e permitirá que você selecione um para usar no seu projeto.
Publicar no PyPI	✅	O PDM dá suporte à publicação tanto no test PyPI quanto no PyPI
Versionamento baseado em controle de versão	✅	O PDM tem uma ferramenta semelhante ao setuptools_scm embutida nele, que permite usar versionamento dinâmico baseado em tags do git.
Incremento de versão	✅	O PDM dá suporte ao incremento da versão do seu pacote usando os termos padrão de versionamento semântico patch; minor; major
Segue os padrões atuais de packaging	✅	O PDM dá suporte aos padrões atuais de packaging para adicionar metadados ao arquivo pyproject.toml.
Instale o seu pacote em modo editável	✅	O PDM dá suporte à instalação do seu pacote em modo editável.
Construa as suas distribuições sdist e wheel	✅	Assim como todas as outras ferramentas, o PDM constrói os arquivos sdist e wheel do seu pacote para você.

PDM vs. Poetry

A funcionalidade do PDM é semelhante à do Poetry. No entanto, o PDM também oferece suporte adicional e documentado para extensões em C e versionamento baseado em controle de versão. Por isso, o PDM é preferível para quem trabalha com pacotes que não são de Python puro.

Se você está decidindo entre o Poetry e o PDM, uma diferença menor é a forma padrão como as dependências são adicionadas ao seu arquivo pyproject.toml.

• O Poetry, por padrão, segue o versionamento semântico estrito, adicionando dependências ao seu arquivo pyproject.toml usando uma restrição de limite superior (^). O bloqueio de limite superior significa que o Poetry nunca vai incrementar uma dependência para a próxima versão major (ou seja, de 1.2 para 2.0). No entanto, você pode dizer ao Poetry para usar uma abordagem de limite aberto adicionando o pacote explicitamente assim: poetry add requests >= 1.2 em vez de apenas usar poetry add requests, o que resultará em um limite superior bloqueado (ou seja, o bloqueio de limite superior significa que requests 2.0 nunca poderia ser instalado, mesmo que fosse lançado e o seu pacote pudesse se beneficiar dele).

• O PDM usa por padrão adições de dependências com limites abertos (>=), que é a abordagem preferida no ecossistema científico do python. No entanto, o PDM também permite que você especifique a forma como as dependências são adicionadas por padrão. Assim, você também pode especificar limites superiores (^) usando o PDM caso precise dessa abordagem.

Por fim, há algumas diferenças sutis na forma como ambas as ferramentas criam arquivos de lock, sobre as quais não entraremos em detalhes aqui.

Desafios com o PDM

O PDM é uma ferramenta de packaging completa. No entanto, ela não está isenta de desafios:

• Sua documentação pode ser confusa, especialmente se você é novo no packaging. Por exemplo, o PDM não fornece um fluxo de trabalho inicial de ponta a ponta na sua documentação.

• O PDM também tem apenas um mantenedor atualmente. Consideramos as equipes com um único mantenedor como um risco potencial. Se o mantenedor perceber que não tem mais tempo para trabalhar no projeto, isso deixa os usuários com uma lacuna no suporte. O Hatch e o Flit também têm equipes com um único mantenedor.

Você pode ver um exemplo de um pacote que usa o PDM aqui. O arquivo README disso fornece diretamente uma visão geral de como é a interface de linha de comando do PDM quando você a usa.

Flit

O Flit é uma ferramenta de packaging simples e enxuta que dá suporte aos padrões modernos de packaging Python. O Flit é uma ótima escolha se você está construindo um pacote básico para usar em um fluxo de trabalho local que não requer nenhum recurso avançado. E se a estrutura do seu pacote já estiver criada. Mais sobre isso abaixo.

Recursos do Flit

Recurso	Flit	Notas
Publicar no PyPI e no test PyPI	✅	O Flit dá suporte à publicação tanto no test PyPI quanto no PyPI
Ajuda você a adicionar metadados ao seu arquivo pyproject.toml	✅	O Flit dá suporte à adição de metadados ao seu arquivo pyproject.toml seguindo os padrões modernos de packaging.
Segue os padrões atuais de packaging	✅	O Flit dá suporte aos padrões atuais de packaging para adicionar metadados ao arquivo pyproject.toml.
Instale o seu pacote em modo editável	✅	O Flit dá suporte à instalação do seu pacote em modo editável.**
Construa as suas distribuições sdist e wheel	✅	O Flit pode ser usado para construir as distribuições sdist e wheel do seu pacote.

NOTA: Se você está usando a versão mais atual do pip, ele dá suporte tanto à abordagem de symlink flit install -s quanto a python -m pip install -e .

Saiba mais sobre o flit

• Por que usar o flit?

Por que você pode não querer usar o Flit

Como o Flit é simples e sem complicações, ele é melhor para builds básicas e rápidas. Se você é iniciante, talvez prefira escolher o Hatch ou o PDM, que lhe oferecerão mais suporte em operações comuns.

Você pode NÃO querer usar o flit se:

• Você quer configurar um rastreamento e gerenciamento de versões mais avançado (usando controle de versão para o incremento de versão)

• Você quer uma ferramenta que lide com versões de dependências (use o PDM ou o Poetry no lugar)

• Você tem um projeto que não é de Python puro (Use Hatch, PDM ou setuptools)

• Você quer gerenciamento de ambientes (use PDM, Hatch ou Poetry)

Hatch

O Hatch, assim como o Poetry e o PDM, fornece uma interface de linha de comando unificada. Para diferenciar o Hatch do Poetry e do PDM, ele também fornece um gerenciador de ambientes para testes que facilitará a execução de testes localmente em diferentes versões do Python. Ele também oferece um recurso semelhante ao nox / makefile que permite criar fluxos de trabalho de build personalizados, como construir a sua documentação localmente. Isso significa que você poderia, potencialmente, eliminar uma ferramenta como o Make ou o Nox do seu fluxo de trabalho e usar o Hatch no lugar.

Recursos do Hatch

Recurso	Hatch	Notas
Usar Outros Back-ends de Build	✅	O Hatch é usado com o backend Hatchling por padrão, mas permite que você use outro backend trocando a declaração no pyproject.toml.
Gerenciamento de dependências	x	Atualmente, você precisa adicionar as dependências manualmente com o Hatch. No entanto, um recurso para dar suporte ao gerenciamento de dependências pode ser adicionado em uma versão futura.
Gerenciamento de Ambientes	✅	O Hatch dá suporte a ambientes virtuais Python. Se você quiser usar outros tipos de ambientes, como o Conda, será necessário instalar um plugin como o hatch-conda para suporte ao conda.
Publicar no PyPI e no test PyPI	✅	O Hatch dá suporte à publicação tanto no test PyPI quanto no PyPI
Versionamento baseado em controle de versão	✅	O Hatch oferece o hatch_vcs, que é um plugin que usa o setuptools_scm para dar suporte ao versionamento usando tags do git. O fluxo de trabalho com o hatch_vcs é o mesmo do setuptools_scm.
Incremento de versão	✅	O Hatch dá suporte ao incremento da versão do seu pacote usando os termos padrão de versionamento semântico patch; minor; major
Segue os padrões atuais de packaging	✅	O Hatch dá suporte aos padrões atuais de packaging para adicionar metadados ao arquivo pyproject.toml.
Instale o seu pacote em modo editável	✅	Por padrão, o Hatch instalará o seu pacote em qualquer um dos seus ambientes em modo editável. Você pode instalar o seu pacote em modo editável manualmente usando python -m pip install -e . O Hatch menciona instalações editáveis, mas faz referência ao pip na sua documentação.
Construa as suas distribuições sdist e wheel	✅	O Hatch construirá as distribuições sdist e wheel
✨Criação de ambientes em matriz para dar suporte a testes em diferentes versões do Python✨	✅	A criação de ambientes em matriz é um recurso exclusivo do Hatch no ecossistema de packaging. Esse recurso é útil se você quiser testar o seu pacote localmente em diferentes versões do Python (em vez de usar uma ferramenta como o tox).
✨Funcionalidade semelhante ao Nox / MAKEFILE✨	✅	Esse recurso também é exclusivo do Hatch. Essa funcionalidade permite que você crie fluxos de trabalho na configuração do pyproject.toml para fazer coisas como servir a documentação localmente e limpar o diretório de build do seu pacote. Isso significa que você pode ter uma ferramenta a menos no seu fluxo de trabalho de build.
✨Um backend de build flexível: hatchling✨	✅	**O backend de build hatchling, oferecido pelo mantenedor do Hatch, permite que os desenvolvedores criem plugins com facilidade para dar suporte a etapas de build personalizadas durante o packaging.

Há alguma controvérsia sobre essa abordagem impor aos mantenedores o ônus de criar um sistema de build personalizado. Mas outros apreciam a flexibilidade. A abordagem de build hook do Hatch também é comparável aos recursos oferecidos pelo PDM.

Por que você pode não querer usar o Hatch

Há alguns recursos que faltam no hatch e que podem ser importantes para alguns. Eles incluem:

• O Hatch não dá suporte à adição de dependências. Você terá que adicioná-las manualmente.

• Por padrão, o Hatch não reconhecerá ambientes Conda sem um plugin.

• Assim como o PDM, a documentação do Hatch pode ser difícil de acompanhar, especialmente se você está apenas começando a criar um pacote.

• Hatch, assim como o PDM e o Flit, atualmente tem apenas um mantenedor.

Poetry

O Poetry é uma ferramenta de build completa. Ele também é a segunda ferramenta de packaging de front-end mais popular (com base na pesquisa da PyPA). O Poetry é amigável e tem uma documentação limpa e fácil de ler.

Nota

Embora alguns tenham usado o Poetry para builds Python com extensões em C/C++, esse suporte atualmente não é documentado. Por isso, não recomendamos usar o Poetry para builds mais complexas.

Recursos do Poetry

Recurso	Poetry	Notas
Adicione dependências ao seu arquivo pyproject.toml	✅	O Poetry ajuda você a adicionar dependências aos metadados do seu pyproject.toml.
Especificação de dependências	✅	O Poetry permite que você seja específico quanto à versão das dependências que você adiciona ao arquivo pyproject.toml do seu pacote. No entanto, sua abordagem padrão de limite superior pode ser problemática para alguns pacotes (sugerimos que você sobrescreva a configuração padrão ao adicionar dependências). Leia abaixo para saber mais.
Gerenciamento de ambientes	✅	O Poetry permite que você use o seu ambiente embutido ou selecione o tipo de ambiente que deseja usar para gerenciar o seu pacote. Leia mais sobre as suas opções de gerenciamento de ambientes embutidas.
Arquivos de lock	✅	O Poetry cria um arquivo poetry.lock que você pode usar caso precise de um arquivo de lock para a sua build.
Publicar no PyPI e no test PyPI	✅	O Poetry dá suporte à publicação tanto no test PyPI quanto no PyPI
Versionamento baseado em controle de versão	✅	O plugin Poetry dynamic versioning dá suporte ao versionamento usando tags do git com o Poetry.
Incremento de versão	✅	O Poetry dá suporte ao incremento da versão do seu pacote usando os termos padrão de versionamento semântico patch; minor; major
Segue os padrões atuais de packaging	✅	Desde a versão 2.0, o Poetry dá suporte à maioria dos padrões atuais de metadados de projeto. No entanto, nem todos os padrões são suportados, e ele também dá suporte ao formato legado do Poetry. Leia abaixo para saber mais.
Instale o seu pacote em modo editável	✅	O Poetry dá suporte à instalação do seu pacote em modo editável.
Construa as suas distribuições sdist e wheel	✅	O Poetry construirá as suas distribuições sdist e wheel usando poetry build

Desafios com o Poetry

Alguns desafios do Poetry incluem:

• O Poetry tem o seu próprio conceito de dependências agrupadas (poetry add --group=GROUP_NAME DEPENDENCY). As dependências adicionadas como dependências agrupadas não são opcionais e não há um padrão Python para esse tipo de dependência. Isso não deve ser confundido com as dependências «opcionais» (poetry add --optional=GROUP_NAME DEPENDENCY), que são padronizadas e permitem que você agrupe as suas dependências em vários grupos opcionais.

• Embora o Poetry dê suporte a dependências de «desenvolvimento» (ou seja, dependências que você usa para o desenvolvimento, mas não para executar o código, como o pytest), o Poetry ainda não segue o formato padronizado para especificar tais dependências.

• O Poetry, por padrão, fixa as dependências usando um limite «superior» (que é especificado com o símbolo ^ no formato legado). No entanto, esse comportamento pode ser sobrescrito especificando a dependência quando você usa poetry add da seguinte forma: poetry add "requests>=2.1" Veja o destaque abaixo para mais discussões sobre as questões em torno da fixação com limites superiores.

O Poetry é uma ferramenta de packaging popular e introduziu muitos recursos bastante úteis. No entanto, se você decidir usá-lo, tenha cuidado ao adicionar dependências, pois a abordagem de fixação do Poetry pode ser problemática para muitas builds. Se você usar o Poetry, sugerimos fortemente que você sobrescreva a opção padrão de dependências com limite superior.

Desafios com a fixação de dependências do Poetry

Por padrão, o Poetry fixa as dependências usando ^. Esse símbolo ^ significa que há um «limite superior» para a dependência. Assim, o poetry não incrementará a versão de uma dependência para uma nova versão major. Portanto, se o seu pacote usa uma dependência que está na versão 1.2.3, o Poetry nunca incrementará a dependência para 2.0, mesmo que haja uma nova versão major do pacote. Em vez disso, o Poetry incrementará até 1.9.x.

O Poetry faz isso porque adere ao versionamento semântico estrito, que afirma que um incremento de versão major (de 1.0 para 2.0, por exemplo) significa que há mudanças que quebram a compatibilidade na ferramenta. No entanto, nem todas as ferramentas seguem o versionamento semântico estrito. Essa abordagem foi considerada problemática por muitos dos nossos principais pacotes científicos.

Essa abordagem também não dará suporte a outras formas de versionar ferramentas; por exemplo, algumas ferramentas usam o calver, que cria novas versões com base na data.

Usando o back-end Setuptools para packaging Python com o front-end Build

O Setuptools é a ferramenta de build de packaging Python mais madura, com desenvolvimento que remonta a 2009 e antes. O Setuptools também tem o maior número de usuários na comunidade (de acordo com a pesquisa da PyPA). O Setuptools não oferece um front-end de usuário como o Flit, o Poetry e o Hatch oferecem. Por isso, você precisará usar outras ferramentas, como o build para criar as distribuições do seu pacote e o twine para publicar no PyPI.

Embora o setuptools seja a ferramenta mais comumente usada, incentivamos os mantenedores de pacotes a considerarem usar uma ferramenta mais moderna para packaging, como o Poetry, o Hatch ou o PDM.

Discutimos o setuptools aqui porque ele é comumente encontrado no ecossistema e os contribuidores podem se beneficiar de entendê-lo.

Recursos do Setuptools

Alguns dos recursos do setuptools incluem:

• Fluxo de trabalho de build totalmente personalizável

• Muitos pacotes científicos em Python o utilizam.

• Ele oferece versionamento de pacotes baseado em controle de versão usando o setuptools_scm

• Ele dá suporte ao packaging moderno usando o pyproject.toml para metadados

• Dá suporte à compatibilidade retroativa com abordagens de packaging mais antigas.

Desafios ao usar o setuptools

O Setuptools tem alguns desafios:

• Por padrão, o Setuptools não dá suporte a recursos interativos como auto / tab completion se você estiver trabalhando em uma IDE como o VSCODE e usando uma instalação editável para desenvolvimento. Veja as notas aqui sobre o suporte do pylance. Em comparação, ferramentas como flit, hatch e PDM dão suporte a recursos interativos como tab / auto completion ao usar uma IDE como o VSCODE ou o pycharm (desde que a sua versão do pip seja atual!).

• Como o setuptools precisa manter a compatibilidade retroativa com uma variedade de pacotes, ele não é tão flexível na adoção dos padrões modernos de packaging Python.

• A compatibilidade retroativa mencionada acima resulta em uma base de código mais complexa.

• A sua experiência como usuário será menos enxuta e simples usando o setuptools em comparação com as outras ferramentas discutidas nesta página.

Há também algumas configurações padrão problemáticas que os usuários devem conhecer ao usar o setuptools. Por exemplo:

• o setuptools construirá um projeto sem nome ou versão se você não estiver usando um arquivo pyproject.toml para armazenar os metadados.

• o setuptools também incluirá todos os arquivos do repositório do seu pacote se você não disser explicitamente para excluir arquivos usando um arquivo MANIFEST.in