Default to latest supported Python version for version-related syntax errors (astral-sh#17529)

## Summary

This PR partially addresses astral-sh#16418 via the following:

- `LinterSettings::unresolved_python_version` is now a `TargetVersion`,
which is a thin wrapper around an `Option<PythonVersion>`
- `Checker::target_version` now calls `TargetVersion::linter_version`
internally, which in turn uses `unwrap_or_default` to preserve the
current default behavior
- Calls to the parser now call `TargetVersion::parser_version`, which
calls `unwrap_or_else(PythonVersion::latest)`
- The `Checker`'s implementation of
`SemanticSyntaxContext::python_version` also uses
`TargetVersion::parser_version` to use `PythonVersion::latest` for
semantic errors

In short, all lint rule behavior should be unchanged, but we default to
the latest Python version for the new syntax errors, which should
minimize confusing version-related syntax errors for users without a
version configured.

## Test Plan

Existing tests, which showed no changes (except for printing default
settings).

Author: ntBre

crates/ruff/src/cache.rs

@@ -616,7 +616,7 @@ mod tests {
         let settings = Settings {
             cache_dir,
             linter: LinterSettings {
-                unresolved_target_version: PythonVersion::latest(),
+                unresolved_target_version: PythonVersion::latest().into(),
                 ..Default::default()
             },
             ..Settings::default()

crates/ruff/tests/lint.rs

@@ -3930,7 +3930,7 @@ from typing import Union;foo: Union[int, str] = 1
         linter.per_file_ignores = {}
         linter.safety_table.forced_safe = []
         linter.safety_table.forced_unsafe = []
-        linter.unresolved_target_version = 3.9
+        linter.unresolved_target_version = none
         linter.per_file_target_version = {}
         linter.preview = disabled
         linter.explicit_preview_rules = false
@@ -4215,7 +4215,7 @@ from typing import Union;foo: Union[int, str] = 1
         linter.per_file_ignores = {}
         linter.safety_table.forced_safe = []
         linter.safety_table.forced_unsafe = []
-        linter.unresolved_target_version = 3.9
+        linter.unresolved_target_version = none
         linter.per_file_target_version = {}
         linter.preview = disabled
         linter.explicit_preview_rules = false

crates/ruff_linter/src/checkers/ast/mod.rs

@@ -72,7 +72,7 @@ use crate::rules::pyflakes::rules::{
 };
 use crate::rules::pylint::rules::{AwaitOutsideAsync, LoadBeforeGlobalDeclaration};
 use crate::rules::{flake8_pyi, flake8_type_checking, pyflakes, pyupgrade};
-use crate::settings::{flags, LinterSettings};
+use crate::settings::{flags, LinterSettings, TargetVersion};
 use crate::{docstrings, noqa, Locator};
 
 mod analyze;
@@ -232,7 +232,7 @@ pub(crate) struct Checker<'a> {
     /// A state describing if a docstring is expected or not.
     docstring_state: DocstringState,
     /// The target [`PythonVersion`] for version-dependent checks.
-    target_version: PythonVersion,
+    target_version: TargetVersion,
     /// Helper visitor for detecting semantic syntax errors.
     #[expect(clippy::struct_field_names)]
     semantic_checker: SemanticSyntaxChecker,
@@ -257,7 +257,7 @@ impl<'a> Checker<'a> {
         source_type: PySourceType,
         cell_offsets: Option<&'a CellOffsets>,
         notebook_index: Option<&'a NotebookIndex>,
-        target_version: PythonVersion,
+        target_version: TargetVersion,
     ) -> Checker<'a> {
         let semantic = SemanticModel::new(&settings.typing_modules, path, module);
         Self {
@@ -523,9 +523,16 @@ impl<'a> Checker<'a> {
         }
     }
 
-    /// Return the [`PythonVersion`] to use for version-related checks.
-    pub(crate) const fn target_version(&self) -> PythonVersion {
-        self.target_version
+    /// Return the [`PythonVersion`] to use for version-related lint rules.
+    ///
+    /// If the user did not provide a target version, this defaults to the lowest supported Python
+    /// version ([`PythonVersion::default`]).
+    ///
+    /// Note that this method should not be used for version-related syntax errors emitted by the
+    /// parser or the [`SemanticSyntaxChecker`], which should instead default to the _latest_
+    /// supported Python version.
+    pub(crate) fn target_version(&self) -> PythonVersion {
+        self.target_version.linter_version()
     }
 
     fn with_semantic_checker(&mut self, f: impl FnOnce(&mut SemanticSyntaxChecker, &Checker)) {
@@ -583,7 +590,10 @@ impl TypingImporter<'_, '_> {
 
 impl SemanticSyntaxContext for Checker<'_> {
     fn python_version(&self) -> PythonVersion {
-        self.target_version
+        // Reuse `parser_version` here, which should default to `PythonVersion::latest` instead of
+        // `PythonVersion::default` to minimize version-related semantic syntax errors when
+        // `target_version` is unset.
+        self.target_version.parser_version()
     }
 
     fn global(&self, name: &str) -> Option<TextRange> {
@@ -1366,7 +1376,7 @@ impl<'a> Visitor<'a> for Checker<'a> {
             // we can't defer again, or we'll infinitely recurse!
             && !self.semantic.in_deferred_type_definition()
             && self.semantic.in_type_definition()
-            && (self.semantic.future_annotations_or_stub()||self.target_version.defers_annotations())
+            && (self.semantic.future_annotations_or_stub()||self.target_version().defers_annotations())
             && (self.semantic.in_annotation() || self.source_type.is_stub())
         {
             if let Expr::StringLiteral(string_literal) = expr {
@@ -2594,7 +2604,7 @@ impl<'a> Checker<'a> {
                 // annotations` is active, or they are type definitions in a stub file.
                 debug_assert!(
                     (self.semantic.future_annotations_or_stub()
-                        || self.target_version.defers_annotations())
+                        || self.target_version().defers_annotations())
                         && (self.source_type.is_stub() || self.semantic.in_annotation())
                 );
 
@@ -2932,7 +2942,7 @@ pub(crate) fn check_ast(
     source_type: PySourceType,
     cell_offsets: Option<&CellOffsets>,
     notebook_index: Option<&NotebookIndex>,
-    target_version: PythonVersion,
+    target_version: TargetVersion,
 ) -> (Vec<Diagnostic>, Vec<SemanticSyntaxError>) {
     let module_path = package
         .map(PackageRoot::path)

crates/ruff_linter/src/linter.rs

@@ -35,7 +35,7 @@ use crate::registry::{AsRule, Rule, RuleSet};
 #[cfg(any(feature = "test-rules", test))]
 use crate::rules::ruff::rules::test_rules::{self, TestRule, TEST_RULES};
 use crate::settings::types::UnsafeFixes;
-use crate::settings::{flags, LinterSettings};
+use crate::settings::{flags, LinterSettings, TargetVersion};
 use crate::source_kind::SourceKind;
 use crate::{directives, fs, warn_user_once, Locator};
 
@@ -111,7 +111,7 @@ pub fn check_path(
     source_kind: &SourceKind,
     source_type: PySourceType,
     parsed: &Parsed<ModModule>,
-    target_version: PythonVersion,
+    target_version: TargetVersion,
 ) -> Vec<Message> {
     // Aggregate all diagnostics.
     let mut diagnostics = vec![];
@@ -160,7 +160,7 @@ pub fn check_path(
             locator,
             comment_ranges,
             settings,
-            target_version,
+            target_version.linter_version(),
         ));
     }
 
@@ -215,7 +215,7 @@ pub fn check_path(
                     package,
                     source_type,
                     cell_offsets,
-                    target_version,
+                    target_version.linter_version(),
                 );
 
                 diagnostics.extend(import_diagnostics);
@@ -390,7 +390,7 @@ pub fn add_noqa_to_path(
 ) -> Result<usize> {
     // Parse once.
     let target_version = settings.resolve_target_version(path);
-    let parsed = parse_unchecked_source(source_kind, source_type, target_version);
+    let parsed = parse_unchecked_source(source_kind, source_type, target_version.parser_version());
 
     // Map row and column locations to byte slices (lazily).
     let locator = Locator::new(source_kind.source_code());
@@ -451,11 +451,13 @@ pub fn lint_only(
 ) -> LinterResult {
     let target_version = settings.resolve_target_version(path);
 
-    if matches!(target_version, PythonVersion::PY314) && !is_py314_support_enabled(settings) {
+    if matches!(target_version, TargetVersion(Some(PythonVersion::PY314)))
+        && !is_py314_support_enabled(settings)
+    {
         warn_user_once!("Support for Python 3.14 is under development and may be unstable. Enable `preview` to remove this warning.");
     }
 
-    let parsed = source.into_parsed(source_kind, source_type, target_version);
+    let parsed = source.into_parsed(source_kind, source_type, target_version.parser_version());
 
     // Map row and column locations to byte slices (lazily).
     let locator = Locator::new(source_kind.source_code());
@@ -563,14 +565,17 @@ pub fn lint_fix<'a>(
 
     let target_version = settings.resolve_target_version(path);
 
-    if matches!(target_version, PythonVersion::PY314) && !is_py314_support_enabled(settings) {
+    if matches!(target_version, TargetVersion(Some(PythonVersion::PY314)))
+        && !is_py314_support_enabled(settings)
+    {
         warn_user_once!("Support for Python 3.14 is under development and may be unstable. Enable `preview` to remove this warning.");
     }
 
     // Continuously fix until the source code stabilizes.
     loop {
         // Parse once.
-        let parsed = parse_unchecked_source(&transformed, source_type, target_version);
+        let parsed =
+            parse_unchecked_source(&transformed, source_type, target_version.parser_version());
 
         // Map row and column locations to byte slices (lazily).
         let locator = Locator::new(transformed.source_code());
@@ -972,8 +977,9 @@ mod tests {
         settings: &LinterSettings,
     ) -> Vec<Message> {
         let source_type = PySourceType::from(path);
+        let target_version = settings.resolve_target_version(path);
         let options =
-            ParseOptions::from(source_type).with_target_version(settings.unresolved_target_version);
+            ParseOptions::from(source_type).with_target_version(target_version.parser_version());
         let parsed = ruff_python_parser::parse_unchecked(source_kind.source_code(), options)
             .try_into_module()
             .expect("PySourceType always parses into a module");
@@ -998,7 +1004,7 @@ mod tests {
             source_kind,
             source_type,
             &parsed,
-            settings.unresolved_target_version,
+            target_version,
         );
         messages.sort_by_key(Ranged::start);
         messages
@@ -1121,7 +1127,7 @@ mod tests {
             contents,
             &LinterSettings {
                 rules: settings::rule_table::RuleTable::empty(),
-                unresolved_target_version: python_version,
+                unresolved_target_version: python_version.into(),
                 preview: settings::types::PreviewMode::Enabled,
                 ..Default::default()
             },
@@ -1139,7 +1145,7 @@ mod tests {
             &SourceKind::IpyNotebook(Notebook::from_path(path)?),
             path,
             &LinterSettings {
-                unresolved_target_version: python_version,
+                unresolved_target_version: python_version.into(),
                 rules: settings::rule_table::RuleTable::empty(),
                 preview: settings::types::PreviewMode::Enabled,
                 ..Default::default()
@@ -1205,7 +1211,7 @@ mod tests {
         "pyi019_adds_typing_extensions",
 		PYI019_EXAMPLE,
 		&LinterSettings {
-			unresolved_target_version: PythonVersion::PY310,
+			unresolved_target_version: PythonVersion::PY310.into(),
 			typing_extensions: true,
 			..LinterSettings::for_rule(Rule::CustomTypeVarForSelf)
 		}
@@ -1214,7 +1220,7 @@ mod tests {
         "pyi019_does_not_add_typing_extensions",
 		PYI019_EXAMPLE,
 		&LinterSettings {
-			unresolved_target_version: PythonVersion::PY310,
+			unresolved_target_version: PythonVersion::PY310.into(),
 			typing_extensions: false,
 			..LinterSettings::for_rule(Rule::CustomTypeVarForSelf)
 		}
@@ -1223,7 +1229,7 @@ mod tests {
         "pyi019_adds_typing_without_extensions_disabled",
 		PYI019_EXAMPLE,
 		&LinterSettings {
-			unresolved_target_version: PythonVersion::PY311,
+			unresolved_target_version: PythonVersion::PY311.into(),
 			typing_extensions: true,
 			..LinterSettings::for_rule(Rule::CustomTypeVarForSelf)
 		}
@@ -1232,7 +1238,7 @@ mod tests {
         "pyi019_adds_typing_with_extensions_disabled",
 		PYI019_EXAMPLE,
 		&LinterSettings {
-			unresolved_target_version: PythonVersion::PY311,
+			unresolved_target_version: PythonVersion::PY311.into(),
 			typing_extensions: false,
 			..LinterSettings::for_rule(Rule::CustomTypeVarForSelf)
 		}
@@ -1244,7 +1250,7 @@ mod tests {
 			def __new__(cls) -> C: ...
 		",
 		&LinterSettings {
-			unresolved_target_version: PythonVersion { major: 3, minor: 10 },
+			unresolved_target_version: PythonVersion { major: 3, minor: 10 }.into(),
 			typing_extensions: false,
 			..LinterSettings::for_rule(Rule::NonSelfReturnType)
 		}
@@ -1261,7 +1267,7 @@ mod tests {
 			return commons
 		"#,
 		&LinterSettings {
-			unresolved_target_version: PythonVersion { major: 3, minor: 8 },
+			unresolved_target_version: PythonVersion { major: 3, minor: 8 }.into(),
 			typing_extensions: false,
 			..LinterSettings::for_rule(Rule::FastApiNonAnnotatedDependency)
 		}
@@ -1276,7 +1282,7 @@ mod tests {
 		"pyi026_disabled",
 		"Vector = list[float]",
 		&LinterSettings {
-			unresolved_target_version: PythonVersion { major: 3, minor: 9 },
+			unresolved_target_version: PythonVersion { major: 3, minor: 9 }.into(),
 			typing_extensions: false,
 			..LinterSettings::for_rule(Rule::TypeAliasWithoutAnnotation)
 		}

crates/ruff_linter/src/rules/fastapi/mod.rs

@@ -36,7 +36,7 @@ mod tests {
         let diagnostics = test_path(
             Path::new("fastapi").join(path).as_path(),
             &settings::LinterSettings {
-                unresolved_target_version: ruff_python_ast::PythonVersion::PY38,
+                unresolved_target_version: ruff_python_ast::PythonVersion::PY38.into(),
                 ..settings::LinterSettings::for_rule(rule_code)
             },
         )?;

crates/ruff_linter/src/rules/flake8_annotations/mod.rs

@@ -128,7 +128,7 @@ mod tests {
         let diagnostics = test_path(
             Path::new("flake8_annotations/auto_return_type.py"),
             &LinterSettings {
-                unresolved_target_version: PythonVersion::PY38,
+                unresolved_target_version: PythonVersion::PY38.into(),
                 ..LinterSettings::for_rules(vec![
                     Rule::MissingReturnTypeUndocumentedPublicFunction,
                     Rule::MissingReturnTypePrivateFunction,

crates/ruff_linter/src/rules/flake8_async/mod.rs

@@ -44,7 +44,7 @@ mod tests {
         let diagnostics = test_path(
             Path::new("flake8_async").join(path),
             &LinterSettings {
-                unresolved_target_version: PythonVersion::PY310,
+                unresolved_target_version: PythonVersion::PY310.into(),
                 ..LinterSettings::for_rule(Rule::AsyncFunctionWithTimeout)
             },
         )?;

crates/ruff_linter/src/rules/flake8_bugbear/mod.rs

@@ -100,7 +100,7 @@ mod tests {
         let diagnostics = test_path(
             Path::new("flake8_bugbear").join(path).as_path(),
             &LinterSettings {
-                unresolved_target_version: target_version,
+                unresolved_target_version: target_version.into(),
                 ..LinterSettings::for_rule(rule_code)
             },
         )?;

crates/ruff_linter/src/rules/flake8_builtins/mod.rs

@@ -217,7 +217,7 @@ mod tests {
         let diagnostics = test_path(
             Path::new("flake8_builtins").join(path).as_path(),
             &LinterSettings {
-                unresolved_target_version: PythonVersion::PY38,
+                unresolved_target_version: PythonVersion::PY38.into(),
                 ..LinterSettings::for_rule(rule_code)
             },
         )?;

crates/ruff_linter/src/rules/flake8_future_annotations/mod.rs

@@ -30,7 +30,7 @@ mod tests {
         let diagnostics = test_path(
             Path::new("flake8_future_annotations").join(path).as_path(),
             &settings::LinterSettings {
-                unresolved_target_version: PythonVersion::PY37,
+                unresolved_target_version: PythonVersion::PY37.into(),
                 ..settings::LinterSettings::for_rule(Rule::FutureRewritableTypeAnnotation)
             },
         )?;
@@ -49,7 +49,7 @@ mod tests {
         let diagnostics = test_path(
             Path::new("flake8_future_annotations").join(path).as_path(),
             &settings::LinterSettings {
-                unresolved_target_version: PythonVersion::PY37,
+                unresolved_target_version: PythonVersion::PY37.into(),
                 ..settings::LinterSettings::for_rule(Rule::FutureRequiredTypeAnnotation)
             },
         )?;