In this lesson, you’ll learn how to extend the functionality of your chosen build backend by utilizing tool-specific configuration tables within your pyproject.toml file.
While the [project] table in pyproject.toml contains standard metadata defined by PEP 621 (like name, version, and dependencies), advanced build systems like Hatch or PDM often require extra instructions to handle unique workflows, such as environment management, specific build hooks, or plugin configurations. These are placed in tables prefixed with [tool.<name>].
The Power of Tool-Specific Tables
Standardization ensures that any tool can read your project’s name, but build-specific tables allow you to "supercharge" the build process. For example, if you use Hatch, you might want to customize how it manages virtual environments or runs tests. By using a tool-specific table, you keep these instructions within your project configuration without polluting the standard metadata.
Concrete Example: Hatch Configuration
Imagine you are using Hatch and want to set a specific environment variable whenever your test suite runs. Instead of hardcoding this in a script, you can configure it directly in your pyproject.toml:
[tool.hatch.envs.default]
extra-dependencies = [
"pytest",
]
[tool.hatch.envs.default.env-vars]
DATABASE_URL = "sqlite:///:memory:"
In this snippet, the [tool.hatch.envs.default] table tells Hatch how to manage the default environment, while [tool.hatch.envs.default.env-vars] passes custom configuration directly to the backend. Other tools—like PDM or Flit—will simply ignore these tables because they only look for their respective [tool.pdm] or [tool.flit] keys.
Why This Matters
This approach maintains a clean separation of concerns. The [project] section tells the world how to install your package, while the [tool] sections tell your specific build system how to behave during development, testing, and distribution. It keeps your build configuration declarative, portable, and easily version-controlled alongside your source code.
Key Takeaway: Use [tool.<backend-name>] tables in your pyproject.toml to define backend-specific behaviors while keeping your standard project metadata compliant with PEP 621.