<h2>O que é pyproject.toml e Por Que Importa</h2>
<p>O arquivo <code>pyproject.toml</code> é o coração da configuração moderna de projetos Python. Introduzido pela PEP 518 em 2016 e expandido pela PEP 517 e PEP 621, ele substitui a fragmentação de configurações espalhadas por arquivos como <code>setup.py</code>, <code>setup.cfg</code>, <code>requirements.txt</code> e <code>tox.ini</code>. Trata-se de um arquivo de configuração em formato TOML (Tom's Obvious, Minimal Language) que centraliza metadados do projeto, dependências, ferramentas de build e configurações de linters, testadores e outras utilidades.</p>
<p>Por que isso importa? Imagine um projeto onde você precisa atualizar versões em três arquivos diferentes, ou onde um colega novo não sabe aonde procurar a configuração do seu formatter de código. O <code>pyproject.toml</code> resolve isso: uma única fonte de verdade. Além disso, esse padrão alinha Python com outras linguagens como Node.js (package.json) e Rust (Cargo.toml), tornando a experiência mais intuitiva para desenvolvedores que transitam entre ecossistemas.</p>
<h2>Estrutura Básica e Metadados do Projeto</h2>
<h3>A Estrutura Fundamental</h3>
<p>Um <code>pyproject.toml</code> funcional começa com a definição da ferramenta de build e os metadados essenciais do projeto. A estrutura segue a convenção de seções entre colchetes, onde cada seção define configurações para um contexto específico.</p>
<pre><code class="language-toml">[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "meu-projeto-incrivel"
version = "0.1.0"
description = "Uma biblioteca para processar dados com elegância"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "MIT"}
authors = [
{name = "João Silva", email = "joao@example.com"}
]
keywords = ["data", "processing", "python"]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
]</code></pre>
<p>A seção <code>[build-system]</code> define qual ferramenta constrói seu pacote (neste caso, setuptools) e sua versão mínima. A seção <code>[project]</code> contém os metadados PEP 621: nome, versão, descrição, autor, requisitos mínimos de Python e classifiers que ajudam plataformas como PyPI a categorizar seu projeto. O campo <code>requires-python</code> é crítico: ele previne que usuários com Python 3.8 instalem sua biblioteca se você usa features do 3.9.</p>
<h3>Adicionando Dependências</h3>
<p>As dependências são organizadas em grupos: dependências principais (necessárias para qualquer um que instale seu pacote) e dependências opcionais (grupos temáticos para desenvolvimento, testes, documentação, etc).</p>
<pre><code class="language-toml">[project]
dependencies = [
"requests>=2.28.0",
"pydantic>=2.0",
"numpy>=1.20,<2.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.0",
"pytest-cov>=4.0",
"black>=23.0",
"ruff>=0.1.0",
"mypy>=1.0",
]
docs = [
"sphinx>=5.0",
"sphinx-rtd-theme>=1.0",
]
test = [
"pytest>=7.0",
"pytest-cov>=4.0",
"faker>=18.0",
]</code></pre>
<p>Essa abordagem é clara: alguém pode instalar seu projeto com <code>pip install meu-projeto-incrivel</code> (apenas dependências principais) ou com <code>pip install meu-projeto-incrivel[dev]</code> (para desenvolvimento) ou <code>pip install meu-projeto-incrivel[dev,docs]</code> (múltiplos grupos). Note que estamos sendo explícitos com versões: <code>>=2.28.0</code> garante compatibilidade para frente (até certo ponto), enquanto <code><2.0</code> em numpy previne quebras de API.</p>
<h2>Configuração de Ferramentas de Desenvolvimento</h2>
<h3>Integrando Black, Ruff e MyPy</h3>
<p>Python moderno exige verificação de tipo, formatação consistente e linting automático. Em vez de arquivos espalhados como <code>.flake8</code>, <code>.isort.cfg</code> e <code>mypy.ini</code>, você centraliza tudo no <code>pyproject.toml</code>. Isso reduz fricção e evita conflitos de configuração.</p>
<pre><code class="language-toml">[tool.black]
line-length = 100
target-version = ['py39', 'py310', 'py311']
include = '\.pyi?$'
extend-exclude = '''
/(
Diretórios
\.git
\.hg | \.mypy_cache | \.tox | \.venv | build | dist
)/
'''
[tool.ruff]
line-length = 100
target-version = "py39"
select = [
"E", # pycodestyle errors
"W", # pycodestyle warnings
"F", # Pyflakes
"I", # isort
"C", # flake8-comprehensions
"B", # flake8-bugbear
"UP", # pyupgrade
]
ignore = ["E501"] # Black já cuida de linhas longas
[tool.mypy]
python_version = "3.9"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_no_return = true
exclude = ["tests/", "build/", "dist/"]</code></pre>
<p>Com essa configuração, você roda <code>black .</code> para formatar tudo, <code>ruff check .</code> para encontrar problemas de qualidade, e <code>mypy .</code> para verificar tipos. As ferramentas automaticamente leem suas preferências do <code>pyproject.toml</code>. A escolha de <code>line-length = 100</code> é opinião pessoal minha após anos no mercado: 80 é muito restrictivo para código moderno, 120 é muito solto. 100 é o ponto doce.</p>
<h3>Pytest e Cobertura de Testes</h3>
<pre><code class="language-toml">[tool.pytest.ini_options]
minversion = "7.0"
addopts = "-ra -q --strict-markers --disable-warnings"
testpaths = ["tests"]
python_files = ["test_.py", "_test.py"]
markers = [
"slow: marcação para testes lentos",
"integration: testes que requerem conexão externa",
]
[tool.coverage.run]
source = ["src"]
omit = ["/tests/", "/migrations/"]
[tool.coverage.report]
exclude_lines = [
"pragma: no cover",
"def __repr__",
"raise AssertionError",
"raise NotImplementedError",
"if __name__ == .__main__.:",
"if TYPE_CHECKING:",
"if typing.TYPE_CHECKING:",
]
precision = 2</code></pre>
<p>Dessa forma, <code>pytest</code> e <code>coverage</code> sabem exatamente onde procurar seus testes e qual código medir. O campo <code>markers</code> documenta quais tags você usa (útil para rodar <code>pytest -m "not slow"</code> em CI para feedback rápido). A seção <code>coverage.report</code> exclui padrões que inflam artificialmente números de cobertura sem valor real (como <code>__repr__</code> ou imports para type checking).</p>
<h2>Publicação e Distribuição</h2>
<h3>Configurando o Projeto para PyPI</h3>
<p>Quando você quer compartilhar seu código com o mundo, é preciso pensar em como será descoberto e instalado. A seção <code>[project.urls]</code> ajuda nisso, assim como configurações de entrada do seu pacote.</p>
<pre><code class="language-toml">[project.urls]
Homepage = "https://github.com/usuario/meu-projeto-incrivel"
Documentation = "https://meu-projeto.readthedocs.io"
Repository = "https://github.com/usuario/meu-projeto-incrivel.git"
"Bug Tracker" = "https://github.com/usuario/meu-projeto-incrivel/issues"
Changelog = "https://github.com/usuario/meu-projeto-incrivel/releases"
[project.scripts]
meu-comando = "meu_projeto.cli:main"
[project.gui-scripts]
meu-app = "meu_projeto.gui:launch"</code></pre>
<p>O campo <code>[project.scripts]</code> define comandos CLI que será acessíveis depois da instalação. Se alguém instalar seu pacote, poderá simplesmente digitar <code>meu-comando</code> no terminal — setuptools cuida de criar um wrapper executável apropriado. URLs são essenciais para que PyPI exiba links apropriados na página do seu projeto.</p>
<h3>Exemplo Prático: Arquivo Completo</h3>
<p>Aqui está um <code>pyproject.toml</code> realista e completo de um projeto médio:</p>
<pre><code class="language-toml">[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "data-pipeline"
version = "1.2.3"
description = "ETL simplificado para pipelines de dados"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "Apache-2.0"}
authors = [
{name = "Maria Dev", email = "maria@company.com"}
]
keywords = ["etl", "data", "pipeline"]
classifiers = [
"Development Status :: 4 - Beta",
"Intended Audience :: Developers",
"License :: OSI Approved :: Apache Software License",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
]
dependencies = [
"pandas>=1.5.0",
"sqlalchemy>=2.0",
"python-dotenv>=0.20.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.0",
"pytest-cov>=4.0",
"black>=23.0",
"ruff>=0.1.0",
"mypy>=1.0",
]
docs = [
"sphinx>=5.0",
"sphinx-rtd-theme>=1.3",
]
postgres = [
"psycopg2-binary>=2.9",
]
[project.urls]
Homepage = "https://github.com/company/data-pipeline"
Documentation = "https://data-pipeline.readthedocs.io"
Repository = "https://github.com/company/data-pipeline.git"
"Bug Tracker" = "https://github.com/company/data-pipeline/issues"
[project.scripts]
pipeline = "data_pipeline.cli:main"
[tool.setuptools]
packages = ["data_pipeline"]
[tool.black]
line-length = 100
target-version = ['py39', 'py310', 'py311']
[tool.ruff]
line-length = 100
target-version = "py39"
select = ["E", "W", "F", "I", "C", "B", "UP"]
[tool.mypy]
python_version = "3.9"
disallow_untyped_defs = true
check_untyped_defs = true
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra -q"
[tool.coverage.run]
source = ["data_pipeline"]
[tool.coverage.report]
exclude_lines = [
"pragma: no cover",
"if TYPE_CHECKING:",
]</code></pre>
<p>Esse arquivo é autossuficiente. Com apenas isso, alguém pode clonar seu repositório, rodar <code>pip install -e .[dev]</code>, e ter um ambiente pronto para desenvolvimento. Não há <code>setup.py</code> boilerplate, não há <code>requirements.txt</code> desincronizado, não há <code>setup.cfg</code> misterioso.</p>
<h2>Conclusão</h2>
<p>Três pontos críticos aprendidos nesta jornada:</p>
<ol>
<li><strong>Centralização é poder</strong>: O <code>pyproject.toml</code> é a resposta moderna à fragmentação. Uma única fonte de verdade para metadados, dependências e configurações elimina conflitos e reduz erros. Você não precisa mais sincronizar versões entre múltiplos arquivos ou perguntar a colegas onde está a configuração do linter.</li>
</ol>
<ol>
<li><strong>Compatibilidade é intencional</strong>: Declarar explicitamente <code>requires-python</code>, usar seções <code>[project.optional-dependencies]</code> e versionamento semântico não é burocracia — é comunicação clara com seus usuários sobre o que seu projeto oferece e exige. Isso constrói confiança e reduz surpresas ruins em produção.</li>
</ol>
<ol>
<li><strong>Ferramentas modernas convertem em prática</strong>: Usar Black, Ruff e MyPy em conjunto com uma configuração centralizada automatiza qualidade. Você ganha tempo para pensar em lógica, não em formatação ou bugs óbvios. Cada commit passa por um portão de qualidade consistente.</li>
</ol>
<p>O <code>pyproject.toml</code> não é apenas um arquivo de configuração — é um contrato claro entre você e seus usuários/colaboradores.</p>
<h2>Referências</h2>
<ul>
<li><a href="https://www.python.org/dev/peps/pep-0517/" target="_blank" rel="noopener noreferrer">PEP 517 – A build-system independent format</a></li>
<li><a href="https://www.python.org/dev/peps/pep-0621/" target="_blank" rel="noopener noreferrer">PEP 621 – Storing project metadata in pyproject.toml</a></li>
<li><a href="https://toml.io/en/" target="_blank" rel="noopener noreferrer">TOML Documentation</a></li>
<li><a href="https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html" target="_blank" rel="noopener noreferrer">Setuptools: Configuring setuptools using pyproject.toml</a></li>
<li><a href="https://hynek.me/articles/python-packaging/" target="_blank" rel="noopener noreferrer">Hynek Schlawack's Python Packaging Guide</a></li>
</ul>
<p><!-- FIM --></p>