Principle:PrefectHQ Prefect Python Package Configuration
| Knowledge Sources | |
|---|---|
| Domains | Packaging, Build_System, DevOps |
| Last Updated | 2026-02-09 22:00 GMT |
Overview
Principle of declaring Python package metadata, dependencies, build system, and tooling configuration in a single `pyproject.toml` file following PEP 621 and PEP 517 standards.
Description
Python Package Configuration is the practice of using `pyproject.toml` as the single source of truth for all package-related configuration. This supersedes the legacy `setup.py` / `setup.cfg` approach and centralizes project metadata (name, version, description, license), dependency declarations (required and optional), build system specification (backend, version strategy), entry points (CLI commands, plugins), and development tool configurations (linters, formatters, test runners) into one declarative file. This standardized approach enables tooling interoperability (pip, hatch, flit, poetry all read pyproject.toml) and simplifies package maintenance.
Usage
Apply this principle when creating or maintaining a Python package. It is the correct approach for any Python project that will be distributed via PyPI, installed by users, or that needs consistent tool configuration across a development team. The dual-package pattern (full vs. client) demonstrates how a single codebase can produce multiple distribution packages with different dependency profiles.
Theoretical Basis
The core approach is declarative package specification:
- Define build backend (PEP 517): specifies how to build the package
- Declare metadata (PEP 621): name, version, dependencies, classifiers
- Optional dependencies: feature-gated extras (e.g., `[aws]`, `[docker]`)
- Dynamic versioning: derive version from VCS tags (e.g., versioningit)
- Tool configuration: co-locate linter/formatter/test settings
Pseudo-code Logic:
# Abstract package configuration structure
package = {
"build_system": {"backend": "hatchling", "version_source": "git_tags"},
"metadata": {"name": name, "python_requires": ">=3.10"},
"dependencies": resolve_deps(core_deps + server_deps),
"extras": {"aws": aws_deps, "docker": docker_deps},
"entry_points": {"console_scripts": {"prefect": "prefect.cli:app"}},
"tool_configs": {"pytest": ..., "ruff": ..., "mypy": ...},
}