gh-144361: Fix NameError when type parameter default refers to a forward name

Lib/test/test_typing.py

@@ -823,6 +823,54 @@ def test_pickle(self):
                 self.assertEqual(z.__bound__, typevar.__bound__)
                 self.assertEqual(z.__default__, typevar.__default__)
 
+    def test_forward_reference_default_typevar(self):
+        ns = run_code(
+            """
+            class A[T, U = ForwardName]:
+                pass
+            """
+        )
+        U, A = ns["A"].__type_params__[1], ns["A"]
+        with self.assertRaises(NameError):
+            U.__default__
+        result = A[int]
+        self.assertIsInstance(result.__args__[0], type)
+        self.assertIs(int, result.__args__[0])
+        self.assertIsInstance(result.__args__[1], ForwardRef)
+        self.assertEqual(result.__args__[1].__forward_arg__, 'ForwardName')
+
+    def test_forward_reference_default_typevartuple(self):
+        ns = run_code(
+            """
+            class A[T, *Ts = ForwardName]:
+                pass
+            """
+        )
+        Ts, A = ns["A"].__type_params__[1], ns["A"]
+        with self.assertRaises(NameError):
+            Ts.__default__
+        result = A[int]
+        self.assertIsInstance(result.__args__[0], type)
+        self.assertIs(int, result.__args__[0])
+        self.assertIsInstance(result.__args__[1], ForwardRef)
+        self.assertEqual(result.__args__[1].__forward_arg__, 'ForwardName')
+
+    def test_forward_reference_default_paramspec(self):
+        ns = run_code(
+            """
+            class A[T, **P = ForwardName]:
+                pass
+            """
+        )
+        P, A = ns["A"].__type_params__[1], ns["A"]
+        with self.assertRaises(NameError):
+            P.__default__
+        result = A[int]
+        self.assertIsInstance(result.__args__[0], type)
+        self.assertIs(int, result.__args__[0])
+        self.assertIsInstance(result.__args__[1], ForwardRef)
+        self.assertEqual(result.__args__[1].__forward_arg__, 'ForwardName')
+
 
 def template_replace(templates: list[str], replacements: dict[str, list[str]]) -> list[tuple[str]]:
     """Renders templates with possible combinations of replacements.

Lib/typing.py

@@ -1099,7 +1099,12 @@ def _typevartuple_prepare_subst(self, alias, args):
         raise TypeError(f"Too few arguments for {alias};"
                         f" actual {alen}, expected at least {plen-1}")
     if left == alen - right and self.has_default():
-        replacement = _unpack_args(self.__default__)
+        try:
+            default = self.__default__
+        except NameError:
+            default = annotationlib.call_evaluate_function(
+                self.evaluate_default, annotationlib.Format.FORWARDREF)
+        replacement = _unpack_args(default)
     else:
         replacement = args[left: alen - right]
 
@@ -1125,7 +1130,12 @@ def _paramspec_prepare_subst(self, alias, args):
     params = alias.__parameters__
     i = params.index(self)
     if i == len(args) and self.has_default():
-        args = (*args, self.__default__)
+        try:
+            default = self.__default__
+        except NameError:
+            default = annotationlib.call_evaluate_function(
+                self.evaluate_default, annotationlib.Format.FORWARDREF)
+        args = (*args, default)
     if i >= len(args):
         raise TypeError(f"Too few arguments for {alias}")
     # Special case where Z[[int, str, bool]] == Z[int, str, bool] in PEP 612.

Misc/NEWS.d/next/Library/2026-06-25-22-30-00.gh-issue-144361.lL9mN2.rst

@@ -0,0 +1,4 @@
+Fix :exc:`NameError` when a type parameter default (PEP 696/PEP 749)
+refers to a name defined later in the module. Now three call sites in
+:mod:`typing` fall back to :func:`annotationlib.call_evaluate_function`
+with :data:`~annotationlib.Format.FORWARDREF` when eager evaluation fails.

Objects/typevarobject.c

@@ -350,6 +350,24 @@ call_typing_func_object(const char *name, PyObject **args, size_t nargs)
     return result;
 }
 
+static PyObject *
+call_annotationlib_func_object(const char *name, PyObject **args, size_t nargs)
+{
+    PyObject *annotationlib = PyImport_ImportModule("annotationlib");
+    if (annotationlib == NULL) {
+        return NULL;
+    }
+    PyObject *func = PyObject_GetAttrString(annotationlib, name);
+    if (func == NULL) {
+        Py_DECREF(annotationlib);
+        return NULL;
+    }
+    PyObject *result = PyObject_Vectorcall(func, args, nargs, NULL);
+    Py_DECREF(func);
+    Py_DECREF(annotationlib);
+    return result;
+}
+
 static PyObject *
 type_check(PyObject *arg, const char *msg)
 {
@@ -803,8 +821,29 @@ typevar_typing_prepare_subst_impl(typevarobject *self, PyObject *alias,
         // If the TypeVar has a default, use it.
         PyObject *dflt = typevar_default((PyObject *)self, NULL);
         if (dflt == NULL) {
-            Py_DECREF(params);
-            return NULL;
+            if (!PyErr_ExceptionMatches(PyExc_NameError)) {
+                Py_DECREF(params);
+                return NULL;
+            }
+            PyErr_Clear();
+            if (self->evaluate_default == NULL) {
+                dflt = &_Py_NoDefaultStruct;
+            }
+            else {
+                PyObject *format = PyLong_FromLong(_Py_ANNOTATE_FORMAT_FORWARDREF);
+                if (format == NULL) {
+                    Py_DECREF(params);
+                    return NULL;
+                }
+                PyObject *call_args[2] = {self->evaluate_default, format};
+                dflt = call_annotationlib_func_object(
+                    "call_evaluate_function", call_args, 2);
+                Py_DECREF(format);
+                if (dflt == NULL) {
+                    Py_DECREF(params);
+                    return NULL;
+                }
+            }
         }
         if (dflt != &_Py_NoDefaultStruct) {
             PyObject *new_args = PyTuple_Pack(1, dflt);