autodoc: Improve type hints for events (#14126)

Author: AA-Turner

doc/conf.py

@@ -188,7 +188,10 @@
     # sphinx.application.Sphinx.connect
     ('py:class', '_AutodocProcessDocstringListener'),
     # sphinx.application.Sphinx.connect
+    ('py:class', '_AutodocBeforeProcessSignatureListener'),
+    # sphinx.application.Sphinx.connect
     ('py:class', '_AutodocProcessSignatureListener'),
+    ('py:class', '_AutodocProcessBasesListener'),  # sphinx.application.Sphinx.connect
     ('py:class', '_AutodocSkipMemberListener'),  # sphinx.application.Sphinx.connect
     ('py:class', '_ConfigRebuild'),  # sphinx.application.Sphinx.add_config_value
     # sphinx.application.Sphinx.add_html_math_renderer

doc/usage/extensions/autodoc.rst

@@ -1378,7 +1378,7 @@ Docstring preprocessing
 
 autodoc provides the following additional events:
 
-.. event:: autodoc-process-docstring (app, what, name, obj, options, lines)
+.. event:: autodoc-process-docstring (app, obj_type, name, obj, options, lines)
 
    .. versionadded:: 0.4
 
@@ -1387,9 +1387,9 @@ autodoc provides the following additional events:
    can modify **in place** to change what Sphinx puts into the output.
 
    :param app: the Sphinx application object
-   :param what: the type of the object which the docstring belongs to (one of
-      ``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'method'``,
-      ``'attribute'``)
+   :param obj_type: the type of the object which the docstring belongs to (one of
+      ``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'decorator'``,
+      ``'method'``, ``'property'``, ``'attribute'``, ``'data'``, or ``'type'``)
    :param name: the fully qualified name of the object
    :param obj: the object itself
    :param options: the options given to the directive: an object with attributes
@@ -1409,7 +1409,7 @@ autodoc provides the following additional events:
    :param obj: the object itself
    :param bound_method: a boolean indicates an object is bound method or not
 
-.. event:: autodoc-process-signature (app, what, name, obj, options, signature, return_annotation)
+.. event:: autodoc-process-signature (app, obj_type, name, obj, options, signature, return_annotation)
 
    .. versionadded:: 0.5
 
@@ -1418,9 +1418,9 @@ autodoc provides the following additional events:
    what Sphinx puts into the output.
 
    :param app: the Sphinx application object
-   :param what: the type of the object which the docstring belongs to (one of
-      ``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'method'``,
-      ``'attribute'``)
+   :param obj_type: the type of the object which the docstring belongs to (one of
+      ``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'decorator'``,
+      ``'method'``, ``'property'``, ``'attribute'``, ``'data'``, or ``'type'``)
    :param name: the fully qualified name of the object
    :param obj: the object itself
    :param options: the options given to the directive: an object with attributes
@@ -1439,17 +1439,17 @@ needed docstring processing in event :event:`autodoc-process-docstring`:
 .. autofunction:: cut_lines
 .. autofunction:: between
 
-.. event:: autodoc-process-bases (app, name, obj, options, bases)
+.. event:: autodoc-process-bases (app, name, obj, _unused, bases)
 
    Emitted when autodoc has read and processed a class to determine the
    base-classes.  *bases* is a list of classes that the event handler can
    modify **in place** to change what Sphinx puts into the output.  It's
-   emitted only if ``show-inheritance`` option given.
+   emitted only if the ``show-inheritance`` option is given.
 
    :param app: the Sphinx application object
    :param name: the fully qualified name of the object
    :param obj: the object itself
-   :param options: the options given to the class directive
+   :param _unused: unused placeholder
    :param bases: the list of base classes signature. see above.
 
    .. versionadded:: 4.1
@@ -1465,7 +1465,7 @@ Skipping members
 autodoc allows the user to define a custom method for determining whether a
 member should be included in the documentation by using the following event:
 
-.. event:: autodoc-skip-member (app, what, name, obj, skip, options)
+.. event:: autodoc-skip-member (app, obj_type, name, obj, skip, options)
 
    .. versionadded:: 0.5
 
@@ -1479,9 +1479,9 @@ member should be included in the documentation by using the following event:
    autodoc and other enabled extensions.
 
    :param app: the Sphinx application object
-   :param what: the type of the object which the docstring belongs to (one of
-      ``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'method'``,
-      ``'attribute'``)
+   :param obj_type: the type of the object which the docstring belongs to (one of
+      ``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'decorator'``,
+      ``'method'``, ``'property'``, ``'attribute'``, ``'data'``, or ``'type'``)
    :param name: the fully qualified name of the object
    :param obj: the object itself
    :param skip: a boolean indicating if autodoc will skip this member if the

sphinx/application.py

@@ -53,6 +53,8 @@
     from sphinx.domains import Domain, Index
     from sphinx.environment.collectors import EnvironmentCollector
     from sphinx.ext.autodoc._event_listeners import (
+        _AutodocBeforeProcessSignatureListener,
+        _AutodocProcessBasesListener,
         _AutodocProcessDocstringListener,
         _AutodocProcessSignatureListener,
         _AutodocSkipMemberListener,
@@ -721,7 +723,7 @@ def connect(
     def connect(
         self,
         event: Literal['autodoc-before-process-signature'],
-        callback: Callable[[Sphinx, Any, bool], None],
+        callback: _AutodocBeforeProcessSignatureListener,
         priority: int = 500,
     ) -> int: ...
 
@@ -737,7 +739,7 @@ def connect(
     def connect(
         self,
         event: Literal['autodoc-process-bases'],
-        callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None],
+        callback: _AutodocProcessBasesListener,
         priority: int = 500,
     ) -> int: ...
 

sphinx/events.py

@@ -29,6 +29,8 @@
     from sphinx.domains import Domain
     from sphinx.environment import BuildEnvironment
     from sphinx.ext.autodoc._event_listeners import (
+        _AutodocBeforeProcessSignatureListener,
+        _AutodocProcessBasesListener,
         _AutodocProcessDocstringListener,
         _AutodocProcessSignatureListener,
         _AutodocSkipMemberListener,
@@ -293,7 +295,7 @@ def connect(
     def connect(
         self,
         name: Literal['autodoc-before-process-signature'],
-        callback: Callable[[Sphinx, Any, bool], None],
+        callback: _AutodocBeforeProcessSignatureListener,
         priority: int,
     ) -> int: ...
 
@@ -309,7 +311,7 @@ def connect(
     def connect(
         self,
         name: Literal['autodoc-process-bases'],
-        callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None],
+        callback: _AutodocProcessBasesListener,
         priority: int,
     ) -> int: ...
 

sphinx/ext/autodoc/_dynamic/_member_finder.py

@@ -485,16 +485,16 @@ def _filter_members(
         # should be skipped
         if events is not None:
             # let extensions preprocess docstrings
-            skip_user = events.emit_firstresult(
+            skip_member = events.emit_firstresult(
                 'autodoc-skip-member',
                 props.obj_type,
                 member_name,
                 member_obj,
                 not keep,
                 options,
             )
-            if skip_user is not None:
-                keep = not skip_user
+            if skip_member is not None:
+                keep = not skip_member
 
         if keep:
             # if is_attr is True, the member is documented as an attribute

sphinx/ext/autodoc/_event_listeners.py

@@ -6,22 +6,75 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Sequence
-    from typing import Any, TypeAlias
+    from collections.abc import Sequence
+    from typing import Any, Protocol
 
     from sphinx.application import Sphinx
     from sphinx.ext.autodoc._property_types import _AutodocObjType
 
-    _AutodocProcessDocstringListener: TypeAlias = Callable[
-        [Sphinx, _AutodocObjType, str, Any, dict[str, bool], list[str]], None
-    ]
-    _AutodocProcessSignatureListener: TypeAlias = Callable[  # NoQA: PYI047
-        [Sphinx, _AutodocObjType, str, Any, dict[str, bool], str | None, str | None],
-        tuple[str | None, str | None] | None,
-    ]
-    _AutodocSkipMemberListener: TypeAlias = Callable[  # NoQA: PYI047
-        [Sphinx, _AutodocObjType, str, Any, bool, dict[str, bool]], bool
-    ]
+    class _AutodocProcessDocstringListener(Protocol):
+        # parameter names are non-normative
+        def __call__(
+            self,
+            app: Sphinx,
+            obj_type: _AutodocObjType,
+            full_name: str,
+            obj: Any,
+            options: Any,
+            docstring_lines: list[str],
+            /,
+        ) -> None: ...
+
+    class _AutodocBeforeProcessSignatureListener(Protocol):  # NoQA: PYI046
+        # parameter names are non-normative
+        def __call__(
+            self,
+            app: Sphinx,
+            obj: Any,
+            is_bound_method: bool,
+            /,
+        ) -> None: ...
+
+    class _AutodocProcessSignatureListener(Protocol):  # NoQA: PYI046
+        # parameter names are non-normative
+        # returns: (args, retann) | None
+        def __call__(
+            self,
+            app: Sphinx,
+            obj_type: _AutodocObjType,
+            full_name: str,
+            obj: Any,
+            options: Any,
+            args: str | None,
+            retann: str | None,
+            /,
+        ) -> tuple[str | None, str | None] | None: ...
+
+    class _AutodocProcessBasesListener(Protocol):  # NoQA: PYI046
+        # parameter names are non-normative
+        def __call__(
+            self,
+            app: Sphinx,
+            full_name: str,
+            obj: Any,
+            _unused: None,  # previously: options
+            obj_bases: list[type],
+            /,
+        ) -> None: ...
+
+    class _AutodocSkipMemberListener(Protocol):  # NoQA: PYI046
+        # parameter names are non-normative
+        # returns: skip_member
+        def __call__(
+            self,
+            app: Sphinx,
+            obj_type: _AutodocObjType,
+            member_name: str,
+            member_obj: Any,
+            skip: bool,
+            options: Any,
+            /,
+        ) -> bool: ...
 
 
 def cut_lines(
@@ -51,7 +104,7 @@ def process(
         what_: _AutodocObjType,
         name: str,
         obj: Any,
-        options: dict[str, bool],
+        options: Any,
         lines: list[str],
     ) -> None:
         if what_unique and what_ not in what_unique:
@@ -90,7 +143,7 @@ def process(
         what_: _AutodocObjType,
         name: str,
         obj: Any,
-        options: dict[str, bool],
+        options: Any,
         lines: list[str],
     ) -> None:
         if what and what_ not in what:

sphinx/ext/napoleon/__init__.py

@@ -15,6 +15,7 @@
     from typing import Any
 
     from sphinx.config import _ConfigRebuild
+    from sphinx.ext.autodoc._property_types import _AutodocObjType
     from sphinx.util.typing import ExtensionMetadata
 
 
@@ -362,7 +363,12 @@ def _patch_python_domain() -> None:
 
 
 def _process_docstring(
-    app: Sphinx, what: str, name: str, obj: Any, options: Any, lines: list[str]
+    app: Sphinx,
+    what: _AutodocObjType,
+    name: str,
+    obj: Any,
+    options: Any,
+    lines: list[str],
 ) -> None:
     """Process the docstring for a given python object.
 
@@ -415,7 +421,7 @@ def _process_docstring(
 
 
 def _skip_member(
-    app: Sphinx, what: str, name: str, obj: Any, skip: bool, options: Any
+    app: Sphinx, what: _AutodocObjType, name: str, obj: Any, skip: bool, options: Any
 ) -> bool | None:
     """Determine if private and special class members are included in docs.
 

sphinx/ext/napoleon/docstring.py

@@ -16,9 +16,11 @@
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator
+    from typing import Literal
 
     from sphinx.application import Sphinx
     from sphinx.config import Config as SphinxConfig
+    from sphinx.ext.autodoc._property_types import _AutodocObjType
 
 logger = logging.getLogger(__name__)
 
@@ -328,10 +330,10 @@ def __init__(
         docstring: str | list[str],
         config: SphinxConfig | None = None,
         app: Sphinx | None = None,
-        what: str = '',
+        what: _AutodocObjType | Literal['object'] = 'object',
         name: str = '',
-        obj: Any = None,
-        options: Any = None,
+        obj: Any | None = None,
+        options: Any | None = None,
     ) -> None:
         self._app = app
         if config:
@@ -343,7 +345,7 @@ def __init__(
 
             self._config = Config()  # type: ignore[assignment]
 
-        if not what:
+        if what == 'object':
             if inspect.isclass(obj):
                 what = 'class'
             elif inspect.ismodule(obj):
@@ -353,7 +355,7 @@ def __init__(
             else:
                 what = 'object'
 
-        self._what = what
+        self._what: _AutodocObjType | Literal['object'] = what
         self._name = name
         self._obj = obj
         self._opt = options
@@ -1206,10 +1208,10 @@ def __init__(
         docstring: str | list[str],
         config: SphinxConfig | None = None,
         app: Sphinx | None = None,
-        what: str = '',
+        what: _AutodocObjType | Literal['object'] = 'object',
         name: str = '',
-        obj: Any = None,
-        options: Any = None,
+        obj: Any | None = None,
+        options: Any | None = None,
     ) -> None:
         self._directive_sections = ['.. index::']
         super().__init__(docstring, config, app, what, name, obj, options)

tests/test_ext_autodoc/test_ext_autodoc_autoclass.py

@@ -318,7 +318,7 @@ def test_show_inheritance_for_decendants_of_generic_type() -> None:
 
 
 def _autodoc_process_bases(
-    app: Sphinx, name: str, obj: Any, options: dict[str, bool], bases: list[type]
+    app: Sphinx, name: str, obj: Any, options: Any, bases: list[type]
 ) -> None:
     assert name == 'target.classes.Quux'
     assert obj.__module__ == 'target.classes'

tests/test_ext_napoleon/test_ext_napoleon.py

@@ -16,6 +16,8 @@
     from collections.abc import Callable
     from typing import ParamSpec, TypeVar
 
+    from sphinx.ext.autodoc._property_types import _AutodocObjType
+
     _P = ParamSpec('_P')
     _R = TypeVar('_R')
 
@@ -151,7 +153,7 @@ def test_add_config_values(self) -> None:
 class TestSkipMember:
     def assert_skip(
         self,
-        what: str,
+        what: _AutodocObjType,
         member: str,
         obj: object,
         expect_default_skip: bool,