Use the `FORWARDREF annotation format with inspect.signature()` (#13946)

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>

tests/roots/test-ext-autodoc/target/properties.py

@@ -1,3 +1,10 @@
+import sys
+
+TYPE_CHECKING = False
+if sys.version_info[:2] < (3, 14) or TYPE_CHECKING:
+    TypeCheckingOnlyName = int
+
+
 class Foo:
     """docstring"""
 
@@ -20,3 +27,7 @@ class Foo:
     def prop2_with_type_comment(cls):
         # type: () -> int
         """docstring"""
+
+    @property
+    def prop3_with_undefined_anotation(self) -> TypeCheckingOnlyName:
+        """docstring"""

tests/test_ext_autodoc/test_ext_autodoc_autoclass.py

@@ -6,6 +6,7 @@ source file translated by test_build.
 
 from __future__ import annotations
 
+import sys
 import typing
 
 import pytest
@@ -208,6 +209,11 @@ def test_decorators() -> None:
 
 
 def test_properties() -> None:
+    if sys.version_info[:2] >= (3, 14):
+        type_checking_only_name = 'TypeCheckingOnlyName'
+    else:
+        type_checking_only_name = 'int'
+
     options = {'members': None}
     actual = do_autodoc('class', 'target.properties.Foo', options=options)
     assert actual == [
@@ -247,6 +253,13 @@ def test_properties() -> None:
         '',
         '      docstring',
         '',
+        '',
+        '   .. py:property:: Foo.prop3_with_undefined_anotation',
+        '      :module: target.properties',
+        f'      :type: {type_checking_only_name}',
+        '',
+        '      docstring',
+        '',
     ]
 
 

tests/test_ext_autodoc/test_ext_autodoc_autoproperty.py

@@ -6,6 +6,8 @@ source file translated by test_build.
 
 from __future__ import annotations
 
+import sys
+
 import pytest
 
 from tests.test_ext_autodoc.autodoc_util import do_autodoc
@@ -87,3 +89,23 @@ def test_cached_properties_with_type_comment() -> None:
         '   :type: int',
         '',
     ]
+
+
+def test_property_with_undefined_annotation() -> None:
+    if sys.version_info[:2] >= (3, 14):
+        type_checking_only_name = 'TypeCheckingOnlyName'
+    else:
+        type_checking_only_name = 'int'
+
+    actual = do_autodoc(
+        'property', 'target.properties.Foo.prop3_with_undefined_anotation'
+    )
+    assert actual == [
+        '',
+        '.. py:property:: Foo.prop3_with_undefined_anotation',
+        '   :module: target.properties',
+        f'   :type: {type_checking_only_name}',
+        '',
+        '   docstring',
+        '',
+    ]

tests/test_util/test_util_inspect.py

@@ -106,6 +106,14 @@ def _decorator(f):
     return wrapper
 
 
+def forward_reference_in_args(x: Foo) -> None:  # type: ignore[name-defined] # noqa: F821
+    pass
+
+
+def forward_reference_in_return() -> Foo:  # type: ignore[name-defined] # noqa: F821
+    pass
+
+
 def test_TypeAliasForwardRef():
     alias = TypeAliasForwardRef('example')
     sig_str = stringify_annotation(alias, 'fully-qualified-except-typing')
@@ -172,6 +180,13 @@ def test_signature() -> None:
     sig = inspect.stringify_signature(inspect.signature(func))
     assert sig == '(a, b, c=1, d=2, *e, **f)'
 
+    # forward references
+    sig = inspect.stringify_signature(inspect.signature(forward_reference_in_args))
+    assert sig == '(x: Foo) -> None'
+
+    sig = inspect.stringify_signature(inspect.signature(forward_reference_in_return))
+    assert sig == '() -> Foo'
+
 
 def test_signature_partial() -> None:
     def fun(a, b, c=1, d=2):

tests/test_util/test_util_inspect_py314.py

@@ -0,0 +1,52 @@
+# noqa: I002 as 'from __future__ import annotations' prevents Python 3.14
+# forward references from causing issues, so we must skip it here.
+
+import pytest
+
+from sphinx.util import inspect
+from sphinx.util.typing import stringify_annotation
+
+try:
+    from annotationlib import ForwardRef  # type: ignore[import-not-found]
+except ImportError:
+    pytest.skip('Requires annotationlib (Python 3.14+).', allow_module_level=True)
+
+
+def forward_reference_in_args(x: Foo) -> None:  # type: ignore[name-defined] # noqa: F821
+    pass
+
+
+def forward_reference_in_return() -> Foo:  # type: ignore[name-defined] # noqa: F821
+    pass
+
+
+def test_signature_forwardref_in_args() -> None:
+    sig = inspect.signature(forward_reference_in_args)
+
+    assert sig.return_annotation is None
+
+    assert len(sig.parameters)
+    assert 'x' in sig.parameters
+    param = sig.parameters['x']
+
+    ann = param.annotation
+    assert isinstance(ann, ForwardRef)
+    assert ann.__arg__ == 'Foo'
+    assert ann.__forward_is_class__ is False
+    assert ann.__forward_module__ is None
+    assert ann.__owner__ is not None
+    assert stringify_annotation(ann) == 'Foo'
+
+
+def test_signature_forwardref_in_return() -> None:
+    sig = inspect.signature(forward_reference_in_return)
+
+    assert sig.parameters == {}
+
+    ann = sig.return_annotation
+    assert isinstance(ann, ForwardRef)
+    assert ann.__arg__ == 'Foo'
+    assert ann.__forward_is_class__ is False
+    assert ann.__forward_module__ is None
+    assert ann.__owner__ is not None
+    assert stringify_annotation(ann) == 'Foo'