diff --git a/AUTHORS.rst b/AUTHORS.rst index f5a692a5302..04995b3e120 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -102,6 +102,7 @@ Contributors * Pauli Virtanen -- autodoc improvements, autosummary extension * Rafael Fontenelle -- internationalisation * \A. Rafey Khan -- improved intersphinx typing +* Rui Pinheiro -- Python 3.14 forward references support * Roland Meister -- epub builder * Sebastian Wiesner -- image handling, distutils support * Slawek Figiel -- additional warning suppression diff --git a/CHANGES.rst b/CHANGES.rst index e5601caba3c..2c29abfada0 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -174,6 +174,9 @@ Bugs fixed * #12797: Fix ``Some type variables (...) are not listed in Generic[...]`` TypeError when inheriting from both Generic and autodoc mocked class. Patch by Ikor Jefocur and Daniel Sperber. +* #13945: autodoc: Fix handling of undefined names in annotations by using + the ``FORWARDREF`` :mod:`annotationlib` format. + Patch by Rui Pinheiro and Adam Turner. Testing diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py index 546a292f838..cc70f785819 100644 --- a/sphinx/util/inspect.py +++ b/sphinx/util/inspect.py @@ -710,6 +710,16 @@ def _should_unwrap(subject: _SignatureType) -> bool: ) +# Python 3.14 uses deferred evaluation of annotations by default. +# Using annotationlib's FORWARDREF format gives us more robust handling +# of forward references in type annotations. +signature_kwds: dict[str, Any] = {} +if sys.version_info[:2] >= (3, 14): + import annotationlib # type: ignore[import-not-found] + + signature_kwds['annotation_format'] = annotationlib.Format.FORWARDREF + + def signature( subject: _SignatureType, bound_method: bool = False, @@ -726,12 +736,16 @@ def signature( try: if _should_unwrap(subject): - signature = inspect.signature(subject) # type: ignore[arg-type] + signature = inspect.signature(subject, **signature_kwds) # type: ignore[arg-type] else: - signature = inspect.signature(subject, follow_wrapped=True) # type: ignore[arg-type] + signature = inspect.signature( + subject, # type: ignore[arg-type] + follow_wrapped=True, + **signature_kwds, + ) except ValueError: # follow built-in wrappers up (ex. functools.lru_cache) - signature = inspect.signature(subject) # type: ignore[arg-type] + signature = inspect.signature(subject, **signature_kwds) # type: ignore[arg-type] parameters = list(signature.parameters.values()) return_annotation = signature.return_annotation diff --git a/tests/roots/test-ext-autodoc/target/properties.py b/tests/roots/test-ext-autodoc/target/properties.py index 84d1c2a1a19..071bf182b55 100644 --- a/tests/roots/test-ext-autodoc/target/properties.py +++ b/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 @@ def prop1_with_type_comment(self): def prop2_with_type_comment(cls): # type: () -> int """docstring""" + + @property + def prop3_with_undefined_anotation(self) -> TypeCheckingOnlyName: + """docstring""" diff --git a/tests/test_ext_autodoc/test_ext_autodoc_autoclass.py b/tests/test_ext_autodoc/test_ext_autodoc_autoclass.py index b479094c6be..acecfce0e53 100644 --- a/tests/test_ext_autodoc/test_ext_autodoc_autoclass.py +++ b/tests/test_ext_autodoc/test_ext_autodoc_autoclass.py @@ -6,6 +6,7 @@ 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', + '', ] diff --git a/tests/test_ext_autodoc/test_ext_autodoc_autoproperty.py b/tests/test_ext_autodoc/test_ext_autodoc_autoproperty.py index 7fdd57ad7f8..8042a1ff310 100644 --- a/tests/test_ext_autodoc/test_ext_autodoc_autoproperty.py +++ b/tests/test_ext_autodoc/test_ext_autodoc_autoproperty.py @@ -6,6 +6,8 @@ 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', + '', + ] diff --git a/tests/test_util/test_util_inspect.py b/tests/test_util/test_util_inspect.py index 1c864ba4544..577ae6f3f8a 100644 --- a/tests/test_util/test_util_inspect.py +++ b/tests/test_util/test_util_inspect.py @@ -106,6 +106,14 @@ def wrapper(): 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 func(a, b, c=1, d=2, *e, **f): 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): diff --git a/tests/test_util/test_util_inspect_py314.py b/tests/test_util/test_util_inspect_py314.py new file mode 100644 index 00000000000..dbda82a53b2 --- /dev/null +++ b/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'