PY-TYPE0003 · minimum_python_declaration

Keep project and tool Python targets explicit and mutually consistent.

This is a deterministic rule for python. Read its implementation.

Definition

Parse [project].requires-python with packaging. Require it to exclude every Python 3 minor below minimum_version. When Ruff, Pyrefly, ty, mypy, Pyright, or basedpyright is configured, require its target-version key and require that target to equal the minimum Python minor admitted by the project declaration. Ruff per-file targets must meet the same project minimum because a file cannot safely support less than the published package.

Evidence

Report a missing or invalid pyproject.toml, a missing or invalid project declaration, each configured tool without an explicit target, and each old or inconsistent target. Locations point to the relevant TOML declaration when it can be identified. The value is the number of missing or inconsistent Python target declarations.

Exceptions

A type checker with no [tool] table is outside the project and is not required. Interpreter discovery is deliberately not accepted for a configured checker because it varies between developer machines and CI. Packaging upper bounds and exclusions remain valid when they preserve the declared minimum.

Examples

Good

`requires-python = ">=3.14"`, Ruff `target-version = "py314"`, and Pyrefly
`python-version = "3.14"` agree.

Bad
~~~
`requires-python = ">=3.13"` permits an older interpreter. A configured `[tool.ty]` without
`[tool.ty.environment].python-version` is missing a stable target. Ruff `py313` disagrees
with a package whose minimum is Python 3.14.

## References

- Cites "Python Packaging User Guide", `requires-python`. [Open reference](https://packaging.python.org/en/latest/specifications/pyproject-toml/#requires-python)
- Cites "packaging documentation", specifier API. [Open reference](https://packaging.pypa.io/en/stable/specifiers.html)
- Cites "Ruff documentation", configuration for `target-version`. [Open reference](https://docs.astral.sh/ruff/settings/#target-version)
- Cites "Pyrefly documentation", `python-version`. [Open reference](https://pyrefly.org/en/docs/configuration/)
- Cites "ty documentation", `python-version`. [Open reference](https://docs.astral.sh/ty/reference/configuration/#python-version)