autodoc: Avoid updating __annotations__ with parent class members (#13935)

This commit ensures that the ``__annotations__`` dict of a class is
updated only with type comment-derived annotations for direct members;
the type comment-derived annotations for parent classes are added to
those parent classes own ``__annotations__`` dicts. The inherited
member annotations are still found by ``typing.get_type_hints``.

This commit also improves the efficiency of incorporating the
annotations found by the ``ModuleAnalyzer``.  Previously, each call to
``_load_object_by_name`` for a data member or attribute would result
in separately iterating over all attributes (including within
classes) found by ModuleAnalyzer for the containing module, and in
the case of classes, the containing modules of all parent classes.
For modules with many members this cost could likely be significant.
With this commit, at least for the purpose of updating
``__annotations__`` dicts, each module's attributes only processed a
single time in total.

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

Author: jbms

CHANGES.rst

@@ -126,6 +126,10 @@ Bugs fixed
 * #13929: Duplicate equation label warnings now have a new warning
   sub-type, ``ref.equation``.
   Patch by Jared Dillard.
+* #13935: autoclass: parent class members no longer considered
+  directly defined in certain cases, depending on autodoc processing
+  order.
+  Patch by Jeremy Maitin-Shepard.
 
 
 Testing

sphinx/ext/autodoc/_documenters.py

@@ -1546,20 +1546,6 @@ def can_document_member(
     ) -> bool:
         return isinstance(parent, ModuleDocumenter) and isattr
 
-    def update_annotations(self, parent: Any) -> None:
-        """Update __annotations__ to support type_comment and so on."""
-        annotations = dict(inspect.getannotations(parent))
-        parent.__annotations__ = annotations
-
-        try:
-            analyzer = ModuleAnalyzer.for_module(self.props.module_name)
-            analyzer.analyze()
-            for (classname, attrname), annotation in analyzer.annotations.items():
-                if not classname and attrname not in annotations:
-                    annotations[attrname] = annotation
-        except PycodeError:
-            pass
-
     def should_suppress_value_header(self) -> bool:
         if self.props._obj is UNINITIALIZED_ATTR:
             return True
@@ -1878,29 +1864,6 @@ def can_document_member(
             return True
         return not inspect.isroutine(member) and not isinstance(member, type)
 
-    def update_annotations(self, parent: Any) -> None:
-        """Update __annotations__ to support type_comment and so on."""
-        try:
-            annotations = dict(inspect.getannotations(parent))
-            parent.__annotations__ = annotations
-
-            for cls in inspect.getmro(parent):
-                try:
-                    module = safe_getattr(cls, '__module__')
-                    qualname = safe_getattr(cls, '__qualname__')
-
-                    analyzer = ModuleAnalyzer.for_module(module)
-                    analyzer.analyze()
-                    anns = analyzer.annotations
-                    for (classname, attrname), annotation in anns.items():
-                        if classname == qualname and attrname not in annotations:
-                            annotations[attrname] = annotation
-                except (AttributeError, PycodeError):
-                    pass
-        except (AttributeError, TypeError):
-            # Failed to set __annotations__ (built-in, extensions, etc.)
-            pass
-
     @property
     def _is_non_data_descriptor(self) -> bool:
         return not inspect.isattributedescriptor(self.props._obj)

sphinx/ext/autodoc/importer.py

@@ -12,8 +12,9 @@
 from importlib.machinery import EXTENSION_SUFFIXES
 from importlib.util import decode_source, find_spec, module_from_spec, spec_from_loader
 from pathlib import Path
-from types import SimpleNamespace
+from types import ModuleType, SimpleNamespace
 from typing import TYPE_CHECKING, NewType, TypeVar
+from weakref import WeakSet
 
 from sphinx.errors import PycodeError
 from sphinx.ext.autodoc._property_types import (
@@ -41,7 +42,6 @@
 if TYPE_CHECKING:
     from collections.abc import Sequence
     from importlib.machinery import ModuleSpec
-    from types import ModuleType
     from typing import Any, Protocol
 
     from sphinx.config import Config
@@ -660,20 +660,7 @@ def _load_object_by_name(
         )
     elif objtype == 'data':
         # Update __annotations__ to support type_comment and so on
-        annotations = dict(inspect.getannotations(parent))
-        parent.__annotations__ = annotations
-
-        try:
-            analyzer = ModuleAnalyzer.for_module(module_name)
-            analyzer.analyze()
-            for (
-                classname,
-                attrname,
-            ), annotation in analyzer.annotations.items():
-                if not classname and attrname not in annotations:
-                    annotations[attrname] = annotation
-        except PycodeError:
-            pass
+        _ensure_annotations_from_type_comments(parent)
 
         # obtain annotation
         annotations = get_type_hints(
@@ -729,27 +716,8 @@ def _load_object_by_name(
         elif inspect.isenumattribute(obj):
             obj = obj.value
         if parent:
-            # Update __annotations__ to support type_comment and so on.
-            try:
-                annotations = dict(inspect.getannotations(parent))
-                parent.__annotations__ = annotations
-
-                for cls in inspect.getmro(parent):
-                    try:
-                        module = safe_getattr(cls, '__module__')
-                        qualname = safe_getattr(cls, '__qualname__')
-
-                        analyzer = ModuleAnalyzer.for_module(module)
-                        analyzer.analyze()
-                        anns = analyzer.annotations
-                        for (classname, attrname), annotation in anns.items():
-                            if classname == qualname and attrname not in annotations:
-                                annotations[attrname] = annotation
-                    except (AttributeError, PycodeError):
-                        pass
-            except (AttributeError, TypeError):
-                # Failed to set __annotations__ (built-in, extensions, etc.)
-                pass
+            # Update __annotations__ to support type_comment and so on
+            _ensure_annotations_from_type_comments(parent)
 
         # obtain annotation
         annotations = get_type_hints(
@@ -964,3 +932,81 @@ def _resolve_name(
         return module_name, (*parents, base)
 
     return None
+
+
+_objects_with_type_comment_annotations: WeakSet[Any] = WeakSet()
+"""Cache of objects with annotations updated from type comments."""
+
+
+def _ensure_annotations_from_type_comments(obj: Any) -> None:
+    """Ensures `obj.__annotations__` includes type comment information.
+
+    Failures to assign to `__annotations__` are silently ignored.
+
+    If `obj` is a class type, this also ensures that type comment
+    information is incorporated into the `__annotations__` member of
+    all parent classes, if possible.
+
+    This mutates the `__annotations__` of existing imported objects,
+    in order to allow the existing `typing.get_type_hints` method to
+    take the modified annotations into account.
+
+    Modifying existing imported objects is unfortunate but avoids the
+    need to reimplement `typing.get_type_hints` in order to take into
+    account type comment information.
+
+    Note that this does not directly include type comment information
+    from parent classes, but `typing.get_type_hints` takes that into
+    account.
+    """
+    if obj in _objects_with_type_comment_annotations:
+        return
+    _objects_with_type_comment_annotations.add(obj)
+
+    if isinstance(obj, type):
+        for cls in inspect.getmro(obj):
+            modname = safe_getattr(cls, '__module__')
+            mod = sys.modules.get(modname)
+            if mod is not None:
+                _ensure_annotations_from_type_comments(mod)
+
+    elif isinstance(obj, ModuleType):
+        _update_module_annotations_from_type_comments(obj)
+
+
+def _update_module_annotations_from_type_comments(mod: ModuleType) -> None:
+    """Adds type comment annotations for a single module.
+
+    Both module-level and class-level annotations are added.
+    """
+    mod_annotations = dict(inspect.getannotations(mod))
+    mod.__annotations__ = mod_annotations
+
+    class_annotations: dict[str, dict[str, Any]] = {}
+
+    try:
+        analyzer = ModuleAnalyzer.for_module(mod.__name__)
+        analyzer.analyze()
+        anns = analyzer.annotations
+        for (classname, attrname), annotation in anns.items():
+            if not classname:
+                annotations = mod_annotations
+            else:
+                cls_annotations = class_annotations.get(classname)
+                if cls_annotations is None:
+                    try:
+                        cls = mod
+                        for part in classname.split('.'):
+                            cls = safe_getattr(cls, part)
+                        annotations = dict(inspect.getannotations(cls))
+                        # Ignore errors setting __annotations__
+                        with contextlib.suppress(TypeError, AttributeError):
+                            cls.__annotations__ = annotations
+                    except AttributeError:
+                        annotations = {}
+                    class_annotations[classname] = annotations
+                else:
+                    annotations = cls_annotations
+            annotations.setdefault(attrname, annotation)
+    except PycodeError:
+        pass

tests/test_ext_autodoc/test_ext_autodoc.py

@@ -976,13 +976,16 @@ def test_autodoc_special_members(app):
     if sys.version_info >= (3, 13, 0, 'alpha', 5):
         options['exclude-members'] = '__static_attributes__,__firstlineno__'
     if sys.version_info >= (3, 14, 0, 'alpha', 7):
-        ann_attr_name = '__annotations_cache__'
+        ann_attrs = (
+            '   .. py:attribute:: Class.__annotate_func__',
+            '   .. py:attribute:: Class.__annotations_cache__',
+        )
     else:
-        ann_attr_name = '__annotations__'
+        ann_attrs = ('   .. py:attribute:: Class.__annotations__',)
     actual = do_autodoc(app, 'class', 'target.Class', options)
     assert list(filter(lambda l: '::' in l, actual)) == [
         '.. py:class:: Class(arg)',
-        f'   .. py:attribute:: Class.{ann_attr_name}',
+        *ann_attrs,
         '   .. py:attribute:: Class.__dict__',
         '   .. py:method:: Class.__init__(arg)',
         '   .. py:attribute:: Class.__module__',
@@ -2287,6 +2290,11 @@ def test_autodoc_typed_instance_variables(app):
         'members': None,
         'undoc-members': None,
     }
+    # First compute autodoc of a `Derived` member to verify that it
+    # doesn't result in inherited members in
+    # `Derived.__annotations__`.
+    # https://github.com/sphinx-doc/sphinx/issues/13934
+    do_autodoc(app, 'attribute', 'target.typed_vars.Derived.attr2')
     actual = do_autodoc(app, 'module', 'target.typed_vars', options)
     assert list(actual) == [
         '',