Introduce _AutodocAttrGetter type (#13971)

Author: AA-Turner

sphinx/ext/autodoc/__init__.py

@@ -35,7 +35,6 @@
     ModuleDocumenter,
     PropertyDocumenter,
     TypeAliasDocumenter,
-    autodoc_attrgetter,
 )
 from sphinx.ext.autodoc._event_listeners import between, cut_lines
 from sphinx.ext.autodoc._member_finder import ObjectMember, special_member_re
@@ -94,7 +93,6 @@
     'ObjectMember',
     'py_ext_sig_re',
     'special_member_re',
-    'autodoc_attrgetter',
     'Documenter',
 )
 

sphinx/ext/autodoc/_documenters.py

@@ -26,9 +26,9 @@
 from sphinx.util.typing import restify, stringify_annotation
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator, Sequence
     from types import ModuleType
-    from typing import Any, ClassVar, Final, Literal
+    from typing import Any, ClassVar, Final, Literal, NoReturn
 
     from sphinx.config import Config
     from sphinx.environment import BuildEnvironment, _CurrentDocument
@@ -43,7 +43,6 @@
         _TypeStatementProperties,
     )
     from sphinx.ext.autodoc.directive import DocumenterBridge
-    from sphinx.registry import SphinxComponentRegistry
     from sphinx.util.typing import OptionSpec, _RestifyMode
 
 logger = logging.getLogger('sphinx.ext.autodoc')
@@ -86,10 +85,6 @@ class Documenter:
         'noindex': bool_option,
     }
 
-    def get_attr(self, obj: Any, name: str, *defargs: Any) -> Any:
-        """getattr() override for types such as Zope interfaces."""
-        return autodoc_attrgetter(obj, name, *defargs, registry=self.env._registry)
-
     def __init__(
         self, directive: DocumenterBridge, name: str, indent: str = ''
     ) -> None:
@@ -99,6 +94,7 @@ def __init__(
         self._current_document: _CurrentDocument = directive.env.current_document
         self._events: EventManager = directive.env.events
         self.options: _AutoDocumenterOptions = directive.genopt
+        self.get_attr = directive.get_attr
         self.name = name
         self.indent: Final = indent
         self.module: ModuleType | None = None
@@ -618,12 +614,32 @@ class TypeAliasDocumenter(Documenter):
     }
 
 
-def autodoc_attrgetter(
-    obj: Any, name: str, *defargs: Any, registry: SphinxComponentRegistry
-) -> Any:
-    """Alternative getattr() for types"""
-    for typ, func in registry.autodoc_attrgetters.items():
-        if isinstance(obj, typ):
-            return func(obj, name, *defargs)
+class _AutodocAttrGetter:
+    """getattr() override for types such as Zope interfaces."""
+
+    _attr_getters: Sequence[tuple[type, Callable[[Any, str, Any], Any]]]
+
+    __slots__ = ('_attr_getters',)
+
+    def __init__(
+        self, attr_getters: dict[type, Callable[[Any, str, Any], Any]], /
+    ) -> None:
+        super().__setattr__('_attr_getters', tuple(attr_getters.items()))
+
+    def __call__(self, obj: Any, name: str, *defargs: Any) -> Any:
+        for typ, func in self._attr_getters:
+            if isinstance(obj, typ):
+                return func(obj, name, *defargs)
+
+        return safe_getattr(obj, name, *defargs)
+
+    def __repr__(self) -> str:
+        return f'_AutodocAttrGetter({dict(self._attr_getters)!r})'
+
+    def __setattr__(self, key: str, value: Any) -> NoReturn:
+        msg = f'{self.__class__.__name__} is immutable'
+        raise AttributeError(msg)
 
-    return safe_getattr(obj, name, *defargs)
+    def __delattr__(self, key: str) -> NoReturn:
+        msg = f'{self.__class__.__name__} is immutable'
+        raise AttributeError(msg)

sphinx/ext/autodoc/directive.py

@@ -10,6 +10,7 @@
     _AutoDocumenterOptions,
     _process_documenter_options,
 )
+from sphinx.ext.autodoc._documenters import _AutodocAttrGetter
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective, switch_source_input
 from sphinx.util.parsing import nested_parse_to_nodes
@@ -25,6 +26,7 @@
     from sphinx.environment import BuildEnvironment
     from sphinx.ext.autodoc import Documenter
     from sphinx.ext.autodoc._directive_options import Options
+    from sphinx.ext.autodoc.importer import _AttrGetter
 
 logger = logging.getLogger(__name__)
 
@@ -50,6 +52,7 @@ def __init__(
         options: _AutoDocumenterOptions,
         lineno: int,
         state: Any,
+        get_attr: _AttrGetter,
     ) -> None:
         self.env = env
         self._reporter = reporter
@@ -58,6 +61,7 @@ def __init__(
         self.record_dependencies: set[str] = set()
         self.result = StringList()
         self.state = state
+        self.get_attr = get_attr
 
 
 def process_documenter_options(
@@ -136,8 +140,9 @@ def run(self) -> list[Node]:
         documenter_options._tab_width = self.state.document.settings.tab_width
 
         # generate the output
+        get_attr = _AutodocAttrGetter(self.env._registry.autodoc_attrgetters)
         params = DocumenterBridge(
-            self.env, reporter, documenter_options, lineno, self.state
+            self.env, reporter, documenter_options, lineno, self.state, get_attr
         )
         documenter = doccls(params, self.arguments[0])
         documenter.generate(more_content=self.content)

sphinx/ext/autosummary/__init__.py

@@ -67,6 +67,7 @@
 from sphinx import addnodes
 from sphinx.errors import PycodeError
 from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
+from sphinx.ext.autodoc._documenters import _AutodocAttrGetter
 from sphinx.ext.autodoc._member_finder import _best_object_type_for_member
 from sphinx.ext.autodoc._sentinels import INSTANCE_ATTR
 from sphinx.ext.autodoc.directive import DocumenterBridge
@@ -220,8 +221,14 @@ class Autosummary(SphinxDirective):
 
     def run(self) -> list[Node]:
         opts = _AutoDocumenterOptions()
+        get_attr = _AutodocAttrGetter(self.env._registry.autodoc_attrgetters)
         self.bridge = DocumenterBridge(
-            self.env, self.state.document.reporter, opts, self.lineno, self.state
+            self.env,
+            self.state.document.reporter,
+            opts,
+            self.lineno,
+            self.state,
+            get_attr,
         )
 
         names = [

tests/test_ext_autodoc/autodoc_util.py

@@ -11,6 +11,7 @@
 # NEVER import those objects from sphinx.ext.autodoc directly
 from sphinx.ext.autodoc.directive import DocumenterBridge
 from sphinx.util.docutils import LoggingReporter
+from sphinx.util.inspect import safe_getattr
 
 if TYPE_CHECKING:
     from typing import Any
@@ -38,7 +39,9 @@ def do_autodoc(
     )
     docoptions = _AutoDocumenterOptions.from_directive_options(opts)
     state = Mock()
-    bridge = DocumenterBridge(app.env, LoggingReporter(''), docoptions, 1, state)
+    bridge = DocumenterBridge(
+        app.env, LoggingReporter(''), docoptions, 1, state, safe_getattr
+    )
     documenter = doccls(bridge, name)
     documenter.generate()
     return bridge.result

tests/test_ext_autodoc/test_ext_autodoc.py

@@ -20,7 +20,7 @@
     inherited_members_option,
 )
 from sphinx.ext.autodoc._docstrings import _get_docstring_lines
-from sphinx.ext.autodoc._documenters import Documenter, autodoc_attrgetter
+from sphinx.ext.autodoc._documenters import Documenter, _AutodocAttrGetter
 from sphinx.ext.autodoc._property_types import (
     _ClassDefProperties,
     _FunctionDefProperties,
@@ -72,6 +72,7 @@ def make_directive_bridge(env: BuildEnvironment) -> DocumenterBridge:
         options=options,
         lineno=0,
         state=Mock(),
+        get_attr=safe_getattr,
     )
 
     return directive
@@ -133,9 +134,7 @@ def parse(objtype, name):
 
 
 def format_sig(obj_type, name, obj, *, app, args=None, retann=None):
-    def get_attr(obj: Any, name: str, *defargs: Any) -> Any:
-        return autodoc_attrgetter(obj, name, *defargs, registry=app.registry)
-
+    get_attr = _AutodocAttrGetter(app.registry.autodoc_attrgetters)
     options = _AutoDocumenterOptions(
         synopsis='',
         platform='',
@@ -424,9 +423,7 @@ def func(x: int, y: int) -> int:  # type: ignore[empty-body]
         properties=frozenset(),
     )
 
-    def get_attr(obj: Any, name: str, *defargs: Any) -> Any:
-        return autodoc_attrgetter(obj, name, *defargs, registry=app.registry)
-
+    get_attr = _AutodocAttrGetter(app.registry.autodoc_attrgetters)
     options = _AutoDocumenterOptions(
         synopsis='',
         platform='',
@@ -561,36 +558,44 @@ def test_new_documenter(app):
     ]
 
 
+getattr_spy = []
+
+
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_attrgetter_using(app):
+    attrs = []
+
+    def _special_getattr(obj, attr_name, *defargs):
+        if attr_name in attrs:
+            getattr_spy.append((obj, attr_name))
+            return None
+        return getattr(obj, attr_name, *defargs)
+
+    app.add_autodoc_attrgetter(type, _special_getattr)
+
     directive = make_directive_bridge(app.env)
+    directive.get_attr = _AutodocAttrGetter(app.registry.autodoc_attrgetters)
     options = directive.genopt
     options.members = ALL
 
     options.inherited_members = inherited_members_option(False)
+    attrs[:] = ['meth']
     with catch_warnings(record=True):
-        _assert_getter_works(app, directive, 'class', 'target.Class', {'meth'})
+        _assert_getter_works(app, directive, 'class', 'target.Class', *attrs)
 
     options.inherited_members = inherited_members_option(True)
+    attrs[:] = ['inheritedmeth']
     with catch_warnings(record=True):
         _assert_getter_works(
-            app, directive, 'class', 'target.inheritance.Derived', {'inheritedmeth'}
+            app, directive, 'class', 'target.inheritance.Derived', *attrs
         )
 
 
-def _assert_getter_works(app, directive, objtype, name, attrs=(), **kw):
-    getattr_spy = set()
-
-    def _special_getattr(obj, attr_name, *defargs):
-        if attr_name in attrs:
-            getattr_spy.add((obj, attr_name))
-            return None
-        return getattr(obj, attr_name, *defargs)
-
-    app.add_autodoc_attrgetter(type, _special_getattr)
-
+def _assert_getter_works(app, directive, objtype, name, *attrs):
     getattr_spy.clear()
-    app.registry.documenters[objtype](directive, name).generate(**kw)
+
+    doccls = app.registry.documenters[objtype](directive, name)
+    doccls.generate()
 
     hooked_members = {s[1] for s in getattr_spy}
     documented_members = {s[1] for s in processed_signatures}