Sphinx 8.1.3__py3-none-any.whl → 8.2.0rc1__py3-none-any.whl

sphinx/ext/autosummary/__init__.py

@@ -11,7 +11,7 @@ autosummary directive
 The autosummary directive has the form::
 
     .. autosummary::
-       :nosignatures:
+       :signatures: none
        :toctree: generated/
 
        module.function_1
@@ -51,14 +51,13 @@ from __future__ import annotations
 import functools
 import inspect
 import operator
-import os
 import posixpath
 import re
 import sys
 from inspect import Parameter
-from os import path
+from pathlib import Path
 from types import ModuleType
-from typing import TYPE_CHECKING, Any, ClassVar, cast
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -70,7 +69,7 @@ from sphinx import addnodes
 from sphinx.config import Config
 from sphinx.environment import BuildEnvironment
 from sphinx.errors import PycodeError
-from sphinx.ext.autodoc import INSTANCEATTR, Documenter, Options
+from sphinx.ext.autodoc import INSTANCEATTR, Options
 from sphinx.ext.autodoc.directive import DocumenterBridge
 from sphinx.ext.autodoc.importer import import_module
 from sphinx.ext.autodoc.mock import mock
@@ -92,10 +91,12 @@ from sphinx.util.parsing import nested_parse_to_nodes
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
+    from typing import Any, ClassVar
 
     from docutils.nodes import Node, system_message
 
     from sphinx.application import Sphinx
+    from sphinx.ext.autodoc import Documenter
     from sphinx.extension import Extension
     from sphinx.util.typing import ExtensionMetadata, OptionSpec
     from sphinx.writers.html5 import HTML5Translator
@@ -111,6 +112,7 @@ WELL_KNOWN_ABBREVIATIONS = ('et al.', 'e.g.', 'i.e.')
 
 # -- autosummary_toc node ------------------------------------------------------
 
+
 class autosummary_toc(nodes.comment):
     pass
 
@@ -126,23 +128,26 @@ def autosummary_noop(self: nodes.NodeVisitor, node: Node) -> None:
 
 # -- autosummary_table node ----------------------------------------------------
 
+
 class autosummary_table(nodes.comment):
     pass
 
 
-def autosummary_table_visit_html(self: HTML5Translator, node: autosummary_table) -> None:
+def autosummary_table_visit_html(
+    self: HTML5Translator, node: autosummary_table
+) -> None:
     """Make the first column of the table non-breaking."""
     try:
-        table = cast(nodes.table, node[0])
-        tgroup = cast(nodes.tgroup, table[0])
-        tbody = cast(nodes.tbody, tgroup[-1])
-        rows = cast(list[nodes.row], tbody)
+        table = cast('nodes.table', node[0])
+        tgroup = cast('nodes.tgroup', table[0])
+        tbody = cast('nodes.tbody', tgroup[-1])
+        rows = cast('list[nodes.row]', tbody)
         for row in rows:
-            col1_entry = cast(nodes.entry, row[0])
-            par = cast(nodes.paragraph, col1_entry[0])
+            col1_entry = cast('nodes.entry', row[0])
+            par = cast('nodes.paragraph', col1_entry[0])
             for j, subnode in enumerate(list(par)):
                 if isinstance(subnode, nodes.Text):
-                    new_text = subnode.astext().replace(" ", "\u00a0")
+                    new_text = subnode.astext().replace(' ', '\u00a0')
                     par[j] = nodes.Text(new_text)
     except IndexError:
         pass
@@ -150,14 +155,15 @@ def autosummary_table_visit_html(self: HTML5Translator, node: autosummary_table)
 
 # -- autodoc integration -------------------------------------------------------
 
+
 class FakeApplication:
     verbosity = 0
 
     def __init__(self) -> None:
-        self.doctreedir = None
+        self.doctreedir = Path()
         self.events = None
         self.extensions: dict[str, Extension] = {}
-        self.srcdir = None
+        self.srcdir = Path()
         self.config = Config()
         self.project = Project('', {})
         self.registry = SphinxComponentRegistry()
@@ -174,7 +180,9 @@ class FakeDirective(DocumenterBridge):
         super().__init__(env, None, Options(), 0, state)
 
 
-def get_documenter(app: Sphinx, obj: Any, parent: Any) -> type[Documenter]:
+def _get_documenter(
+    obj: Any, parent: Any, *, registry: SphinxComponentRegistry
+) -> type[Documenter]:
     """Get an autodoc.Documenter class suitable for documenting the given
     object.
 
@@ -190,18 +198,21 @@ def get_documenter(app: Sphinx, obj: Any, parent: Any) -> type[Documenter]:
 
     # Construct a fake documenter for *parent*
     if parent is not None:
-        parent_doc_cls = get_documenter(app, parent, None)
+        parent_doc_cls = _get_documenter(parent, None, registry=registry)
     else:
         parent_doc_cls = ModuleDocumenter
 
     if hasattr(parent, '__name__'):
         parent_doc = parent_doc_cls(FakeDirective(), parent.__name__)
     else:
-        parent_doc = parent_doc_cls(FakeDirective(), "")
+        parent_doc = parent_doc_cls(FakeDirective(), '')
 
     # Get the correct documenter class for *obj*
-    classes = [cls for cls in app.registry.documenters.values()
-               if cls.can_document_member(obj, '', False, parent_doc)]
+    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]
@@ -211,9 +222,9 @@ def get_documenter(app: Sphinx, obj: Any, parent: Any) -> type[Documenter]:
 
 # -- .. autosummary:: ----------------------------------------------------------
 
+
 class Autosummary(SphinxDirective):
-    """
-    Pretty table containing short signatures and summaries of functions etc.
+    """Pretty table containing short signatures and summaries of functions etc.
 
     autosummary can also optionally generate a hidden toctree:: node.
     """
@@ -224,18 +235,24 @@ class Autosummary(SphinxDirective):
     has_content = True
     option_spec: ClassVar[OptionSpec] = {
         'caption': directives.unchanged_required,
+        'class': directives.class_option,
         'toctree': directives.unchanged,
         'nosignatures': directives.flag,
         'recursive': directives.flag,
+        'signatures': directives.unchanged,
         'template': directives.unchanged,
     }
 
     def run(self) -> list[Node]:
-        self.bridge = DocumenterBridge(self.env, self.state.document.reporter,
-                                       Options(), self.lineno, self.state)
-
-        names = [x.strip().split()[0] for x in self.content
-                 if x.strip() and re.search(r'^[~a-zA-Z_]', x.strip()[0])]
+        self.bridge = DocumenterBridge(
+            self.env, self.state.document.reporter, Options(), self.lineno, self.state
+        )
+
+        names = [
+            x.strip().split()[0]
+            for x in self.content
+            if x.strip() and re.search(r'^[~a-zA-Z_]', x.strip()[0])
+        ]
         items = self.get_items(names)
         nodes = self.get_table(items)
 
@@ -252,10 +269,14 @@ class Autosummary(SphinxDirective):
                 docname = posixpath.normpath(posixpath.join(dirname, docname))
                 if docname not in self.env.found_docs:
                     if excluded(str(self.env.doc2path(docname, False))):
-                        msg = __('autosummary references excluded document %r. Ignored.')
+                        msg = __(
+                            'autosummary references excluded document %r. Ignored.'
+                        )
                     else:
-                        msg = __('autosummary: stub file not found %r. '
-                                 'Check your autosummary_generate setting.')
+                        msg = __(
+                            'autosummary: stub file not found %r. '
+                            'Check your autosummary_generate setting.'
+                        )
 
                     logger.warning(msg, real_name, location=self.get_location())
                     continue
@@ -273,13 +294,15 @@ class Autosummary(SphinxDirective):
                 nodes.append(autosummary_toc('', '', tocnode))
 
         if 'toctree' not in self.options and 'caption' in self.options:
-            logger.warning(__('A captioned autosummary requires :toctree: option. ignored.'),
-                           location=nodes[-1])
+            logger.warning(
+                __('A captioned autosummary requires :toctree: option. ignored.'),
+                location=nodes[-1],
+            )
 
         return nodes
 
     def import_by_name(
-        self, name: str, prefixes: list[str | None],
+        self, name: str, prefixes: list[str | None]
     ) -> tuple[str, Any, Any, str]:
         with mock(self.config.autosummary_mock_imports):
             try:
@@ -296,23 +319,41 @@ class Autosummary(SphinxDirective):
 
                     raise ImportExceptionGroup(exc.args[0], errors) from None
 
-    def create_documenter(self, app: Sphinx, obj: Any,
-                          parent: Any, full_name: str) -> Documenter:
+    def create_documenter(
+        self,
+        obj: Any,
+        parent: Any,
+        full_name: str,
+        *,
+        registry: SphinxComponentRegistry,
+    ) -> Documenter:
         """Get an autodoc.Documenter class suitable for documenting the given
         object.
 
-        Wraps get_documenter and is meant as a hook for extensions.
+        Wraps _get_documenter and is meant as a hook for extensions.
         """
-        doccls = get_documenter(app, obj, parent)
+        doccls = _get_documenter(obj, parent, registry=registry)
         return doccls(self.bridge, full_name)
 
-    def get_items(self, names: list[str]) -> list[tuple[str, str, str, str]]:
+    def get_items(self, names: list[str]) -> list[tuple[str, str | None, str, str]]:
         """Try to import the given names, and return a list of
         ``[(name, signature, summary_string, real_name), ...]``.
+
+        signature is already formatted and is None if :nosignatures: option was given.
         """
         prefixes = get_import_prefixes_from_env(self.env)
 
-        items: list[tuple[str, str, str, str]] = []
+        items: list[tuple[str, str | None, str, str]] = []
+
+        signatures_option = self.options.get('signatures')
+        if signatures_option is None:
+            signatures_option = 'none' if 'nosignatures' in self.options else 'long'
+        if signatures_option not in {'none', 'short', 'long'}:
+            msg = (
+                'Invalid value for autosummary :signatures: option: '
+                f"{signatures_option!r}. Valid values are 'none', 'short', 'long'"
+            )
+            raise ValueError(msg)
 
         max_item_chars = 50
 
@@ -323,11 +364,17 @@ class Autosummary(SphinxDirective):
                 display_name = name.split('.')[-1]
 
             try:
-                real_name, obj, parent, modname = self.import_by_name(name, prefixes=prefixes)
+                real_name, obj, parent, modname = self.import_by_name(
+                    name, prefixes=prefixes
+                )
             except ImportExceptionGroup as exc:
-                errors = list({f"* {type(e).__name__}: {e}" for e in exc.exceptions})
-                logger.warning(__('autosummary: failed to import %s.\nPossible hints:\n%s'),
-                               name, '\n'.join(errors), location=self.get_location())
+                errors = list({f'* {type(e).__name__}: {e}' for e in exc.exceptions})
+                logger.warning(
+                    __('autosummary: failed to import %s.\nPossible hints:\n%s'),
+                    name,
+                    '\n'.join(errors),
+                    location=self.get_location(),
+                )
                 continue
 
             self.bridge.result = StringList()  # initialize for each documenter
@@ -335,25 +382,34 @@ class Autosummary(SphinxDirective):
             if not isinstance(obj, ModuleType):
                 # give explicitly separated module name, so that members
                 # of inner classes can be documented
-                full_name = modname + '::' + full_name[len(modname) + 1:]
+                full_name = modname + '::' + full_name[len(modname) + 1 :]
             # NB. using full_name here is important, since Documenters
             #     handle module prefixes slightly differently
-            documenter = self.create_documenter(self.env.app, obj, parent, full_name)
+            documenter = self.create_documenter(
+                obj, parent, full_name, registry=self.env._registry
+            )
             if not documenter.parse_name():
-                logger.warning(__('failed to parse name %s'), real_name,
-                               location=self.get_location())
+                logger.warning(
+                    __('failed to parse name %s'),
+                    real_name,
+                    location=self.get_location(),
+                )
                 items.append((display_name, '', '', real_name))
                 continue
             if not documenter.import_object():
-                logger.warning(__('failed to import object %s'), real_name,
-                               location=self.get_location())
+                logger.warning(
+                    __('failed to import object %s'),
+                    real_name,
+                    location=self.get_location(),
+                )
                 items.append((display_name, '', '', real_name))
                 continue
 
             # try to also get a source code analyzer for attribute docs
             try:
                 documenter.analyzer = ModuleAnalyzer.for_module(
-                    documenter.get_real_modname())
+                    documenter.get_real_modname()
+                )
                 # parse right now, to get PycodeErrors on parsing (results will
                 # be cached anyway)
                 documenter.analyzer.find_attr_docs()
@@ -364,17 +420,22 @@ class Autosummary(SphinxDirective):
 
             # -- Grab the signature
 
-            try:
-                sig = documenter.format_signature(show_annotation=False)
-            except TypeError:
-                # the documenter does not support ``show_annotation`` option
-                sig = documenter.format_signature()
-
-            if not sig:
-                sig = ''
+            if signatures_option == 'none':
+                sig = None
             else:
-                max_chars = max(10, max_item_chars - len(display_name))
-                sig = mangle_signature(sig, max_chars=max_chars)
+                try:
+                    sig = documenter.format_signature(show_annotation=False)
+                except TypeError:
+                    # the documenter does not support ``show_annotation`` option
+                    sig = documenter.format_signature()
+                if not sig:
+                    sig = ''
+                elif signatures_option == 'short':
+                    if sig != '()':
+                        sig = '(…)'
+                else:  # signatures_option == 'long'
+                    max_chars = max(10, max_item_chars - len(display_name))
+                    sig = mangle_signature(sig, max_chars=max_chars)
 
             # -- Grab the summary
 
@@ -388,7 +449,7 @@ class Autosummary(SphinxDirective):
 
         return items
 
-    def get_table(self, items: list[tuple[str, str, str, str]]) -> list[Node]:
+    def get_table(self, items: list[tuple[str, str | None, str, str]]) -> list[Node]:
         """Generate a proper list of table nodes for autosummary:: directive.
 
         *items* is a list produced by :meth:`get_items`.
@@ -397,7 +458,9 @@ class Autosummary(SphinxDirective):
         table_spec['spec'] = r'\X{1}{2}\X{1}{2}'
 
         table = autosummary_table('')
-        real_table = nodes.table('', classes=['autosummary longtable'])
+        real_table = nodes.table(
+            '', classes=['autosummary', 'longtable', *self.options.get('class', ())]
+        )
         table.append(real_table)
         group = nodes.tgroup('', cols=2)
         real_table.append(group)
@@ -412,8 +475,9 @@ class Autosummary(SphinxDirective):
             for text in column_texts:
                 vl = StringList([text], f'{source}:{line}:<autosummary>')
                 with switch_source_input(self.state, vl):
-                    col_nodes = nested_parse_to_nodes(self.state, vl,
-                                                      allow_section_headings=False)
+                    col_nodes = nested_parse_to_nodes(
+                        self.state, vl, allow_section_headings=False
+                    )
                     if col_nodes and isinstance(col_nodes[0], nodes.paragraph):
                         node = col_nodes[0]
                     else:
@@ -423,10 +487,11 @@ class Autosummary(SphinxDirective):
 
         for name, sig, summary, real_name in items:
             qualifier = 'obj'
-            if 'nosignatures' not in self.options:
-                col1 = f':py:{qualifier}:`{name} <{real_name}>`\\ {rst.escape(sig)}'
-            else:
+            if sig is None:
                 col1 = f':py:{qualifier}:`{name} <{real_name}>`'
+            else:
+                col1 = f':py:{qualifier}:`{name} <{real_name}>`\\ {rst.escape(sig)}'
+
             col2 = summary
             append_row(col1, col2)
 
@@ -463,31 +528,33 @@ def mangle_signature(sig: str, max_chars: int = 30) -> str:
     s = _cleanup_signature(sig)
 
     # Strip return type annotation
-    s = re.sub(r"\)\s*->\s.*$", ")", s)
+    s = re.sub(r'\)\s*->\s.*$', ')', s)
 
     # Remove parenthesis
-    s = re.sub(r"^\((.*)\)$", r"\1", s).strip()
+    s = re.sub(r'^\((.*)\)$', r'\1', s).strip()
 
     # Strip literals (which can contain things that confuse the code below)
-    s = re.sub(r"\\\\", "", s)      # escaped backslash (maybe inside string)
-    s = re.sub(r"\\'", "", s)       # escaped single quote
-    s = re.sub(r'\\"', "", s)       # escaped double quote
-    s = re.sub(r"'[^']*'", "", s)   # string literal (w/ single quote)
-    s = re.sub(r'"[^"]*"', "", s)   # string literal (w/ double quote)
+    s = re.sub(r'\\\\', '', s)  # escaped backslash (maybe inside string)
+    s = re.sub(r"\\'", '', s)  # escaped single quote
+    s = re.sub(r'\\"', '', s)  # escaped double quote
+    s = re.sub(r"'[^']*'", '', s)  # string literal (w/ single quote)
+    s = re.sub(r'"[^"]*"', '', s)  # string literal (w/ double quote)
 
     # Strip complex objects (maybe default value of arguments)
-    while re.search(r'\([^)]*\)', s):   # contents of parenthesis (ex. NamedTuple(attr=...))
+    while re.search(
+        r'\([^)]*\)', s
+    ):  # contents of parenthesis (ex. NamedTuple(attr=...))
         s = re.sub(r'\([^)]*\)', '', s)
-    while re.search(r'<[^>]*>', s):     # contents of angle brackets (ex. <object>)
+    while re.search(r'<[^>]*>', s):  # contents of angle brackets (ex. <object>)
         s = re.sub(r'<[^>]*>', '', s)
-    while re.search(r'{[^}]*}', s):     # contents of curly brackets (ex. dict)
+    while re.search(r'{[^}]*}', s):  # contents of curly brackets (ex. dict)
         s = re.sub(r'{[^}]*}', '', s)
 
     # Parse the signature to arguments + options
     args: list[str] = []
     opts: list[str] = []
 
-    opt_re = re.compile(r"^(.*, |)([a-zA-Z0-9_*]+)\s*=\s*")
+    opt_re = re.compile(r'^(.*, |)([a-zA-Z0-9_*]+)\s*=\s*')
     while s:
         m = opt_re.search(s)
         if not m:
@@ -506,19 +573,21 @@ def mangle_signature(sig: str, max_chars: int = 30) -> str:
         opts[i] = strip_arg_typehint(opt)
 
     # Produce a more compact signature
-    sig = limited_join(", ", args, max_chars=max_chars - 2)
+    sig = limited_join(', ', args, max_chars=max_chars - 2)
     if opts:
         if not sig:
-            sig = "[%s]" % limited_join(", ", opts, max_chars=max_chars - 4)
+            sig = '[%s]' % limited_join(', ', opts, max_chars=max_chars - 4)
         elif len(sig) < max_chars - 4 - 2 - 3:
-            sig += "[, %s]" % limited_join(", ", opts,
-                                           max_chars=max_chars - len(sig) - 4 - 2)
+            sig += '[, %s]' % limited_join(
+                ', ', opts, max_chars=max_chars - len(sig) - 4 - 2
+            )
 
-    return "(%s)" % sig
+    return '(%s)' % sig
 
 
 def extract_summary(doc: list[str], document: Any) -> str:
     """Extract summary from docstring."""
+
     def parse(doc: list[str], settings: Any) -> nodes.document:
         state_machine = RSTStateMachine(state_classes, 'Body')
         node = new_document('', settings)
@@ -552,13 +621,13 @@ def extract_summary(doc: list[str], document: Any) -> str:
         summary = doc[0].strip()
     else:
         # Try to find the "first sentence", which may span multiple lines
-        sentences = periods_re.split(" ".join(doc))
+        sentences = periods_re.split(' '.join(doc))
         if len(sentences) == 1:
             summary = sentences[0].strip()
         else:
             summary = ''
             for i in range(len(sentences)):
-                summary = ". ".join(sentences[:i + 1]).rstrip(".") + "."
+                summary = '. '.join(sentences[: i + 1]).rstrip('.') + '.'
                 node[:] = []
                 node = parse(doc, document.settings)
                 if summary.endswith(WELL_KNOWN_ABBREVIATIONS):
@@ -573,8 +642,9 @@ def extract_summary(doc: list[str], document: Any) -> str:
     return summary
 
 
-def limited_join(sep: str, items: list[str], max_chars: int = 30,
-                 overflow_marker: str = "...") -> str:
+def limited_join(
+    sep: str, items: list[str], max_chars: int = 30, overflow_marker: str = '...'
+) -> str:
     """Join a number of strings into one, limiting the length to *max_chars*.
 
     If the string overflows this limit, replace the last fitting item by
@@ -607,14 +677,15 @@ class ImportExceptionGroup(Exception):
     It contains an error messages and a list of exceptions as its arguments.
     """
 
-    def __init__(self, message: str | None, exceptions: Sequence[BaseException]) -> None:
+    def __init__(
+        self, message: str | None, exceptions: Sequence[BaseException]
+    ) -> None:
         super().__init__(message)
         self.exceptions = list(exceptions)
 
 
 def get_import_prefixes_from_env(env: BuildEnvironment) -> list[str | None]:
-    """
-    Obtain current Python import prefixes (for `import_by_name`)
+    """Obtain current Python import prefixes (for `import_by_name`)
     from ``document.env``
     """
     prefixes: list[str | None] = [None]
@@ -626,7 +697,7 @@ def get_import_prefixes_from_env(env: BuildEnvironment) -> list[str | None]:
     currclass = env.ref_context.get('py:class')
     if currclass:
         if currmodule:
-            prefixes.insert(0, currmodule + "." + currclass)
+            prefixes.insert(0, f'{currmodule}.{currclass}')
         else:
             prefixes.insert(0, currclass)
 
@@ -634,7 +705,7 @@ def get_import_prefixes_from_env(env: BuildEnvironment) -> list[str | None]:
 
 
 def import_by_name(
-    name: str, prefixes: Sequence[str | None] = (None,),
+    name: str, prefixes: Sequence[str | None] = (None,)
 ) -> tuple[str, Any, Any, str]:
     """Import a Python object that has the given *name*, under one of the
     *prefixes*.  The first name that succeeds is used.
@@ -644,17 +715,26 @@ def import_by_name(
     for prefix in prefixes:
         if prefix is not None and name.startswith(f'{prefix}.'):
             # Catch and avoid module cycles (e.g., sphinx.ext.sphinx.ext...)
-            msg = __('Summarised items should not include the current module. '
-                     'Replace %r with %r.')
-            logger.warning(msg, name, name.removeprefix(f'{prefix}.'),
-                           type='autosummary', subtype='import_cycle')
+            msg = __(
+                'Summarised items should not include the current module. '
+                'Replace %r with %r.'
+            )
+            logger.warning(
+                msg,
+                name,
+                name.removeprefix(f'{prefix}.'),
+                type='autosummary',
+                subtype='import_cycle',
+            )
             continue
         try:
             if prefix:
                 prefixed_name = f'{prefix}.{name}'
             else:
                 prefixed_name = name
-            obj, parent, modname = _import_by_name(prefixed_name, grouped_exception=True)
+            obj, parent, modname = _import_by_name(
+                prefixed_name, grouped_exception=True
+            )
             return prefixed_name, obj, parent, modname
         except ImportError:
             tried.append(prefixed_name)
@@ -663,7 +743,8 @@ def import_by_name(
             errors.append(exc)
 
     exceptions: list[BaseException] = functools.reduce(
-        operator.iadd, (e.exceptions for e in errors), [])
+        operator.iadd, (e.exceptions for e in errors), []
+    )
     raise ImportExceptionGroup('no module named %s' % ' or '.join(tried), exceptions)
 
 
@@ -714,13 +795,14 @@ def _import_by_name(name: str, grouped_exception: bool = True) -> tuple[Any, Any
             raise ImportError(*exc.args) from exc
 
 
-def import_ivar_by_name(name: str, prefixes: Sequence[str | None] = (None,),
-                        grouped_exception: bool = True) -> tuple[str, Any, Any, str]:
+def import_ivar_by_name(
+    name: str, prefixes: Sequence[str | None] = (None,), grouped_exception: bool = True
+) -> tuple[str, Any, Any, str]:
     """Import an instance variable that has the given *name*, under one of the
     *prefixes*.  The first name that succeeds is used.
     """
     try:
-        name, attr = name.rsplit(".", 1)
+        name, attr = name.rsplit('.', 1)
         real_name, obj, parent, modname = import_by_name(name, prefixes)
 
         # Get ancestors of the object (class.__mro__ includes the class itself as
@@ -730,14 +812,16 @@ def import_ivar_by_name(name: str, prefixes: Sequence[str | None] = (None,),
             candidate_objects = (obj,)
 
         for candidate_obj in candidate_objects:
-            analyzer = ModuleAnalyzer.for_module(getattr(candidate_obj, '__module__', modname))
+            analyzer = ModuleAnalyzer.for_module(
+                getattr(candidate_obj, '__module__', modname)
+            )
             analyzer.analyze()
             # check for presence in `annotations` to include dataclass attributes
             found_attrs = set()
             found_attrs |= {attr for (qualname, attr) in analyzer.attr_docs}
             found_attrs |= {attr for (qualname, attr) in analyzer.annotations}
             if attr in found_attrs:
-                return real_name + "." + attr, INSTANCEATTR, obj, modname
+                return f'{real_name}.{attr}', INSTANCEATTR, obj, modname
     except (ImportError, ValueError, PycodeError) as exc:
         raise ImportError from exc
     except ImportExceptionGroup:
@@ -748,6 +832,7 @@ def import_ivar_by_name(name: str, prefixes: Sequence[str | None] = (None,),
 
 # -- :autolink: (smart default role) -------------------------------------------
 
+
 class AutoLink(SphinxRole):
     """Smart linking role.
 
@@ -758,13 +843,20 @@ class AutoLink(SphinxRole):
     def run(self) -> tuple[list[Node], list[system_message]]:
         pyobj_role = self.env.domains.python_domain.role('obj')
         assert pyobj_role is not None
-        objects, errors = pyobj_role('obj', self.rawtext, self.text, self.lineno,
-                                     self.inliner, self.options, self.content)
+        objects, errors = pyobj_role(
+            'obj',
+            self.rawtext,
+            self.text,
+            self.lineno,
+            self.inliner,
+            self.options,
+            self.content,
+        )
         if errors:
             return objects, errors
 
         assert len(objects) == 1
-        pending_xref = cast(addnodes.pending_xref, objects[0])
+        pending_xref = cast('addnodes.pending_xref', objects[0])
         try:
             # try to import object by name
             prefixes = get_import_prefixes_from_env(self.env)
@@ -777,9 +869,10 @@ class AutoLink(SphinxRole):
             ]
             import_by_name(name, prefixes)
         except ImportExceptionGroup:
-            literal = cast(nodes.literal, pending_xref[0])
-            objects[0] = nodes.emphasis(self.rawtext, literal.astext(),
-                                        classes=literal['classes'])
+            literal = cast('nodes.literal', pending_xref[0])
+            objects[0] = nodes.emphasis(
+                self.rawtext, literal.astext(), classes=literal['classes']
+            )
 
         return objects, errors
 
@@ -803,18 +896,23 @@ def process_generate_options(app: Sphinx) -> None:
     genfiles = app.config.autosummary_generate
 
     if genfiles is True:
-        env = app.builder.env
-        genfiles = [str(env.doc2path(x, base=False)) for x in env.found_docs
-                    if os.path.isfile(env.doc2path(x))]
+        env = app.env
+        genfiles = [
+            str(env.doc2path(x, base=False))
+            for x in env.found_docs
+            if env.doc2path(x).is_file()
+        ]
     elif genfiles is False:
         pass
     else:
         ext = list(app.config.source_suffix)
-        genfiles = [genfile + (ext[0] if not genfile.endswith(tuple(ext)) else '')
-                    for genfile in genfiles]
+        genfiles = [
+            genfile + (ext[0] if not genfile.endswith(tuple(ext)) else '')
+            for genfile in genfiles
+        ]
 
         for entry in genfiles[:]:
-            if not path.isfile(path.join(app.srcdir, entry)):
+            if not (app.srcdir / entry).is_file():
                 logger.warning(__('autosummary_generate: file not found: %s'), entry)
                 genfiles.remove(entry)
 
@@ -823,45 +921,75 @@ def process_generate_options(app: Sphinx) -> None:
 
     suffix = get_rst_suffix(app)
     if suffix is None:
-        logger.warning(__('autosummary generates .rst files internally. '
-                          'But your source_suffix does not contain .rst. Skipped.'))
+        logger.warning(
+            __(
+                'autosummary generates .rst files internally. '
+                'But your source_suffix does not contain .rst. Skipped.'
+            )
+        )
         return
 
     from sphinx.ext.autosummary.generate import generate_autosummary_docs
 
     imported_members = app.config.autosummary_imported_members
     with mock(app.config.autosummary_mock_imports):
-        generate_autosummary_docs(genfiles, suffix=suffix, base_path=app.srcdir,
-                                  app=app, imported_members=imported_members,
-                                  overwrite=app.config.autosummary_generate_overwrite,
-                                  encoding=app.config.source_encoding)
+        generate_autosummary_docs(
+            genfiles,
+            suffix=suffix,
+            base_path=app.srcdir,
+            app=app,
+            imported_members=imported_members,
+            overwrite=app.config.autosummary_generate_overwrite,
+            encoding=app.config.source_encoding,
+        )
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
     # I need autodoc
     app.setup_extension('sphinx.ext.autodoc')
-    app.add_node(autosummary_toc,
-                 html=(autosummary_toc_visit_html, autosummary_noop),
-                 latex=(autosummary_noop, autosummary_noop),
-                 text=(autosummary_noop, autosummary_noop),
-                 man=(autosummary_noop, autosummary_noop),
-                 texinfo=(autosummary_noop, autosummary_noop))
-    app.add_node(autosummary_table,
-                 html=(autosummary_table_visit_html, autosummary_noop),
-                 latex=(autosummary_noop, autosummary_noop),
-                 text=(autosummary_noop, autosummary_noop),
-                 man=(autosummary_noop, autosummary_noop),
-                 texinfo=(autosummary_noop, autosummary_noop))
+    app.add_node(
+        autosummary_toc,
+        html=(autosummary_toc_visit_html, autosummary_noop),
+        latex=(autosummary_noop, autosummary_noop),
+        text=(autosummary_noop, autosummary_noop),
+        man=(autosummary_noop, autosummary_noop),
+        texinfo=(autosummary_noop, autosummary_noop),
+    )
+    app.add_node(
+        autosummary_table,
+        html=(autosummary_table_visit_html, autosummary_noop),
+        latex=(autosummary_noop, autosummary_noop),
+        text=(autosummary_noop, autosummary_noop),
+        man=(autosummary_noop, autosummary_noop),
+        texinfo=(autosummary_noop, autosummary_noop),
+    )
     app.add_directive('autosummary', Autosummary)
     app.add_role('autolink', AutoLink())
     app.connect('builder-inited', process_generate_options)
-    app.add_config_value('autosummary_context', {}, 'env')
-    app.add_config_value('autosummary_filename_map', {}, 'html')
-    app.add_config_value('autosummary_generate', True, 'env', {bool, list})
-    app.add_config_value('autosummary_generate_overwrite', True, '')
-    app.add_config_value('autosummary_mock_imports',
-                         lambda config: config.autodoc_mock_imports, 'env')
-    app.add_config_value('autosummary_imported_members', [], '', bool)
-    app.add_config_value('autosummary_ignore_module_all', True, 'env', bool)
-
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
+    app.add_config_value('autosummary_context', {}, 'env', types=frozenset({dict}))
+    app.add_config_value(
+        'autosummary_filename_map', {}, 'html', types=frozenset({dict})
+    )
+    app.add_config_value(
+        'autosummary_generate', True, 'env', types=frozenset({bool, list})
+    )
+    app.add_config_value(
+        'autosummary_generate_overwrite', True, '', types=frozenset({bool})
+    )
+    app.add_config_value(
+        'autosummary_mock_imports',
+        lambda config: config.autodoc_mock_imports,
+        'env',
+        types=frozenset({list, tuple}),
+    )
+    app.add_config_value(
+        'autosummary_imported_members', False, '', types=frozenset({bool})
+    )
+    app.add_config_value(
+        'autosummary_ignore_module_all', True, 'env', types=frozenset({bool})
+    )
+
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+    }