Estrutura e Código de Pacotes Python#
Esta seção cobre tudo o que você precisa para estruturar seu pacote Python, configurar metadados, escolher ferramentas de build e publicar seu pacote no PyPI e conda-forge.
Comece com nossos tutoriais passo a passo:
Acompanhe enquanto criamos um pacote do zero
Aprenda na prática com exemplos guiados
Ideal para o seu primeiro pacote
Começar a série de tutoriais
Acesse os guias de referência:
Aprenda sobre estrutura de pacote e metadados
Compare ferramentas de build e escolha a mais adequada para você
Entenda o processo de publicação
Comece pelos cards abaixo ↓
Como este conteúdo é desenvolvido
Todo o conteúdo deste guia foi revisado por membros da comunidade, incluindo mantenedores e desenvolvedores das principais ferramentas de packaging.
O que você vai aprender#
Nesta seção, você vai aprender como:
Estruturar seu pacote - Escolher entre layouts src e flat, organizar testes e documentação
Configurar metadados - Definir o
pyproject.tomlcom informações do projeto, dependências e versionamentoEscolher ferramentas de build - Comparar Hatch, PDM, Poetry e setuptools para encontrar a opção mais adequada
Gerar distribuições - Criar arquivos sdist e wheel prontos para publicação
Publicar seu pacote - Disponibilizar seu pacote no PyPI e, opcionalmente, no conda-forge
Manter a qualidade do código - Configurar linters e formatadores para manter seu código consistente
Nossas recomendações estão alinhadas com os padrões atuais de packaging Python e com as especificações da comunidade Scientific Python, priorizando ferramentas acessíveis para iniciantes e bem mantidas.
Configuração do pacote#
Aprenda a organizar os arquivos do seu pacote usando layouts src ou flat. Esta página ajuda você a decidir uma estrutura de pacote que segue as boas práticas modernas do Python, incluindo onde colocar testes e documentação.
Aprenda a adicionar metadados de projeto ao seu pacote Python para dar suporte tanto à filtragem no PyPI quanto aos metadados que um instalador de pacotes precisa para compilar e instalar seu pacote.
Aprenda a especificar dependências obrigatórias, dependências opcionais de funcionalidades e dependências de desenvolvimento no seu arquivo pyproject.toml.
Aprenda a gerenciar versões do pacote usando versionamento semântico (SemVer) ou versionamento por calendário (CalVer). Esta página ajuda você a escolher a estratégia de versionamento ideal e a configurar o gerenciamento automatizado de versões usando ferramentas como hatch_vcs ou setuptools-scm.
Boas práticas de desenvolvimento#
Aprenda a configurar formatadores de código e linters (Black, Ruff, flake8) para garantir que seu pacote siga os padrões PEP 8 e mantenha um estilo de código consistente em todo o projeto.
Build & publicação#
Aprenda a escolher a ferramenta de packaging ideal para o seu projeto. Compare Hatch, PDM, Poetry e setuptools para encontrar a melhor opção para o seu fluxo de trabalho. Veja o comparativo resumido para ajudar na decisão.
Aprenda a compilar seu pacote Python em arquivos de distribuição (sdist e wheel) que podem ser publicados no PyPI.
Aprenda a publicar seu pacote no PyPI e, opcionalmente, no conda-forge. Esta página cobre o processo completo para disponibilizar seu pacote aos usuários, incluindo o processo de envio ao conda-forge após a publicação no PyPI.
Escolhendo as ferramentas certas#
Não sabe qual ferramenta de build usar? Esta árvore de decisão pode ajudar você a escolher com base nas necessidades do seu pacote:
Use esta árvore de decisão para ajudar a selecionar uma ferramenta de packaging. Acesse a página de ferramentas de packaging para comparações detalhadas e recomendações.#
Nossas recomendações#
Sugerimos ferramentas e abordagens com base em três princípios:
Acessível para iniciantes - Ferramentas fáceis de aprender e usar para quem está começando com packaging
Bem mantidas - Ferramentas com desenvolvimento ativo e boa documentação
Alinhadas com os padrões - Ferramentas que seguem os padrões atuais de packaging Python e as especificações da comunidade Scientific Python
Python puro vs. builds complexos#
Pacotes Python puro podem usar qualquer ferramenta moderna (Hatch, PDM, Poetry, Flit) - escolha com base nas funcionalidades que você deseja
Pacotes com extensões C/C++ podem precisar de etapas de build adicionais. Consulte nossa página de builds complexos para orientações. Para informações completas sobre packaging de projetos compilados, acesse o Guia de Desenvolvimento Scientific Python sobre packaging compilado.
A maioria dos pacotes Python científicos começa de forma simples e pode evoluir para lidar com requisitos mais complexos conforme necessário.
Submetendo seu pacote para revisão por pares?#
Se você planeja submeter seu pacote ao pyOpenSci para revisão por pares, confira nossa lista de verificação do editor para os requisitos mínimos. Essas verificações são úteis para qualquer pessoa que esteja criando um pacote Python, não apenas para quem está submetendo para revisão.
Estas são recomendações, não requisitos
As sugestões neste guia foram elaboradas para ajudar você a criar um pacote bem-estruturado. Elas não são requisitos específicos para a revisão por pares do pyOpenSci.
Se você está submetendo ao pyOpenSci, consulte nosso escopo de pacotes e o guia do autor para os requisitos reais de revisão.