Python Academy · Aula

Estrutura do projeto e pyproject.toml

Q: A aula “Estrutura do projeto e pyproject.toml” é grátis?

Sim — o texto completo de “Estrutura do projeto e pyproject.toml” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Python Academy, atualize para CoddyKit PRO. O curso de Python Academy inclui 4 aulas no total.

Q: O que vou aprender em “Estrutura do projeto e pyproject.toml”?

Organize um pacote Você pratica Python Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Q: Preciso ter experiência prévia para começar Python Academy?

Nenhuma experiência prévia é necessária. Python Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Q: Quanto tempo leva a aula “Estrutura do projeto e pyproject.toml”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Q: Posso escrever e executar código nesta aula de Python Academy?

Sim. Cada aula de Python Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Organize um pacote

Estrutura do projeto e pyproject.toml é uma aula grátis de Python Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Python Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Python Academy inclui 4 aulas no total.

Por que empacotar seu código

Um script fica na sua máquina; um pacote pode ser instalado por qualquer pessoa com pip install. O empacotamento transforma uma pasta de código em uma unidade distribuível, versionada e reutilizável.

O primeiro passo é ter uma estrutura de projeto organizada e um arquivo de configuração.

A estrutura src

A estrutura recomendada coloca o código que pode ser importado dentro de um diretório src/:

src/mypackage/__init__.py
src/mypackage/core.py
pyproject.toml
README.md e tests/

A estrutura src impede que você importe acidentalmente o código a partir da raiz do projeto, em vez de usar a cópia instalada.

O arquivo init.py

__init__.py identifica um diretório como um pacote que pode ser importado e é executado quando o pacote é importado pela primeira vez. Ele também é o local onde você expõe a API pública, importando os nomes principais.

Até mesmo um __init__.py vazio é suficiente para criar um pacote.

package_dir = 'src/mypackage'
files = ['__init__.py', 'core.py', 'utils.py']
for f in files:
    print(package_dir + '/' + f)
print('Importable as:', 'mypackage')

O que é pyproject.toml

pyproject.toml é o único arquivo de configuração padronizado (PEP 518/621) para o empacotamento moderno em Python. Ele substitui o antigo setup.py na maioria dos projetos e é lido pelas ferramentas de compilação.

Ele usa o formato TOML: seções entre colchetes e linhas no formato chave = valor.

A tabela build-system

A tabela [build-system] informa às ferramentas como compilar seu pacote. Uma escolha comum é:

requires = ['setuptools', 'wheel']
build-backend = 'setuptools.build_meta'

Outros sistemas de compilação incluem Hatchling e Flit; a ideia é a mesma.

A tabela project

A tabela [project] contém metadados: name, version, description, authors, readme, requires-python e dependencies. É isso que os usuários veem no PyPI.

Pense nela como a carteira de identidade do seu pacote.

project = {
    'name': 'mytool',
    'version': '0.1.0',
    'requires-python': '>=3.9',
    'dependencies': ['requests>=2.0'],
}
for k, v in project.items():
    print(k, '=', v)

Regras de nomenclatura

O nome do pacote deve ser exclusivo no PyPI e seguir a normalização: não diferencia maiúsculas de minúsculas, e hífens e sublinhados são tratados da mesma forma. Verifique a disponibilidade antes de escolher um nome, para evitar um conflito no momento do envio.

name = 'My_Cool.Tool'
normalized = name.lower().replace('_', '-').replace('.', '-')
print('PyPI normalized name:', normalized)

Declarando dependências

Liste as dependências de execução em dependencies, usando restrições de versão como 'requests>=2.28,<3'. Os extras opcionais ficam em [project.optional-dependencies] e podem ser instalados com pip install mytool[dev].

Mantenha as restrições tão flexíveis quanto for seguro, para que seu pacote possa coexistir com outros.

Pontos de entrada

Para distribuir uma ferramenta de linha de comando, adicione uma entrada em [project.scripts], como mytool = 'mypackage.cli:main'. Depois da instalação, digitar mytool executa essa função. É assim que CLIs como black ou pytest disponibilizam seus comandos.

Incluindo arquivos que não são código

Arquivos de dados (modelos, JSON) não são incluídos automaticamente. Configure os dados do pacote no sistema de compilação para que os arquivos sejam incluídos dentro do arquivo de distribuição binária. Esquecer isso é uma causa comum de erros em que algo funciona localmente, mas deixa de funcionar depois de instalado.

Instalações editáveis para desenvolvimento

Durante o desenvolvimento, instale seu pacote no modo editável com pip install -e .. As alterações no código-fonte entram em vigor imediatamente, sem reinstalação. Isso depende de um pyproject.toml correto, que é mais uma razão para configurá-lo desde o início.

As instalações editáveis oferecem o retorno mais rápido durante a evolução de um pacote.

Verificação rápida

Teste seus conhecimentos sobre a estrutura de projetos.

Recapitulação

Você estruturou um pacote:

Use a estrutura src, com __init__.py identificando os pacotes
pyproject.toml é a configuração padrão: [build-system] e [project]
Declare name, version, requires-python e dependencies
Adicione pontos de entrada em [project.scripts] para CLIs e configure os dados do pacote

Perguntas Frequentes

A aula “Estrutura do projeto e pyproject.toml” é grátis?