3.14 deferred evaluation of annotations

[nickdrozd]

In 3.14, type annotations are not evaluated eagerly.

https://docs.python.org/3.14/whatsnew/3.14.html#whatsnew314-pep649

So this snippet runs fine:

class X:
    x: X

Ruff flags the field annotation as an undefined name. It is undefined in 3.13 and earlier, but in 3.14 this is a false positive. Earlier versions require from __future__ import annotations to make this work.

[dhruvmanila]

Thanks for the issue.

The following are the affected rules that should be updated (not a complete list):

• https://docs.astral.sh/ruff/rules/#flake8-future-annotations-fa
• https://docs.astral.sh/ruff/rules/unnecessary-future-import/

As per the release schedule of 3.14, the first beta is scheduled in around 5 months so I'd wait for a while until making any changes for 3.14.

[Daverball]

Most importantly we will need to update the checker walking of the AST, so the semantic model contains correct state. Everywhere that currently checks for the presence of from __future__ import annotations to defer visiting a type expression, will need to also check for a Python version of >= 3.14.

That being said, as far as I know, there's not a 1:1 equivalence in semantics between the deferral strategy for PEP 649 and PEP 563, so we may need to do some things subtly different, to properly model the runtime semantics. Since there are some things that are safe with PEP 563, that aren't safe with PEP 649. Which is also the reason why from __future__ import annotations doesn't go away in 3.14 and still has the same semantics as it did before (i.e. you will get string forward references in __annotations__).

[nickdrozd]

Some discussion here: nedbat/coveragepy#1908

[nickdrozd]

Besides undefined name, this also raises false positives for TC004.

[Daverball]

Any rule that relies on the semantic runtime context of the expression will yield incorrect results, this also includes TC001-003 , TC010 and UP037 just to name some other ones I can think of immediately. Ultimately it's not really all that helpful to enumerate the affected rules here, beyond documenting which false positives/negatives are currently expected with 3.14, since this is a shortcoming of the semantic model, not the implementation of the individual rules.

[Tatsh]

I would love to have a rule and fix that says to add from __future__ import annotations to the file (and it would be great if the checker checks that it actually makes a difference), and then an upgrade rule/fix when we're on 3.14+ to remove it.

[Daverball]

I would love to have a rule and fix that says to add from __future__ import annotations to the file (and it would be great if the checker checks that it actually makes a difference), and then an upgrade rule/fix when we're on 3.14+ to remove it.

You can already force an import with missing-required-import:

[tool.ruff.lint.isort]
required-imports = ["from __future__ import annotations"]

And the opposite case could potentially be covered by unecessary-future-import.

[dylwil3]

Below is a patch to the semantic model that does what @Daverball suggests and simply treats Python version 3.14 as if there was an implicit from __future__ import annotations everywhere.

I think the question is whether this is correct enough for our semantic purposes. For a specific example, consider the following:

from annotationlib import get_annotations, Format


class X:
    def to_y(self) -> Y:
        return Y()


print(get_annotations(X.to_y, format=Format.VALUE))


class Y: ...

This raises a NameError at runtime for any Python version, including Python 3.14 - though for Python 3.14 the traceback is different because the exception is thrown while evaluating get_annotations and not before. On the other hand, if we choose a different Format or if we prepend with from __future__ import annotations, then we don't get a NameError. The patch below does not emit F821 when target-version = py314.

I think this is correct behavior, and should be thought of as roughly equivalent to the following:

from inspect import get_annotations


class X:
    def to_y(self) -> Y:
        return Y()


print(get_annotations(X.to_y, eval_str=True))


class Y: ...

Does that sound right to you @Daverball ?

Semantic model patch

diff --git c/crates/ruff_linter/src/checkers/ast/annotation.rs w/crates/ruff_linter/src/checkers/ast/annotation.rs
index 86d1ba50f..f545ba27e 100644
--- c/crates/ruff_linter/src/checkers/ast/annotation.rs
+++ w/crates/ruff_linter/src/checkers/ast/annotation.rs
@@ -1,4 +1,4 @@
-use ruff_python_ast::StmtFunctionDef;
+use ruff_python_ast::{PythonVersion, StmtFunctionDef};
 use ruff_python_semantic::{ScopeKind, SemanticModel};
 
 use crate::rules::flake8_type_checking;
@@ -29,7 +29,11 @@ pub(super) enum AnnotationContext {
 impl AnnotationContext {
     /// Determine the [`AnnotationContext`] for an annotation based on the current scope of the
     /// semantic model.
-    pub(super) fn from_model(semantic: &SemanticModel, settings: &LinterSettings) -> Self {
+    pub(super) fn from_model(
+        semantic: &SemanticModel,
+        settings: &LinterSettings,
+        version: PythonVersion,
+    ) -> Self {
         // If the annotation is in a class scope (e.g., an annotated assignment for a
         // class field) or a function scope, and that class or function is marked as
         // runtime-required, treat the annotation as runtime-required.
@@ -59,7 +63,7 @@ impl AnnotationContext {
         // If `__future__` annotations are enabled or it's a stub file,
         // then annotations are never evaluated at runtime,
         // so we can treat them as typing-only.
-        if semantic.future_annotations_or_stub() {
+        if semantic.future_annotations_or_stub() || version.defers_annotations() {
             return Self::TypingOnly;
         }
 
@@ -81,6 +85,7 @@ impl AnnotationContext {
         function_def: &StmtFunctionDef,
         semantic: &SemanticModel,
         settings: &LinterSettings,
+        version: PythonVersion,
     ) -> Self {
         if flake8_type_checking::helpers::runtime_required_function(
             function_def,
@@ -88,7 +93,7 @@ impl AnnotationContext {
             semantic,
         ) {
             Self::RuntimeRequired
-        } else if semantic.future_annotations_or_stub() {
+        } else if semantic.future_annotations_or_stub() || version.defers_annotations() {
             Self::TypingOnly
         } else {
             Self::RuntimeEvaluated
diff --git c/crates/ruff_linter/src/checkers/ast/mod.rs w/crates/ruff_linter/src/checkers/ast/mod.rs
index ebff12438..56f8ad296 100644
--- c/crates/ruff_linter/src/checkers/ast/mod.rs
+++ w/crates/ruff_linter/src/checkers/ast/mod.rs
@@ -982,8 +982,12 @@ impl<'a> Visitor<'a> for Checker<'a> {
 
                 // Function annotations are always evaluated at runtime, unless future annotations
                 // are enabled.
-                let annotation =
-                    AnnotationContext::from_function(function_def, &self.semantic, self.settings);
+                let annotation = AnnotationContext::from_function(
+                    function_def,
+                    &self.semantic,
+                    self.settings,
+                    self.target_version(),
+                );
 
                 // The first parameter may be a single dispatch.
                 let singledispatch =
@@ -1180,7 +1184,11 @@ impl<'a> Visitor<'a> for Checker<'a> {
                 value,
                 ..
             }) => {
-                match AnnotationContext::from_model(&self.semantic, self.settings) {
+                match AnnotationContext::from_model(
+                    &self.semantic,
+                    self.settings,
+                    self.target_version(),
+                ) {
                     AnnotationContext::RuntimeRequired => {
                         self.visit_runtime_required_annotation(annotation);
                     }
@@ -1335,7 +1343,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.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 {
@@ -2537,7 +2545,8 @@ impl<'a> Checker<'a> {
                 // if they are annotations in a module where `from __future__ import
                 // annotations` is active, or they are type definitions in a stub file.
                 debug_assert!(
-                    self.semantic.future_annotations_or_stub()
+                    (self.semantic.future_annotations_or_stub()
+                        || self.target_version.defers_annotations())
                         && (self.source_type.is_stub() || self.semantic.in_annotation())
                 );
 
diff --git c/crates/ruff_linter/src/settings/types.rs w/crates/ruff_linter/src/settings/types.rs
index 7087d9856..9a6fd859e 100644
--- c/crates/ruff_linter/src/settings/types.rs
+++ w/crates/ruff_linter/src/settings/types.rs
@@ -34,6 +34,7 @@ pub enum PythonVersion {
     Py311,
     Py312,
     Py313,
+    Py314,
 }
 
 impl Default for PythonVersion {
@@ -55,6 +56,7 @@ impl TryFrom<ast::PythonVersion> for PythonVersion {
             ast::PythonVersion::PY311 => Ok(Self::Py311),
             ast::PythonVersion::PY312 => Ok(Self::Py312),
             ast::PythonVersion::PY313 => Ok(Self::Py313),
+            ast::PythonVersion::PY314 => Ok(Self::Py314),
             _ => Err(format!("unrecognized python version {value}")),
         }
     }
@@ -84,6 +86,7 @@ impl PythonVersion {
             Self::Py311 => (3, 11),
             Self::Py312 => (3, 12),
             Self::Py313 => (3, 13),
+            Self::Py314 => (3, 14),
         }
     }
 }
diff --git c/crates/ruff_python_ast/src/python_version.rs w/crates/ruff_python_ast/src/python_version.rs
index e5d1406de..5445e3265 100644
--- c/crates/ruff_python_ast/src/python_version.rs
+++ w/crates/ruff_python_ast/src/python_version.rs
@@ -30,6 +30,10 @@ impl PythonVersion {
         major: 3,
         minor: 13,
     };
+    pub const PY314: PythonVersion = PythonVersion {
+        major: 3,
+        minor: 14,
+    };
 
     pub fn iter() -> impl Iterator<Item = PythonVersion> {
         [
@@ -40,6 +44,7 @@ impl PythonVersion {
             PythonVersion::PY311,
             PythonVersion::PY312,
             PythonVersion::PY313,
+            PythonVersion::PY314,
         ]
         .into_iter()
     }
@@ -50,7 +55,7 @@ impl PythonVersion {
     }
 
     pub const fn latest() -> Self {
-        Self::PY313
+        Self::PY314
     }
 
     pub const fn as_tuple(self) -> (u8, u8) {
@@ -67,6 +72,10 @@ impl PythonVersion {
     pub fn supports_pep_701(self) -> bool {
         self >= Self::PY312
     }
+
+    pub fn defers_annotations(self) -> bool {
+        self >= Self::PY314
+    }
 }
 
 impl Default for PythonVersion {

[Daverball]

That seems right to me, but I haven't looked at the implementation details of PEP 695 to know whether or not there are any important edge cases we would want to encode into the semantic model in some way.

Either way this seems like a good start. Although I think it would be better if we added a semantic flag to encode this property, rather than having to pass around the version, so we can have a single method on the semantic model to tell us whether or not our annotations are deferred, i.e. have a future_or_deferred_annotations_or_stub take the place of future_annotations_or_stub, since in most cases we probably want to check both.