Skip to content

Commit b9b2562

Browse files
dylwil3MichaReiserntBre
authored
describe requires-python fallback in docs (#16704)
Adds description of `requires-python` fallback to documentation for configuration file discovery. --------- Co-authored-by: Micha Reiser <[email protected]> Co-authored-by: Brent Westbrook <[email protected]>
1 parent abaa189 commit b9b2562

File tree

3 files changed

+15
-2
lines changed

3 files changed

+15
-2
lines changed

crates/ruff_workspace/src/options.rs

+3-1
Original file line numberDiff line numberDiff line change
@@ -312,7 +312,9 @@ pub struct Options {
312312
/// ```
313313
///
314314
/// If both are specified, `target-version` takes precedence over
315-
/// `requires-python`.
315+
/// `requires-python`. See [_Inferring the Python version_](https://docs.astral.sh/ruff/configuration/#inferring-the-python-version)
316+
/// for a complete description of how the `target-version` is determined
317+
/// when left unspecified.
316318
///
317319
/// Note that a stub file can [sometimes make use of a typing feature](https://typing.readthedocs.io/en/latest/spec/distributing.html#syntax)
318320
/// before it is available at runtime, as long as the stub does not make

docs/configuration.md

+11
Original file line numberDiff line numberDiff line change
@@ -307,6 +307,17 @@ If Ruff detects multiple configuration files in the same directory, the `.ruff.t
307307
precedence over the `ruff.toml` file, and the `ruff.toml` file will take precedence over
308308
the `pyproject.toml` file.
309309

310+
### Inferring the Python version
311+
When no discovered configuration specifies a [`target-version`](settings.md#target-version), Ruff will attempt to fall back to the minimum version compatible with the `requires-python` field in a nearby `pyproject.toml`.
312+
The rules for this behavior are as follows:
313+
314+
1. If a configuration file is passed directly, Ruff does not attempt to infer a missing `target-version`.
315+
1. If a configuration file is found in the filesystem hierarchy, Ruff will infer a missing `target-version` from the `requires-python` field in a `pyproject.toml` file in the same directory as the found configuration.
316+
1. If we are using a user-level configuration from `${config_dir}/ruff/pyproject.toml`, the `requires-python` field in the first `pyproject.toml` file found in an ancestor of the current working directory takes precedence over the `target-version` in the user-level configuration.
317+
1. If no configuration files are found, Ruff will infer the `target-version` from the `requires-python` field in the first `pyproject.toml` file found in an ancestor of the current working directory.
318+
319+
Note that in these last two cases, the behavior of Ruff may differ depending on the working directory from which it is invoked.
320+
310321
## Python file discovery
311322

312323
When passed a path on the command-line, Ruff will automatically discover all Python files in that

ruff.schema.json

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)