Pular para o conteúdo principal

​
Arquivo pyproject.toml para Python

O arquivo pyproject.toml é uma forma moderna de especificar todos os requisitos do sistema de build e as dependências do seu projeto em um único arquivo. Este guia mostra como criar, configurar e usar o pyproject.toml para garantir consistência entre os ambientes de desenvolvimento e produção.

​
O que é um arquivo pyproject.toml?

Um pyproject.toml lista dependências, o sistema de build e outros metadados do seu projeto Python. Isso permite:
  • Permitir que você e sua equipe mantenham ambientes idênticos
  • Fazer com que novos colaboradores reproduzam o ambiente exatamente
  • Configurar dependências de desenvolvimento e produção separadamente
1

Criar o arquivo pyproject.toml

Primeiro, crie um arquivo chamado pyproject.toml na raiz do seu projeto.
2

Defina os detalhes do seu projeto

No arquivo pyproject.toml, comece definindo os metadados do projeto. Vamos definir o nome do projeto, versão, descrição e outras informações relevantes.
O nome do projeto deve conter letras ASCII, dígitos, underscores ”_”, hífens ”-” e pontos ”.”. Não deve começar ou terminar com underscore, hífen ou ponto. Por exemplo:
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
3

Listar dependências do projeto

Em seguida, vamos listar as dependências necessárias para o projeto. Podemos especificar dependências de produção e de desenvolvimento. As dependências de produção são listadas na seção dependencies, enquanto as dependências de desenvolvimento podem ser listadas em optional-dependencies com um nome de grupo específico (por exemplo, dev).
Você pode especificar versões para suas dependências usando operadores de comparação como ==, >=, <… No exemplo abaixo não especificamos versões; isso significa que a versão mais recente será instalada. É recomendado especificar versões exatas para garantir reprodutibilidade e evitar que atualizações incompatíveis quebrem o ambiente em produção.
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
dependencies = [
    "discord-py",
    "aiohttp"
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black"
]
4

Configurar o sistema de build

Por fim, precisamos especificar os requisitos do sistema de build. Isso é necessário para que ferramentas como o pip saibam como construir e instalar seu projeto. Usaremos setuptools como backend de build, que é uma escolha comum, mas você pode escolher outros como o poetry.
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
dependencies = [
    "discord.py",
    "aiohttp"
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black"
]

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

​
Instalar dependências com pip

Para instalar as dependências listadas no pyproject.toml, você pode usar o pip ou outras ferramentas que suportem pyproject.toml. Isso permite trabalhar no projeto com as dependências instaladas. 
pip install .
Esse comando irá ler o pyproject.toml, instalar as dependências listadas em dependencies e configurar seu projeto para desenvolvimento. Se quiser instalar também as dependências de desenvolvimento, use: 
pip install .[dev]
Isso instalará dependências de produção e de desenvolvimento, permitindo que você trabalhe no projeto com todas as ferramentas necessárias.

​
Boas práticas e dicas:

  • Mantenha atualizado: Revise e atualize o pyproject.toml regularmente conforme adicionar novas dependências
  • Use versões exatas: Prefira == em vez de >, >= ou não especificar versão para evitar surpresas em produção
  • Versionamento: Faça commit do pyproject.toml no Git para rastrear mudanças de dependências e versões
  • Ambiente isolado: Mantenha um ambiente virtual por projeto para evitar conflitos globais
  • Teste localmente: Antes de realizar deploy, teste o arquivo com pip install . em um ambiente novo

​
Próximos passos

Com seu pyproject.toml configurado:
  1. Faça commit no seu repositório Git.
  2. Hospede seu projeto na Square Cloud.
  3. Configure deploy automático via GitHub.
  4. Bem-vindo à hospedagem profissional de aplicações Python!
Um pyproject.toml bem estruturado é a base para qualquer aplicação Python bem-sucedida, garantindo que sua aplicação funcione perfeitamente na Square Cloud.