Sphinx 7.3.6__py3-none-any.whl → 7.4.0__py3-none-any.whl

sphinx/ext/autodoc/__init__.py

@@ -170,7 +170,7 @@ def merge_members_option(options: dict) -> None:
         return
 
     members = options.setdefault('members', [])
-    for key in {'private-members', 'special-members'}:
+    for key in ('private-members', 'special-members'):
         if key in options and options[key] not in (ALL, None):
             for member in options[key]:
                 if member not in members:
@@ -396,7 +396,7 @@ class Documenter:
         # an autogenerated one
         matched = py_ext_sig_re.match(self.name)
         if matched is None:
-            logger.warning(__('invalid signature for auto%s (%r)') % (self.objtype, self.name),
+            logger.warning(__('invalid signature for auto%s (%r)'), self.objtype, self.name,
                            type='autodoc')
             return False
         explicit_modname, path, base, tp_list, args, retann = matched.groups()
@@ -892,7 +892,7 @@ class Documenter:
             logger.warning(
                 __("don't know which module to import for autodocumenting "
                    '%r (try placing a "module" or "currentmodule" directive '
-                   'in the document, or giving an explicit module name)') %
+                   'in the document, or giving an explicit module name)'),
                 self.name, type='autodoc')
             return
 
@@ -1024,7 +1024,7 @@ class ModuleDocumenter(Documenter):
         ret = super().parse_name()
         if self.args or self.retann:
             logger.warning(__('signature arguments or return annotation '
-                              'given for automodule %s') % self.fullname,
+                              'given for automodule %s'), self.fullname,
                            type='autodoc')
         return ret
 
@@ -1037,8 +1037,8 @@ class ModuleDocumenter(Documenter):
         except ValueError as exc:
             # invalid __all__ found.
             logger.warning(__('__all__ should be a list of strings, not %r '
-                              '(in module %s) -- ignoring __all__') %
-                           (exc.args[0], self.fullname), type='autodoc')
+                              '(in module %s) -- ignoring __all__'),
+                           exc.args[0], self.fullname, type='autodoc')
 
         return ret
 
@@ -1103,8 +1103,8 @@ class ModuleDocumenter(Documenter):
                     ret.append(members[name])
                 else:
                     logger.warning(__('missing attribute mentioned in :members: option: '
-                                      'module %s, attribute %s') %
-                                   (safe_getattr(self.object, '__name__', '???'), name),
+                                      'module %s, attribute %s'),
+                                   safe_getattr(self.object, '__name__', '???', name),
                                    type='autodoc')
             return False, ret
 
@@ -1756,8 +1756,8 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
                 if name in members:
                     selected.append(members[name])
                 else:
-                    logger.warning(__('missing attribute %s in object %s') %
-                                   (name, self.fullname), type='autodoc')
+                    logger.warning(__('missing attribute %s in object %s'),
+                                   name, self.fullname, type='autodoc')
             return False, selected
         elif self.options.inherited_members:
             return False, list(members.values())
@@ -2721,10 +2721,10 @@ class AttributeDocumenter(GenericAliasMixin, SlotsMixin,  # type: ignore[misc]
             # a docstring from the value which descriptor returns unexpectedly.
             # ref: https://github.com/sphinx-doc/sphinx/issues/7805
             orig = self.config.autodoc_inherit_docstrings
-            self.config.autodoc_inherit_docstrings = False  # type: ignore[attr-defined]
+            self.config.autodoc_inherit_docstrings = False
             return super().get_doc()
         finally:
-            self.config.autodoc_inherit_docstrings = orig  # type: ignore[attr-defined]
+            self.config.autodoc_inherit_docstrings = orig
 
     def add_content(self, more_content: StringList | None) -> None:
         # Disable analyzing attribute comment on Documenter.add_content() to control it on
@@ -2773,7 +2773,7 @@ class PropertyDocumenter(DocstringStripSignatureMixin,  # type: ignore[misc]
             obj = __dict__.get(self.objpath[-1])
             if isinstance(obj, classmethod) and inspect.isproperty(obj.__func__):
                 self.object = obj.__func__
-                self.isclassmethod = True
+                self.isclassmethod: bool = True
                 return True
             else:
                 return False

sphinx/ext/autodoc/directive.py

@@ -9,10 +9,10 @@ from docutils.utils import Reporter, assemble_option_dict
 from sphinx.ext.autodoc import Documenter, Options
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective, switch_source_input
-from sphinx.util.nodes import nested_parse_with_titles
+from sphinx.util.parsing import nested_parse_to_nodes
 
 if TYPE_CHECKING:
-    from docutils.nodes import Element, Node
+    from docutils.nodes import Node
     from docutils.parsers.rst.states import RSTState
 
     from sphinx.config import Config
@@ -86,15 +86,12 @@ def parse_generated_content(state: RSTState, content: StringList, documenter: Do
     """Parse an item of content generated by Documenter."""
     with switch_source_input(state, content):
         if documenter.titles_allowed:
-            node: Element = nodes.section()
-            # necessary so that the child nodes get the right source/line set
-            node.document = state.document
-            nested_parse_with_titles(state, content, node)
-        else:
-            node = nodes.paragraph()
-            node.document = state.document
-            state.nested_parse(content, 0, node)
+            return nested_parse_to_nodes(state, content)
 
+        node = nodes.paragraph()
+        # necessary so that the child nodes get the right source/line set
+        node.document = state.document
+        state.nested_parse(content, 0, node, match_titles=False)
         return node.children
 
 
@@ -115,7 +112,7 @@ class AutodocDirective(SphinxDirective):
         reporter = self.state.document.reporter
 
         try:
-            source, lineno = reporter.get_source_and_line(
+            source, lineno = reporter.get_source_and_line(  # type: ignore[attr-defined]
                 self.lineno)
         except AttributeError:
             source, lineno = (None, None)
@@ -130,8 +127,8 @@ class AutodocDirective(SphinxDirective):
             documenter_options = process_documenter_options(doccls, self.config, self.options)
         except (KeyError, ValueError, TypeError) as exc:
             # an option is either unknown or has a wrong type
-            logger.error('An option to %s is either unknown or has an invalid value: %s' %
-                         (self.name, exc), location=(self.env.docname, lineno))
+            logger.error('An option to %s is either unknown or has an invalid value: %s',
+                         self.name, exc, location=(self.env.docname, lineno))
             return []
 
         # generate the output

sphinx/ext/autodoc/mock.py

@@ -8,13 +8,16 @@ import sys
 from importlib.abc import Loader, MetaPathFinder
 from importlib.machinery import ModuleSpec
 from types import MethodType, ModuleType
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from sphinx.util import logging
 from sphinx.util.inspect import isboundmethod, safe_getattr
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Sequence
+    from typing import Any
+
+    from typing_extensions import TypeIs
 
 logger = logging.getLogger(__name__)
 
@@ -46,10 +49,10 @@ class _MockObject:
     def __contains__(self, key: str) -> bool:
         return False
 
-    def __iter__(self) -> Iterator:
-        return iter([])
+    def __iter__(self) -> Iterator[Any]:
+        return iter(())
 
-    def __mro_entries__(self, bases: tuple) -> tuple:
+    def __mro_entries__(self, bases: tuple[Any, ...]) -> tuple[type, ...]:
         return (self.__class__,)
 
     def __getitem__(self, key: Any) -> _MockObject:
@@ -68,7 +71,7 @@ class _MockObject:
 
 
 def _make_subclass(name: str, module: str, superclass: Any = _MockObject,
-                   attributes: Any = None, decorator_args: tuple = ()) -> Any:
+                   attributes: Any = None, decorator_args: tuple[Any, ...] = ()) -> Any:
     attrs = {'__module__': module,
              '__display_name__': module + '.' + name,
              '__name__': name,
@@ -144,8 +147,8 @@ def mock(modnames: list[str]) -> Iterator[None]:
         # mock modules are enabled here
         ...
     """
+    finder = MockFinder(modnames)
     try:
-        finder = MockFinder(modnames)
         sys.meta_path.insert(0, finder)
         yield
     finally:
@@ -153,7 +156,7 @@ def mock(modnames: list[str]) -> Iterator[None]:
         finder.invalidate_caches()
 
 
-def ismockmodule(subject: Any) -> bool:
+def ismockmodule(subject: Any) -> TypeIs[_MockModule]:
     """Check if the object is a mocked module."""
     return isinstance(subject, _MockModule)
 

sphinx/ext/autodoc/preserve_defaults.py

@@ -109,7 +109,7 @@ def _get_arguments_inner(x: Any, /) -> ast.arguments | None:
     return None
 
 
-def get_default_value(lines: list[str], position: ast.AST) -> str | None:
+def get_default_value(lines: list[str], position: ast.expr) -> str | None:
     try:
         if position.lineno == position.end_lineno:
             line = lines[position.lineno - 1]

sphinx/ext/autodoc/typehints.py

@@ -35,9 +35,9 @@ def record_typehints(app: Sphinx, objtype: str, name: str, obj: Any,
             sig = inspect.signature(obj, type_aliases=app.config.autodoc_type_aliases)
             for param in sig.parameters.values():
                 if param.annotation is not param.empty:
-                    annotation[param.name] = stringify_annotation(param.annotation, mode)
+                    annotation[param.name] = stringify_annotation(param.annotation, mode)  # type: ignore[arg-type]
             if sig.return_annotation is not sig.empty:
-                annotation['return'] = stringify_annotation(sig.return_annotation, mode)
+                annotation['return'] = stringify_annotation(sig.return_annotation, mode)  # type: ignore[arg-type]
     except (TypeError, ValueError):
         pass
 

sphinx/ext/autosummary/__init__.py

@@ -87,6 +87,7 @@ from sphinx.util.docutils import (
 )
 from sphinx.util.inspect import getmro, signature_from_str
 from sphinx.util.matching import Matcher
+from sphinx.util.parsing import nested_parse_to_nodes
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -406,16 +407,14 @@ class Autosummary(SphinxDirective):
             row = nodes.row('')
             source, line = self.state_machine.get_source_and_line()
             for text in column_texts:
-                node = nodes.paragraph('')
-                vl = StringList()
-                vl.append(text, '%s:%d:<autosummary>' % (source, line))
+                vl = StringList([text], f'{source}:{line}:<autosummary>')
                 with switch_source_input(self.state, vl):
-                    self.state.nested_parse(vl, 0, node)
-                    try:
-                        if isinstance(node[0], nodes.paragraph):
-                            node = node[0]
-                    except IndexError:
-                        pass
+                    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:
+                        node = nodes.paragraph('')
                     row.append(nodes.entry('', node))
             body.append(row)
 
@@ -640,6 +639,13 @@ def import_by_name(
     tried = []
     errors: list[ImportExceptionGroup] = []
     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')
+            continue
         try:
             if prefix:
                 prefixed_name = f'{prefix}.{name}'