Use a new _best_object_type_for_member() function (#13961)

AA-Turner · web-flow · commit f1941789674e · 2025-10-17T01:56:54.000+01:00
diff --git a/doc/development/tutorials/examples/autodoc_intenum.py b/doc/development/tutorials/examples/autodoc_intenum.py
@@ -11,19 +11,20 @@
     from docutils.statemachine import StringList
 
     from sphinx.application import Sphinx
+    from sphinx.ext.autodoc import Documenter
     from sphinx.util.typing import ExtensionMetadata
 
 
 class IntEnumDocumenter(ClassDocumenter):
     objtype = 'intenum'
     directivetype = ClassDocumenter.objtype
-    priority = 10 + ClassDocumenter.priority
+    priority = 25
     option_spec = dict(ClassDocumenter.option_spec)
     option_spec['hex'] = bool_option
 
     @classmethod
     def can_document_member(
-        cls, member: Any, membername: str, isattr: bool, parent: Any
+        cls, member: Any, membername: str, isattr: bool, parent: Documenter
     ) -> bool:
         try:
             return issubclass(member, IntEnum)
diff --git a/sphinx/ext/autodoc/_documenters.py b/sphinx/ext/autodoc/_documenters.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import operator
 from typing import TYPE_CHECKING, NewType, TypeVar
 
 from docutils.statemachine import StringList
@@ -80,8 +81,6 @@ class Documenter:
     objtype: ClassVar = 'object'
     #: indentation by which to indent the directive content
     content_indent: ClassVar = '   '
-    #: priority if multiple documenters return True from can_document_member
-    priority: ClassVar = 0
     #: order if autodoc_member_order is set to 'groupwise'
     member_order: ClassVar = 0
     #: true if the generated content may contain titles
@@ -100,14 +99,6 @@ 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)
 
-    @classmethod
-    def can_document_member(
-        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
-    ) -> bool:
-        """Called to see if a member can be documented by this Documenter."""
-        msg = 'must be implemented in subclasses'
-        raise NotImplementedError(msg)
-
     def __init__(
         self, directive: DocumenterBridge, name: str, indent: str = ''
     ) -> None:
@@ -728,18 +719,16 @@ def _gather_members(
         member_documenters: list[tuple[Documenter, bool]] = []
         for member_name, member, is_attr in filtered_members:
             # prefer the documenter with the highest priority
-            doccls = max(
-                (
-                    cls
-                    for cls in registry.documenters.values()
-                    if cls.can_document_member(member, member_name, is_attr, self)
-                ),
-                key=lambda cls: cls.priority,
-                default=None,
+            obj_type = _best_object_type_for_member(
+                member=member,
+                member_name=member_name,
+                is_attr=is_attr,
+                parent_documenter=self,
             )
-            if doccls is None:
+            if not obj_type:
                 # don't know how to document this member
                 continue
+            doccls = registry.documenters[obj_type]
             # give explicitly separated module name, so that members
             # of inner classes can be documented
             module_prefix = f'{props.module_name}::'
@@ -793,13 +782,6 @@ class ModuleDocumenter(Documenter):
         'noindex': bool_option,
     }
 
-    @classmethod
-    def can_document_member(
-        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
-    ) -> bool:
-        # don't document submodules automatically
-        return False
-
 
 class FunctionDocumenter(Documenter):
     """Specialized Documenter subclass for functions."""
@@ -809,17 +791,6 @@ class FunctionDocumenter(Documenter):
     objtype = 'function'
     member_order = 30
 
-    @classmethod
-    def can_document_member(
-        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
-    ) -> bool:
-        # supports functions, builtins and bound methods exported at the module level
-        return (
-            inspect.isfunction(member)
-            or inspect.isbuiltin(member)
-            or (inspect.isroutine(member) and isinstance(parent, ModuleDocumenter))
-        )
-
 
 class DecoratorDocumenter(FunctionDocumenter):
     """Specialized Documenter subclass for decorator functions."""
@@ -828,9 +799,6 @@ class DecoratorDocumenter(FunctionDocumenter):
 
     objtype = 'decorator'
 
-    # must be lower than FunctionDocumenter
-    priority = FunctionDocumenter.priority - 1
-
 
 class ClassDocumenter(Documenter):
     """Specialized Documenter subclass for classes."""
@@ -854,19 +822,6 @@ class ClassDocumenter(Documenter):
         'noindex': bool_option,
     }
 
-    # Must be higher than FunctionDocumenter, ClassDocumenter, and
-    # AttributeDocumenter as NewType can be an attribute and is a class
-    # after Python 3.10.
-    priority = 15
-
-    @classmethod
-    def can_document_member(
-        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
-    ) -> bool:
-        return isinstance(member, type) or (
-            isattr and isinstance(member, (NewType, TypeVar))
-        )
-
     def get_canonical_fullname(self) -> str | None:
         __modname__ = safe_getattr(
             self.props._obj, '__module__', self.props.module_name
@@ -892,25 +847,6 @@ class ExceptionDocumenter(ClassDocumenter):
     objtype = 'exception'
     member_order = 10
 
-    # needs a higher priority than ClassDocumenter
-    priority = ClassDocumenter.priority + 5
-
-    @classmethod
-    def can_document_member(
-        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
-    ) -> bool:
-        try:
-            return isinstance(member, type) and issubclass(member, BaseException)
-        except TypeError as exc:
-            # It's possible for a member to be considered a type, but fail
-            # issubclass checks due to not being a class. For example:
-            # https://github.com/sphinx-doc/sphinx/issues/11654#issuecomment-1696790436
-            msg = (
-                f'{cls.__name__} failed to discern if member {member} with'
-                f' membername {membername} is a BaseException subclass.'
-            )
-            raise ValueError(msg) from exc
-
 
 class DataDocumenter(Documenter):
     """Specialized Documenter subclass for data items."""
@@ -921,17 +857,10 @@ class DataDocumenter(Documenter):
 
     objtype = 'data'
     member_order = 40
-    priority = -10
     option_spec: ClassVar[OptionSpec] = dict(Documenter.option_spec)
     option_spec['annotation'] = annotation_option
     option_spec['no-value'] = bool_option
 
-    @classmethod
-    def can_document_member(
-        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
-    ) -> bool:
-        return isinstance(parent, ModuleDocumenter) and isattr
-
 
 class MethodDocumenter(Documenter):
     """Specialized Documenter subclass for methods (normal, static and class)."""
@@ -941,13 +870,6 @@ class MethodDocumenter(Documenter):
     objtype = 'method'
     directivetype = 'method'
     member_order = 50
-    priority = 1  # must be more than FunctionDocumenter
-
-    @classmethod
-    def can_document_member(
-        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
-    ) -> bool:
-        return inspect.isroutine(member) and not isinstance(parent, ModuleDocumenter)
 
 
 class AttributeDocumenter(Documenter):
@@ -961,26 +883,12 @@ class AttributeDocumenter(Documenter):
     option_spec['annotation'] = annotation_option
     option_spec['no-value'] = bool_option
 
-    # must be higher than the MethodDocumenter, else it will recognize
-    # some non-data descriptors as methods
-    priority = 10
-
     @staticmethod
     def is_function_or_method(obj: Any) -> bool:
         return (
             inspect.isfunction(obj) or inspect.isbuiltin(obj) or inspect.ismethod(obj)
         )
 
-    @classmethod
-    def can_document_member(
-        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
-    ) -> bool:
-        if isinstance(parent, ModuleDocumenter):
-            return False
-        if inspect.isattributedescriptor(member):
-            return True
-        return not inspect.isroutine(member) and not isinstance(member, type)
-
 
 class PropertyDocumenter(Documenter):
     """Specialized Documenter subclass for properties."""
@@ -990,26 +898,6 @@ class PropertyDocumenter(Documenter):
     objtype = 'property'
     member_order = 60
 
-    # before AttributeDocumenter
-    priority = AttributeDocumenter.priority + 1
-
-    @classmethod
-    def can_document_member(
-        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
-    ) -> bool:
-        if isinstance(parent, ClassDocumenter):
-            if inspect.isproperty(member):
-                return True
-            else:
-                # See FakeDirective &c in autosummary, parent might not be a
-                # 'proper' Documenter.
-                obj = parent.props._obj if hasattr(parent, 'props') else None
-                __dict__ = safe_getattr(obj, '__dict__', {})
-                obj = __dict__.get(membername)
-                return isinstance(obj, classmethod) and inspect.isproperty(obj.__func__)
-        else:
-            return False
-
 
 class TypeAliasDocumenter(Documenter):
     """Specialized Documenter subclass for type aliases."""
@@ -1025,12 +913,6 @@ class TypeAliasDocumenter(Documenter):
         'no-value': bool_option,
     }
 
-    @classmethod
-    def can_document_member(
-        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
-    ) -> bool:
-        return isinstance(member, AnyTypeAliasType)
-
 
 class DocstringSignatureMixin:
     """Retained for compatibility."""
@@ -1078,3 +960,83 @@ def _document_members(
             real_modname=real_modname,
             check_module=members_check_module and not is_attr,
         )
+
+
+def _best_object_type_for_member(
+    member: Any,
+    member_name: str,
+    is_attr: bool,
+    parent_documenter: Documenter,
+) -> str | None:
+    """Return the best object type that supports documenting *member*."""
+    filtered = []
+
+    # Don't document submodules automatically: 'module' is never returned.
+
+    try:
+        if isinstance(member, type) and issubclass(member, BaseException):
+            # priority must be higher than 'class'
+            filtered.append((20, 'exception'))
+    except TypeError as exc:
+        # It's possible for a member to be considered a type, but fail
+        # issubclass checks due to not being a class. For example:
+        # https://github.com/sphinx-doc/sphinx/issues/11654#issuecomment-1696790436
+        msg = f'Failed to discern if member {member} is a BaseException subclass.'
+        raise ValueError(msg) from exc
+
+    if isinstance(member, type) or (is_attr and isinstance(member, (NewType, TypeVar))):
+        # priority must be higher than 'function', 'class', and 'attribute'
+        # as NewType can be an attribute and is a class after Python 3.10.
+        filtered.append((15, 'class'))
+
+    if isinstance(parent_documenter, ClassDocumenter):
+        if inspect.isproperty(member):
+            # priority must be higher than 'attribute'
+            filtered.append((11, 'property'))
+
+        # Support for class properties. Note: these only work on Python 3.9.
+        elif hasattr(parent_documenter, 'props'):
+            # See FakeDirective &c in autosummary, parent might not be a
+            # 'proper' Documenter.
+            __dict__ = safe_getattr(parent_documenter.props._obj, '__dict__', {})
+            obj = __dict__.get(member_name)
+            if isinstance(obj, classmethod) and inspect.isproperty(obj.__func__):
+                # priority must be higher than 'attribute'
+                filtered.append((11, 'property'))
+
+    if not isinstance(parent_documenter, ModuleDocumenter):
+        if inspect.isattributedescriptor(member) or not (
+            inspect.isroutine(member) or isinstance(member, type)
+        ):
+            # priority must be higher than 'method', else it will recognise
+            # some non-data descriptors as methods
+            filtered.append((10, 'attribute'))
+
+    if inspect.isroutine(member) and not isinstance(
+        parent_documenter, ModuleDocumenter
+    ):
+        # priority must be higher than 'function'
+        filtered.append((1, 'method'))
+
+    if (
+        inspect.isfunction(member)
+        or inspect.isbuiltin(member)
+        or (
+            inspect.isroutine(member)
+            and isinstance(parent_documenter, ModuleDocumenter)
+        )
+    ):
+        # supports functions, builtins and bound methods exported
+        # at the module level
+        filtered.extend(((0, 'function'), (-1, 'decorator')))
+
+    if isinstance(member, AnyTypeAliasType):
+        filtered.append((0, 'type'))
+
+    if isinstance(parent_documenter, ModuleDocumenter) and is_attr:
+        filtered.append((-10, 'data'))
+
+    if filtered:
+        # return the highest priority object type
+        return max(filtered, key=operator.itemgetter(0))[1]
+    return None
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
@@ -70,6 +70,7 @@
 from sphinx.environment import BuildEnvironment
 from sphinx.errors import PycodeError
 from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
+from sphinx.ext.autodoc._documenters import _best_object_type_for_member
 from sphinx.ext.autodoc._sentinels import INSTANCE_ATTR
 from sphinx.ext.autodoc.directive import DocumenterBridge
 from sphinx.ext.autodoc.importer import _format_signatures, import_module
@@ -206,7 +207,6 @@ def _get_documenter(
     from sphinx.ext.autodoc import DataDocumenter, ModuleDocumenter
 
     if inspect.ismodule(obj):
-        # ModuleDocumenter.can_document_member always returns False
         return ModuleDocumenter
 
     # Construct a fake documenter for *parent*
@@ -221,14 +221,11 @@ def _get_documenter(
         parent_doc = parent_doc_cls(FakeDirective(), '')
 
     # Get the correct documenter class for *obj*
-    classes = [
-        cls
-        for cls in registry.documenters.values()
-        if cls.can_document_member(obj, '', False, parent_doc)
-    ]
-    if classes:
-        classes.sort(key=lambda cls: cls.priority)
-        return classes[-1]
+    obj_type = _best_object_type_for_member(
+        member=obj, member_name='', is_attr=False, parent_documenter=parent_doc
+    )
+    if obj_type:
+        return registry.documenters[obj_type]
     else:
         return DataDocumenter
 
diff --git a/tests/test_ext_autodoc/test_ext_autodoc.py b/tests/test_ext_autodoc/test_ext_autodoc.py
