Merge 3d0e7af into e285adc

sphinx_autodoc_typehints.py

@@ -257,15 +257,35 @@ def _is_dataclass(name: str, what: str, qualname: str) -> bool:
     return stringify_signature(signature).replace('\\', '\\\\'), None
 
 
+def _future_annotations_imported(obj):
+    if sys.version_info < (3, 8):
+        # Only Pythoh ≥ 3.8 supports PEP563.
+        return False
+    _annotations = getattr(inspect.getmodule(obj), "annotations", None)
+    if _annotations is None:
+        return False
+    # Make sure that annotations is imported from __future__
+    CO_FUTURE_ANNOTATIONS = 0x1000000  # defined in cpython/Lib/__future__.py
+    return _annotations.compiler_flag == CO_FUTURE_ANNOTATIONS
+
+
 def get_all_type_hints(obj, name):
     rv = {}
 
     try:
         rv = get_type_hints(obj)
-    except (AttributeError, TypeError, RecursionError):
+    except (AttributeError, TypeError, RecursionError) as exc:
         # Introspecting a slot wrapper will raise TypeError, and and some recursive type
         # definitions will cause a RecursionError (https://github.com/python/typing/issues/574).
-        pass
+
+        # If one is using PEP563 annotations, Python will raise a (e.g.,)
+        # TypeError("TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'")
+        # on 'str | None', therefore we accept TypeErrors with that error message
+        # if 'annotations' is imported from '__future__'.
+        if (isinstance(exc, TypeError)
+            and _future_annotations_imported(obj)
+                and "unsupported operand type" in str(exc)):
+            rv = obj.__annotations__
     except NameError as exc:
         logger.warning('Cannot resolve forward reference in type annotations of "%s": %s',
                        name, exc)

tests/roots/test-dummy/dummy_module_future_annotations.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+def function_with_py310_PEP563_annotations(self, x: bool, y: int, z: str | None = None) -> str:
+    """
+    Method docstring.
+
+    :param x: foo
+    :param y: bar
+    :param z: baz
+    """

tests/roots/test-dummy/future_annotations.rst

@@ -0,0 +1,4 @@
+Dummy Module
+============
+
+.. autofunction:: dummy_module_future_annotations.function_with_py310_PEP563_annotations

tests/test_sphinx_autodoc_typehints.py

@@ -6,6 +6,7 @@
 from typing import (
     IO, Any, AnyStr, Callable, Dict, Generic, Mapping, Match, NewType, Optional, Pattern, Tuple,
     Type, TypeVar, Union)
+from unittest.mock import patch
 
 import pytest
 import typing_extensions
@@ -85,6 +86,11 @@ class Metaclass(type):
     pytest.param(A.Inner, __name__, 'A.Inner', (), id='Inner')
 ])
 def test_parse_annotation(annotation, module, class_name, args):
+    if sys.version_info[:2] >= (3, 10):
+        if annotation == W:
+            module = "test_sphinx_autodoc_typehints"
+            class_name = "W"
+            args = ()
     assert get_annotation_module(annotation) == module
     assert get_annotation_class_name(annotation, module) == class_name
     assert get_annotation_args(annotation, module, class_name) == args
@@ -127,7 +133,10 @@ def test_parse_annotation(annotation, module, class_name, args):
                                     ':py:data:`~typing.Any`]',
                  marks=pytest.mark.skipif((3, 5, 0) <= sys.version_info[:3] <= (3, 5, 2),
                                           reason='Union erases the str on 3.5.0 -> 3.5.2')),
-    (Optional[str],                 ':py:data:`~typing.Optional`\\[:py:class:`str`]'),
+    (Optional[str],                 ':py:data:`~typing.Optional`\\' + (
+                                    '[:py:class:`str`]'
+                                    if sys.version_info[:2] < (3, 10) else
+                                    '[:py:class:`str`, :py:obj:`None`]')),
     (Optional[Union[str, bool]],    ':py:data:`~typing.Union`\\[:py:class:`str`, '
                                     ':py:class:`bool`, :py:obj:`None`]'),
     (Callable,                      ':py:data:`~typing.Callable`'),
@@ -151,7 +160,10 @@ def test_parse_annotation(annotation, module, class_name, args):
     (D,                             ':py:class:`~%s.D`' % __name__),
     (E,                             ':py:class:`~%s.E`' % __name__),
     (E[int],                        ':py:class:`~%s.E`\\[:py:class:`int`]' % __name__),
-    (W,                             ':py:func:`~typing.NewType`\\(:py:data:`~W`, :py:class:`str`)')
+    (W,                             ':py:func:`~typing.NewType`\\(:py:data:`~W`, :py:class:`str`)'
+                                    if sys.version_info[:2] < (3, 10) else
+                                    ':py:class:`~test_sphinx_autodoc_typehints.W`'
+     )
 ])
 def test_format_annotation(inv, annotation, expected_result):
     result = format_annotation(annotation)
@@ -223,17 +235,41 @@ def test_process_docstring_slot_wrapper():
     assert not lines
 
 
-@pytest.mark.parametrize('always_document_param_types', [True, False])
-@pytest.mark.sphinx('text', testroot='dummy')
-def test_sphinx_output(app, status, warning, always_document_param_types):
+def set_python_path():
     test_path = pathlib.Path(__file__).parent
 
     # Add test directory to sys.path to allow imports of dummy module.
     if str(test_path) not in sys.path:
         sys.path.insert(0, str(test_path))
 
+
+def maybe_fix_py310(expected_contents):
+    if sys.version_info[:2] >= (3, 10):
+        # In Python ≥ 3.10, the PEP563 can be interpreted as real annotations
+        # instead of strings.
+        for old, new in [
+                ("*str** | **None*", '"Optional"["str", "None"]'),
+                ("(*bool*)", '("bool")'),
+                ("(*int*)", '("int")'),
+                ("   str", '   "str"'),
+                ('"Optional"["str"]', '"Optional"["str", "None"]'),
+                ('"Optional"["Callable"[["int", "bytes"], "int"]]',
+                 '"Optional"["Callable"[["int", "bytes"], "int"], "None"]'),
+        ]:
+            expected_contents = expected_contents.replace(old, new)
+    return expected_contents
+
+
+@pytest.mark.parametrize('always_document_param_types', [True, False])
+@pytest.mark.sphinx('text', testroot='dummy')
+@patch('sphinx.writers.text.MAXWIDTH', 2000)
+def test_sphinx_output(app, status, warning, always_document_param_types):
+    set_python_path()
+
     app.config.always_document_param_types = always_document_param_types
     app.config.autodoc_mock_imports = ['mailbox']
+    if sys.version_info < (3, 8):
+        app.config.autodoc_mock_imports.append('dummy_module_future_annotations')
     app.build()
 
     assert 'build succeeded' in status.getvalue()  # Build succeeded
@@ -352,7 +388,7 @@ class InnerClass
               Return type:
                  "str"
 
-           property a_property
+           property a_property: str
 
               Property docstring
 
@@ -489,8 +525,7 @@ class dummy_module.ClassWithTypehintsNotInline(x=None)
               Method docstring.
 
               Parameters:
-                 **x** ("Optional"["Callable"[["int", "bytes"], "int"]]) --
-                 foo
+                 **x** ("Optional"["Callable"[["int", "bytes"], "int"]]) -- foo
 
               Return type:
                  "ClassWithTypehintsNotInline"
@@ -506,9 +541,7 @@ class dummy_module.DataClass(x)
 
            Class docstring.{undoc_params_0}
 
-           __init__(x)
-
-              Initialize self.  See help(type(self)) for accurate signature.{undoc_params_1}
+           __init__(x){undoc_params_1}
 
         @dummy_module.Decorator(func)
 
@@ -525,7 +558,43 @@ class dummy_module.DataClass(x)
               **x** ("Mailbox") -- function
         ''')
         expected_contents = expected_contents.format(**format_args).replace('–', '--')
-        assert text_contents == expected_contents
+        assert text_contents == maybe_fix_py310(expected_contents)
+
+
+@pytest.mark.skipif(sys.version_info < (3, 8),
+                    reason="Future annotations are not implemented in Python ≤ 3.8")
+@pytest.mark.sphinx('text', testroot='dummy')
+@patch('sphinx.writers.text.MAXWIDTH', 2000)
+def test_sphinx_output_future_annotations(app, status, warning):
+    set_python_path()
+
+    app.config.master_doc = "future_annotations"
+    app.build()
+
+    assert 'build succeeded' in status.getvalue()  # Build succeeded
+
+    text_path = pathlib.Path(app.srcdir) / '_build' / 'text' / 'future_annotations.txt'
+    with text_path.open('r') as f:
+        text_contents = f.read().replace('–', '--')
+        expected_contents = textwrap.dedent('''\
+        Dummy Module
+        ************
+
+        dummy_module_future_annotations.function_with_py310_PEP563_annotations(self, x, y, z=None)
+
+           Method docstring.
+
+           Parameters:
+              * **x** (*bool*) -- foo
+
+              * **y** (*int*) -- bar
+
+              * **z** (*str** | **None*) -- baz
+
+           Return type:
+              str
+        ''')
+        assert text_contents == maybe_fix_py310(expected_contents)
 
 
 def test_normalize_source_lines_async_def():