FA102 errors eventhough requires-python in pyproject.toml is ">=3.12"

[SimonMarynissen]

I have the following (standard) directory layout:

├── src
│   └── packagename
│       └── ...
├── pyproject.toml
└── ruff.toml

Part from my pyproject.toml:

[project]
name = "packagename"
requires-python = ">=3.12"

My complete ruff.toml:

src = ["src"]

[format]
skip-magic-trailing-comma = true
line-ending = "lf"

[lint]
select = ["ALL"]
ignore = ["ANN101", "D203", "D213", "S320"]

Ruff version: 0.3.0, run with the command ruff check in the directory of pyproject.toml.
In the rule FA102, it is mentioned:

This rule respects the target-version setting. For example, if your project targets Python 3.10 and above, adding from future import annotations does not impact your ability to leverage PEP 604-style unions (e.g., to convert Optional[str] to str | None). As such, this rule will only flag such usages if your project targets Python 3.9 or below.

In the documentation of target-version it is mentioned that requires-python in pyproject.toml is preferred over the target-version option in ruff.toml.
If I add target-version = "py312" to my ruff.toml, then there are no FA102 errors.

[charliermarsh]

I think it's possible that if we find a ruff.toml, we don't even look for the pyproject.toml, since we only use a single configuration file to resolve configuration for the project. So you could fix this (I suspect) by moving your configuration into your pyproject.toml, like:

[project]
name = "packagename"
requires-python = ">=3.12"

[tool.ruff]
src = ["src"]

[tool.ruff.format]
skip-magic-trailing-comma = true
line-ending = "lf"

[tool.ruff.lint]
select = ["ALL"]
ignore = ["ANN101", "D203", "D213", "S320"]

But, we should probably also be respecting the pyproject.toml here.

[charliermarsh]

(If possible, can you give that a try to confirm my suspicion?)

[SimonMarynissen]

That does indeed work, but I would prefer to have a separate ruff.toml.

[MichaReiser]

@charliermarsh considering that you marked this as a bug. What would the desired resolution order be?

The documentation mentions

Ruff can be configured through a pyproject.toml, ruff.toml, or .ruff.toml file.

which seems like pyproject.toml intentionally has higher precedence than ruff.toml. Changing the resolution order would probably be a breaking change.

Or is the fix that we should disregard any pyproject.toml without any tool.ruff section (but that could lead to other false positives because we might disregard a requires-python configuration). That makes me think that the only "proper" solution is to merge the configurations, but that might lead to other unintended or unexpected behavior.

[charliermarsh]

Or is the fix that we should disregard any pyproject.toml without any tool.ruff section (but that could lead to other false positives because we might disregard a requires-python configuration).

We already do this IIRC.

[charliermarsh]

That makes me think that the only "proper" solution is to merge the configurations, but that might lead to other unintended or unexpected behavior.

Yeah fixing this requires that we merge configuration in some way, because the user is inherently asking for information to come from two different files. So we either do something like "when we see a ruff.toml, check for a pyproject.toml in the same directory and use its requires-python", or mark it as unsupported.

[SimonMarynissen]

If I may add my 2 cents: if the precedence is pyproject.toml > ruff.toml > .ruff.toml, then pyproject.toml is always parsed (if it exists) and if no ruff elements are found, I guess you either get bad defaults or an error (I am not too familiar with ruff), so it shouldn't be big change to look for ruff.toml in that case. That would certainly solve my case and would most likely not break workflows from other ruff users.

[DimitriPapadopoulos]

Reproduced in sphinx-doc/sphinx#12250. Removing target-version = "py39" from .ruff.toml breaks the tests as requires-python = ">=3.9" from pyproject.toml is not taken into account.

I think ruff should take into account requires-python" from pyproject.toml, alternatively fix the documentation:

ruff/crates/ruff_workspace/src/options.rs

Lines 314 to 317 in 42d52eb

	/// If you're already using a `pyproject.toml` file, we recommend
	/// `project.requires-python` instead, as it's based on Python packaging
	/// standards, and will be respected by other tools. For example, Ruff
	/// treats the following as identical to `target-version = "py38"`:

[DimitriPapadopoulos]

Same issue in jaraco/skeleton#119. The situation is even worse here, as requires-python is defined in setup.cfg instead of pyproject.toml.

The rationale for a ruff.toml file separate from pyproject.toml is described here:
pypa/setuptools#3979 (review)

[DimitriPapadopoulos]

In the documentation, Config file discovery reads:

Unlike ESLint, Ruff does not merge settings across configuration files; instead, the "closest" configuration file is used, and any parent configuration files are ignored. In lieu of this implicit cascade, Ruff supports an extend field, which allows you to inherit the settings from another config file, like so:

pyproject.toml       ruff.toml

# Extend the `ruff.toml` file in the parent directory...
extend = "../ruff.toml"

# ...but use a different line length.
line-length = 100

All of the above rules apply equivalently to pyproject.toml, ruff.toml, and .ruff.toml files. If Ruff detects multiple configuration files in the same directory, the .ruff.toml file will take precedence over the ruff.toml file, and the ruff.toml file will take precedence over the pyproject.toml file.

I was thinking about adding extend = "pyproject.toml" to ruff.toml to pick requires-python from pyproject.toml, but this doesn't make sense as the namespaces and the way the files are parsed are different.

[DimitriPapadopoulos]

My suggestion would be to:

1. Keep a single configuration file for ruff itself, that is, disregard the [tool.ruff] subtable in pyproject.toml if files .ruff.toml or ruff.toml exist - or ruff is passed option --config.
2. Take into account other tables of pyproject.toml that contain keys that impact ruff, typically the [project] table and its requires-python key.
3. Support keys of interest in both setup.cfg and pyproject.toml. Not sure about precedence in the ill-formed case where requires-python would be defined in both setup.cfg and pyproject.toml.
4. Keep the existing precedence if pyproject.toml or setup.cfg define requires-python and the ruff config file defines target-version simultaneously: the ruff config file and target-version take precedence.