[5.2.x] Fixed #36903 -- Fixed further NameErrors when inspecting functions with deferred annotations.

Provide a wrapper for safe introspection of user functions on Python 3.14+.

Follow-up to 601914722956cc41f1f2c53972d669ddee6ffc04.
Backport of 56ed37e17e5b1a509aa68a0c797dcff34fcc1366 from main.

13 files changed, 137 insertions, 24 deletions

diff --git a/django/contrib/auth/__init__.py b/django/contrib/auth/__init__.py
index 84ca239558..e181cee6ae 100644
--- a/django/contrib/auth/__init__.py
+++ b/django/contrib/auth/__init__.py
@@ -1,4 +1,3 @@
-import inspect
 import re
 import warnings
 
@@ -8,6 +7,7 @@ from django.core.exceptions import ImproperlyConfigured, PermissionDenied
 from django.middleware.csrf import rotate_token
 from django.utils.crypto import constant_time_compare
 from django.utils.deprecation import RemovedInDjango61Warning
+from django.utils.inspect import signature
 from django.utils.module_loading import import_string
 from django.views.decorators.debug import sensitive_variables
 
@@ -42,7 +42,7 @@ def get_backends():
 
 def _get_compatible_backends(request, **credentials):
     for backend, backend_path in _get_backends(return_tuples=True):
-        backend_signature = inspect.signature(backend.authenticate)
+        backend_signature = signature(backend.authenticate)
         try:
             backend_signature.bind(request, **credentials)
         except TypeError:
diff --git a/django/core/checks/security/csrf.py b/django/core/checks/security/csrf.py
index d00f2259c6..51be377f48 100644
--- a/django/core/checks/security/csrf.py
+++ b/django/core/checks/security/csrf.py
@@ -1,6 +1,5 @@
-import inspect
-
 from django.conf import settings
+from django.utils.inspect import signature
 
 from .. import Error, Tags, Warning, register
 
@@ -57,7 +56,7 @@ def check_csrf_failure_view(app_configs, **kwargs):
         errors.append(Error(msg, id="security.E102"))
     else:
         try:
-            inspect.signature(view).bind(None, reason=None)
+            signature(view).bind(None, reason=None)
         except TypeError:
             msg = (
                 "The CSRF failure view '%s' does not take the correct number of "
diff --git a/django/core/checks/urls.py b/django/core/checks/urls.py
index aef2bfebb0..0980ecc3c9 100644
--- a/django/core/checks/urls.py
+++ b/django/core/checks/urls.py
@@ -1,8 +1,8 @@
-import inspect
 from collections import Counter
 
 from django.conf import settings
 from django.core.exceptions import ViewDoesNotExist
+from django.utils.inspect import signature
 
 from . import Error, Tags, Warning, register
 
@@ -142,10 +142,9 @@ def check_custom_error_handlers(app_configs, **kwargs):
             ).format(status_code=status_code, path=path)
             errors.append(Error(msg, hint=str(e), id="urls.E008"))
             continue
-        signature = inspect.signature(handler)
         args = [None] * num_parameters
         try:
-            signature.bind(*args)
+            signature(handler).bind(*args)
         except TypeError:
             msg = (
                 "The custom handler{status_code} view '{path}' does not "
diff --git a/django/db/models/expressions.py b/django/db/models/expressions.py
index 4284c84375..f830df82c2 100644
--- a/django/db/models/expressions.py
+++ b/django/db/models/expressions.py
@@ -1,7 +1,6 @@
 import copy
 import datetime
 import functools
-import inspect
 from collections import defaultdict
 from decimal import Decimal
 from enum import Enum
@@ -17,6 +16,7 @@ from django.db.models.query_utils import Q
 from django.utils.deconstruct import deconstructible
 from django.utils.functional import cached_property, classproperty
 from django.utils.hashable import make_hashable
+from django.utils.inspect import signature
 
 
 class SQLiteNumericMixin:
@@ -521,7 +521,7 @@ class Expression(BaseExpression, Combinable):
     @classproperty
     @functools.lru_cache(maxsize=128)
     def _constructor_signature(cls):
-        return inspect.signature(cls.__init__)
+        return signature(cls.__init__)
 
     @classmethod
     def _identity(cls, value):
diff --git a/django/template/base.py b/django/template/base.py
index 5a0941564d..80ccd0d423 100644
--- a/django/template/base.py
+++ b/django/template/base.py
@@ -58,7 +58,7 @@ from enum import Enum
 from django.template.context import BaseContext
 from django.utils.formats import localize
 from django.utils.html import conditional_escape
-from django.utils.inspect import lazy_annotations
+from django.utils.inspect import lazy_annotations, signature
 from django.utils.regex_helper import _lazy_re_compile
 from django.utils.safestring import SafeData, SafeString, mark_safe
 from django.utils.text import get_text_list, smart_split, unescape_string_literal
@@ -927,12 +927,12 @@ class Variable:
                             current = current()
                         except TypeError:
                             try:
-                                signature = inspect.signature(current)
+                                current_signature = signature(current)
                             except ValueError:  # No signature found.
                                 current = context.template.engine.string_if_invalid
                             else:
                                 try:
-                                    signature.bind()
+                                    current_signature.bind()
                                 except TypeError:  # Arguments *were* required.
                                     # Invalid method call.
                                     current = context.template.engine.string_if_invalid
diff --git a/django/utils/inspect.py b/django/utils/inspect.py
index 6f6bd7b7b9..b5d968062b 100644
--- a/django/utils/inspect.py
+++ b/django/utils/inspect.py
@@ -17,16 +17,7 @@ if PY314:
 
 @functools.lru_cache(maxsize=512)
 def _get_func_parameters(func, remove_first):
-    # As the annotations are not used in any case, inspect the signature with
-    # FORWARDREF to leave any deferred annotations unevaluated.
-    if PY314:
-        signature = inspect.signature(
-            func, annotation_format=annotationlib.Format.FORWARDREF
-        )
-    else:
-        signature = inspect.signature(func)
-
-    parameters = tuple(signature.parameters.values())
+    parameters = tuple(signature(func).parameters.values())
     if remove_first:
         parameters = parameters[1:]
     return parameters
@@ -120,3 +111,14 @@ def lazy_annotations():
             yield
         finally:
             inspect._signature_from_callable = original_helper
+
+
+def signature(obj):
+    """
+    A wrapper around inspect.signature that leaves deferred annotations
+    unevaluated on Python 3.14+, since they are not used in our case.
+    """
+    if PY314:
+        return inspect.signature(obj, annotation_format=annotationlib.Format.FORWARDREF)
+    else:
+        return inspect.signature(obj)
diff --git a/docs/releases/5.2.12.txt b/docs/releases/5.2.12.txt
index ac344f1d1d..1394308e56 100644
--- a/docs/releases/5.2.12.txt
+++ b/docs/releases/5.2.12.txt
@@ -9,4 +9,5 @@ Django 5.2.12 fixes one bug related to support for Python 3.14.
 Bugfixes
 ========
 
-* ...
+* Fixed :exc:`NameError` when inspecting functions making use of deferred
+  annotations in Python 3.14 (:ticket:`36903`).
diff --git a/tests/auth_tests/test_auth_backends.py b/tests/auth_tests/test_auth_backends.py
index 32fb092cf4..45c3de27da 100644
--- a/tests/auth_tests/test_auth_backends.py
+++ b/tests/auth_tests/test_auth_backends.py
@@ -1,5 +1,7 @@
 import sys
+import unittest
 from datetime import date
+from typing import TYPE_CHECKING, TypeAlias
 from unittest import mock
 from unittest.mock import patch
 
@@ -30,6 +32,7 @@ from django.test import (
     override_settings,
 )
 from django.urls import reverse
+from django.utils.version import PY314
 from django.views.debug import ExceptionReporter, technical_500_response
 from django.views.decorators.debug import sensitive_variables
 
@@ -41,6 +44,10 @@ from .models import (
     UUIDUser,
 )
 
+if TYPE_CHECKING:
+    AnnotatedUsername: TypeAlias = str
+    AnnotatedPassword: TypeAlias = str
+
 
 class FilteredExceptionReporter(ExceptionReporter):
     def get_traceback_frames(self):
@@ -1279,6 +1286,29 @@ class AuthenticateTests(TestCase):
     def test_skips_backends_with_decorated_method(self):
         self.assertEqual(authenticate(username="test", password="test"), self.user1)
 
+    @unittest.skipUnless(PY314, "Deferred annotations are Python 3.14+ only")
+    @override_settings(
+        AUTHENTICATION_BACKENDS=[
+            "auth_tests.test_auth_backends.AnnotatedBackend",
+        ],
+    )
+    def test_backend_uses_deferred_annotations(self):
+        class AnnotatedBackend:
+            invariant_user = self.user1
+
+            def authenticate(
+                self,
+                request: HttpRequest,
+                username: AnnotatedUsername,
+                password: AnnotatedPassword,
+            ) -> User | None:
+                return self.invariant_user
+
+        with unittest.mock.patch(
+            "django.contrib.auth.import_string", return_value=AnnotatedBackend
+        ):
+            self.assertEqual(authenticate(username="test", password="test"), self.user1)
+
 
 class ImproperlyConfiguredUserModelTest(TestCase):
     """
diff --git a/tests/check_framework/test_security.py b/tests/check_framework/test_security.py
index cb035a90a4..387a9808cb 100644
--- a/tests/check_framework/test_security.py
+++ b/tests/check_framework/test_security.py
@@ -1,11 +1,18 @@
+import unittest
+from typing import TYPE_CHECKING
+
 from django.conf import settings
 from django.core.checks.messages import Error, Warning
 from django.core.checks.security import base, csrf, sessions
 from django.core.management.utils import get_random_secret_key
 from django.test import SimpleTestCase
 from django.test.utils import override_settings
+from django.utils.version import PY314
 from django.views.generic import View
 
+if TYPE_CHECKING:
+    from django.http.request import HttpRequest
+
 
 class CheckSessionCookieSecureTest(SimpleTestCase):
     @override_settings(
@@ -611,6 +618,12 @@ def failure_view_with_invalid_signature():
     pass
 
 
+if PY314:
+
+    def failure_view_with_deferred_annotations(request: HttpRequest, reason: str):
+        pass
+
+
 good_class_based_csrf_failure_view = View.as_view()
 
 
@@ -651,6 +664,15 @@ class CSRFFailureViewTest(SimpleTestCase):
     def test_failure_view_valid_class_based(self):
         self.assertEqual(csrf.check_csrf_failure_view(None), [])
 
+    @unittest.skipUnless(PY314, "Deferred annotations are Python 3.14+ only")
+    @override_settings(
+        CSRF_FAILURE_VIEW=(
+            "check_framework.test_security.failure_view_with_deferred_annotations"
+        ),
+    )
+    def test_failure_view_valid_deferred_annotations(self):
+        self.assertEqual(csrf.check_csrf_failure_view(None), [])
+
 
 class CheckCrossOriginOpenerPolicyTest(SimpleTestCase):
     @override_settings(
diff --git a/tests/check_framework/test_urls.py b/tests/check_framework/test_urls.py
index a31c5fd856..8931bc75f4 100644
--- a/tests/check_framework/test_urls.py
+++ b/tests/check_framework/test_urls.py
@@ -1,3 +1,5 @@
+import unittest
+
 from django.conf import settings
 from django.core.checks.messages import Error, Warning
 from django.core.checks.urls import (
@@ -10,6 +12,7 @@ from django.core.checks.urls import (
 )
 from django.test import SimpleTestCase
 from django.test.utils import override_settings
+from django.utils.version import PY314
 
 
 class CheckUrlConfigTests(SimpleTestCase):
@@ -322,6 +325,14 @@ class CheckCustomErrorHandlersTests(SimpleTestCase):
         result = check_custom_error_handlers(None)
         self.assertEqual(result, [])
 
+    @unittest.skipUnless(PY314, "Deferred annotations are Python 3.14+ only")
+    @override_settings(
+        ROOT_URLCONF="check_framework.urls.good_error_handler_deferred_annotations",
+    )
+    def test_good_function_based_handlers_deferred_annotations(self):
+        result = check_custom_error_handlers(None)
+        self.assertEqual(result, [])
+
     @override_settings(
         ROOT_URLCONF="check_framework.urls.good_class_based_error_handlers",
     )
diff --git a/tests/check_framework/urls/good_error_handler_deferred_annotations.py b/tests/check_framework/urls/good_error_handler_deferred_annotations.py
new file mode 100644
index 0000000000..8b4ead5566
--- /dev/null
+++ b/tests/check_framework/urls/good_error_handler_deferred_annotations.py
@@ -0,0 +1,15 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from django.http.request import HttpRequest
+
+urlpatterns = []
+
+handler400 = __name__ + ".good_handler_deferred_annotations"
+handler403 = __name__ + ".good_handler_deferred_annotations"
+handler404 = __name__ + ".good_handler_deferred_annotations"
+handler500 = __name__ + ".good_handler_deferred_annotations"
+
+
+def good_handler_deferred_annotations(request: HttpRequest, exception=None):
+    pass
diff --git a/tests/expressions/tests.py b/tests/expressions/tests.py
index 9212b677a2..410ff4f28f 100644
--- a/tests/expressions/tests.py
+++ b/tests/expressions/tests.py
@@ -5,6 +5,7 @@ import uuid
 from collections import namedtuple
 from copy import deepcopy
 from decimal import Decimal
+from typing import TYPE_CHECKING, TypeAlias
 from unittest import mock
 
 from django.core.exceptions import FieldError
@@ -77,6 +78,7 @@ from django.test.utils import (
     register_lookup,
 )
 from django.utils.functional import SimpleLazyObject
+from django.utils.version import PY314
 
 from .models import (
     UUID,
@@ -94,6 +96,9 @@ from .models import (
     Time,
 )
 
+if TYPE_CHECKING:
+    AnnotatedKwarg: TypeAlias = str
+
 
 class BasicExpressionsTests(TestCase):
     @classmethod
@@ -1555,6 +1560,14 @@ class SimpleExpressionTests(SimpleTestCase):
         replaced = expression.replace_expressions({"replacement": Expression()})
         self.assertEqual(replaced.get_source_expressions(), [falsey])
 
+    @unittest.skipUnless(PY314, "Deferred annotations are Python 3.14+ only")
+    def test_expression_signature_uses_deferred_annotations(self):
+        class AnnotatedExpression(Expression):
+            def __init__(self, *args, my_kw: AnnotatedKwarg, **kwargs):
+                super().__init__(*args, **kwargs)
+
+        self.assertEqual(AnnotatedExpression(my_kw=""), AnnotatedExpression(my_kw=""))
+
 
 class ExpressionsNumericTests(TestCase):
     @classmethod
diff --git a/tests/template_tests/tests.py b/tests/template_tests/tests.py
index 7364c7ca64..da03c2d1b5 100644
--- a/tests/template_tests/tests.py
+++ b/tests/template_tests/tests.py
@@ -1,10 +1,16 @@
 import sys
+import unittest
+from typing import TYPE_CHECKING, TypeAlias
 
 from django.template import Context, Engine, TemplateDoesNotExist, TemplateSyntaxError
 from django.template.base import UNKNOWN_SOURCE
 from django.test import SimpleTestCase, override_settings
 from django.urls import NoReverseMatch
 from django.utils import translation
+from django.utils.version import PY314
+
+if TYPE_CHECKING:
+    AnnotatedKwarg: TypeAlias = str
 
 
 class TemplateTestMixin:
@@ -221,6 +227,21 @@ class TemplateTestMixin:
         template = self._engine().from_string("{{ description.count }}")
         self.assertEqual(template.render(Context({"description": "test"})), "")
 
+    @unittest.skipUnless(PY314, "Deferred annotations are Python 3.14+ only")
+    def test_callable_uses_deferred_annotations(self):
+        """
+        Missing required arguments are gracefully handled when a signature uses
+        deferred annotations.
+        """
+
+        class MyObject:
+            @staticmethod
+            def uses_deferred_annotations(value: AnnotatedKwarg):
+                return value
+
+        template = self._engine().from_string("{{ obj.uses_deferred_annotations }}")
+        self.assertEqual(template.render(Context({"obj": MyObject()})), "")
+
 
 class TemplateTests(TemplateTestMixin, SimpleTestCase):
     debug_engine = False