Sphinx 7.1.1__py3-none-any.whl → 7.2.0__py3-none-any.whl

sphinx/ext/autodoc/directive.py

@@ -1,20 +1,23 @@
 from __future__ import annotations
 
-from typing import Any, Callable
+from typing import TYPE_CHECKING, Any, Callable
 
 from docutils import nodes
-from docutils.nodes import Element, Node
-from docutils.parsers.rst.states import RSTState
 from docutils.statemachine import StringList
 from docutils.utils import Reporter, assemble_option_dict
 
-from sphinx.config import Config
-from sphinx.environment import BuildEnvironment
 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
 
+if TYPE_CHECKING:
+    from docutils.nodes import Element, Node
+    from docutils.parsers.rst.states import RSTState
+
+    from sphinx.config import Config
+    from sphinx.environment import BuildEnvironment
+
 logger = logging.getLogger(__name__)
 
 
@@ -111,7 +114,8 @@ class AutodocDirective(SphinxDirective):
         reporter = self.state.document.reporter
 
         try:
-            source, lineno = reporter.get_source_and_line(self.lineno)  # type: ignore
+            source, lineno = reporter.get_source_and_line(  # type: ignore[attr-defined]
+                self.lineno)
         except AttributeError:
             source, lineno = (None, None)
         logger.debug('[autodoc] %s:%s: input:\n%s', source, lineno, self.block_text)

sphinx/ext/autodoc/importer.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import importlib
 import traceback
-import warnings
+import typing
 from typing import TYPE_CHECKING, Any, Callable, NamedTuple
 
 from sphinx.ext.autodoc.mock import ismock, undecorate
@@ -60,10 +60,8 @@ def import_module(modname: str, warningiserror: bool = False) -> Any:
     Call importlib.import_module(modname), convert exceptions to ImportError
     """
     try:
-        with warnings.catch_warnings():
-            warnings.filterwarnings("ignore", category=ImportWarning)
-            with logging.skip_warningiserror(not warningiserror):
-                return importlib.import_module(modname)
+        with logging.skip_warningiserror(not warningiserror):
+            return importlib.import_module(modname)
     except BaseException as exc:
         # Importing modules may cause any side effects, including
         # SystemExit, so we need to catch all errors.
@@ -84,7 +82,18 @@ def import_object(modname: str, objpath: list[str], objtype: str = '',
         objpath = list(objpath)
         while module is None:
             try:
-                module = import_module(modname, warningiserror=warningiserror)
+                try:
+                    # try importing with ``typing.TYPE_CHECKING == True``
+                    typing.TYPE_CHECKING = True
+                    module = import_module(modname, warningiserror=warningiserror)
+                except ImportError:
+                    # if that fails (e.g. circular import), retry with
+                    # ``typing.TYPE_CHECKING == False``
+                    typing.TYPE_CHECKING = False
+                    module = import_module(modname, warningiserror=warningiserror)
+                finally:
+                    # ensure ``typing.TYPE_CHECKING == False``
+                    typing.TYPE_CHECKING = False
                 logger.debug('[autodoc] import %s => %r', modname, module)
             except ImportError as exc:
                 logger.debug('[autodoc] import %s => failed', modname)
@@ -177,11 +186,11 @@ def get_object_members(
 
     # members in __slots__
     try:
-        __slots__ = getslots(subject)
-        if __slots__:
+        subject___slots__ = getslots(subject)
+        if subject___slots__:
             from sphinx.ext.autodoc import SLOTSATTR
 
-            for name in __slots__:
+            for name in subject___slots__:
                 members[name] = Attribute(name, True, SLOTSATTR)
     except (TypeError, ValueError):
         pass
@@ -214,7 +223,7 @@ def get_object_members(
     return members
 
 
-def get_class_members(subject: Any, objpath: list[str], attrgetter: Callable,
+def get_class_members(subject: Any, objpath: Any, attrgetter: Callable,
                       inherit_docstrings: bool = True) -> dict[str, ObjectMember]:
     """Get members and attributes of target class."""
     from sphinx.ext.autodoc import INSTANCEATTR, ObjectMember
@@ -238,11 +247,11 @@ def get_class_members(subject: Any, objpath: list[str], attrgetter: Callable,
 
     # members in __slots__
     try:
-        __slots__ = getslots(subject)
-        if __slots__:
+        subject___slots__ = getslots(subject)
+        if subject___slots__:
             from sphinx.ext.autodoc import SLOTSATTR
 
-            for name, docstring in __slots__.items():
+            for name, docstring in subject___slots__.items():
                 members[name] = ObjectMember(name, SLOTSATTR, class_=subject,
                                              docstring=docstring)
     except (TypeError, ValueError):

sphinx/ext/autodoc/mock.py

@@ -8,11 +8,14 @@ import sys
 from importlib.abc import Loader, MetaPathFinder
 from importlib.machinery import ModuleSpec
 from types import MethodType, ModuleType
-from typing import Any, Generator, Iterator, Sequence
+from typing import TYPE_CHECKING, Any
 
 from sphinx.util import logging
 from sphinx.util.inspect import isboundmethod, safe_getattr
 
+if TYPE_CHECKING:
+    from collections.abc import Generator, Iterator, Sequence
+
 logger = logging.getLogger(__name__)
 
 

sphinx/ext/autodoc/preserve_defaults.py

@@ -8,15 +8,23 @@ from __future__ import annotations
 
 import ast
 import inspect
-from typing import Any
+import types
+import warnings
+from typing import TYPE_CHECKING
 
 import sphinx
-from sphinx.application import Sphinx
+from sphinx.deprecation import RemovedInSphinx90Warning
 from sphinx.locale import __
 from sphinx.pycode.ast import unparse as ast_unparse
 from sphinx.util import logging
 
+if TYPE_CHECKING:
+    from typing import Any
+
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
+_LAMBDA_NAME = (lambda: None).__name__
 
 
 class DefaultValue:
@@ -29,23 +37,77 @@ class DefaultValue:
 
 def get_function_def(obj: Any) -> ast.FunctionDef | None:
     """Get FunctionDef object from living object.
+
     This tries to parse original code for living object and returns
     AST node for given *obj*.
     """
+    warnings.warn('sphinx.ext.autodoc.preserve_defaults.get_function_def is'
+                  ' deprecated and scheduled for removal in Sphinx 9.'
+                  ' Use sphinx.ext.autodoc.preserve_defaults._get_arguments() to'
+                  ' extract AST arguments objects from a lambda or regular'
+                  ' function.', RemovedInSphinx90Warning, stacklevel=2)
+
     try:
         source = inspect.getsource(obj)
-        if source.startswith((' ', r'\t')):
+        if source.startswith((' ', '\t')):
             # subject is placed inside class or block.  To read its docstring,
             # this adds if-block before the declaration.
             module = ast.parse('if True:\n' + source)
-            return module.body[0].body[0]  # type: ignore
+            return module.body[0].body[0]  # type: ignore[attr-defined]
         else:
             module = ast.parse(source)
-            return module.body[0]  # type: ignore
+            return module.body[0]  # type: ignore[return-value]
     except (OSError, TypeError):  # failed to load source code
         return None
 
 
+def _get_arguments(obj: Any, /) -> ast.arguments | None:
+    """Parse 'ast.arguments' from an object.
+
+    This tries to parse the original code for an object and returns
+    an 'ast.arguments' node.
+    """
+    try:
+        source = inspect.getsource(obj)
+        if source.startswith((' ', '\t')):
+            # 'obj' is in some indented block.
+            module = ast.parse('if True:\n' + source)
+            subject = module.body[0].body[0]  # type: ignore[attr-defined]
+        else:
+            module = ast.parse(source)
+            subject = module.body[0]
+    except (OSError, TypeError):
+        # bail; failed to load source for 'obj'.
+        return None
+    except SyntaxError:
+        if _is_lambda(obj):
+            # Most likely a multi-line arising from detecting a lambda, e.g.:
+            #
+            # class Egg:
+            #     x = property(
+            #         lambda self: 1, doc="...")
+            return None
+
+        # Other syntax errors that are not due to the fact that we are
+        # documenting a lambda function are propagated
+        # (in particular if a lambda is renamed by the user).
+        raise
+
+    return _get_arguments_inner(subject)
+
+
+def _is_lambda(x, /):
+    return isinstance(x, types.LambdaType) and x.__name__ == _LAMBDA_NAME
+
+
+def _get_arguments_inner(x: Any, /) -> ast.arguments | None:
+    if isinstance(x, (ast.AsyncFunctionDef, ast.FunctionDef, ast.Lambda)):
+        return x.args
+    if isinstance(x, (ast.Assign, ast.AnnAssign)):
+        return _get_arguments_inner(x.value)
+    return None
+
+
 def get_default_value(lines: list[str], position: ast.AST) -> str | None:
     try:
         if position.lineno == position.end_lineno:
@@ -65,18 +127,24 @@ def update_defvalue(app: Sphinx, obj: Any, bound_method: bool) -> None:
 
     try:
         lines = inspect.getsource(obj).splitlines()
-        if lines[0].startswith((' ', r'\t')):
-            lines.insert(0, '')  # insert a dummy line to follow what get_function_def() does.
+        if lines[0].startswith((' ', '\t')):
+            # insert a dummy line to follow what _get_arguments() does.
+            lines.insert(0, '')
     except (OSError, TypeError):
         lines = []
 
     try:
-        function = get_function_def(obj)
-        assert function is not None  # for mypy
-        if function.args.defaults or function.args.kw_defaults:
+        args = _get_arguments(obj)
+        if args is None:
+            # If the object is a built-in, we won't be always able to recover
+            # the function definition and its arguments. This happens if *obj*
+            # is the `__init__` method generated automatically for dataclasses.
+            return
+
+        if args.defaults or args.kw_defaults:
             sig = inspect.signature(obj)
-            defaults = list(function.args.defaults)
-            kw_defaults = list(function.args.kw_defaults)
+            defaults = list(args.defaults)
+            kw_defaults = list(args.kw_defaults)
             parameters = list(sig.parameters.values())
             for i, param in enumerate(parameters):
                 if param.default is param.empty:

sphinx/ext/autodoc/type_comment.py

@@ -4,26 +4,29 @@ from __future__ import annotations
 
 import ast
 from inspect import Parameter, Signature, getsource
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 import sphinx
-from sphinx.application import Sphinx
 from sphinx.locale import __
 from sphinx.pycode.ast import unparse as ast_unparse
 from sphinx.util import inspect, logging
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
 
 
-def not_suppressed(argtypes: list[ast.AST] = []) -> bool:
+def not_suppressed(argtypes: Sequence[ast.expr] = ()) -> bool:
     """Check given *argtypes* is suppressed type_comment or not."""
     if len(argtypes) == 0:  # no argtypees
         return False
-    if len(argtypes) == 1 and ast_unparse(argtypes[0]) == "...":  # suppressed
-        # Note: To support multiple versions of python, this uses ``ast_unparse()`` for
-        # comparison with Ellipsis.  Since 3.8, ast.Constant has been used to represent
-        # Ellipsis node instead of ast.Ellipsis.
-        return False
+    if len(argtypes) == 1:
+        arg = argtypes[0]
+        if isinstance(arg, ast.Constant) and arg.value is ...:  # suppressed
+            return False
     # not suppressed
     return True
 
@@ -64,9 +67,10 @@ def signature_from_ast(node: ast.FunctionDef, bound_method: bool,
         params.pop(0)
 
     # merge type_comment into signature
-    if not_suppressed(type_comment.argtypes):  # type: ignore
+    if not_suppressed(type_comment.argtypes):  # type: ignore[attr-defined]
         for i, param in enumerate(params):
-            params[i] = param.replace(annotation=type_comment.argtypes[i])  # type: ignore
+            params[i] = param.replace(
+                annotation=type_comment.argtypes[i])  # type: ignore[attr-defined]
 
     if node.returns:
         return Signature(params, return_annotation=node.returns)

sphinx/ext/autodoc/typehints.py

@@ -3,17 +3,21 @@
 from __future__ import annotations
 
 import re
-from typing import Any, Iterable, cast
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
-from docutils.nodes import Element
 
 import sphinx
 from sphinx import addnodes
-from sphinx.application import Sphinx
 from sphinx.util import inspect
 from sphinx.util.typing import stringify_annotation
 
+if TYPE_CHECKING:
+    from docutils.nodes import Element
+
+    from sphinx.application import Sphinx
+
 
 def record_typehints(app: Sphinx, objtype: str, name: str, obj: Any,
                      options: dict, args: str, retann: str) -> None:

sphinx/ext/autosectionlabel.py

@@ -2,18 +2,21 @@
 
 from __future__ import annotations
 
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
-from docutils.nodes import Node
 
 import sphinx
-from sphinx.application import Sphinx
 from sphinx.domains.std import StandardDomain
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.nodes import clean_astext
 
+if TYPE_CHECKING:
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
 
 

sphinx/ext/autosummary/__init__.py

@@ -56,24 +56,21 @@ import sys
 from inspect import Parameter
 from os import path
 from types import ModuleType
-from typing import Any, List, Sequence, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
-from docutils.nodes import Node, system_message
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.states import RSTStateMachine, Struct, state_classes
 from docutils.statemachine import StringList
 
 import sphinx
 from sphinx import addnodes
-from sphinx.application import Sphinx
 from sphinx.config import Config
 from sphinx.environment import BuildEnvironment
 from sphinx.ext.autodoc import INSTANCEATTR, Documenter
 from sphinx.ext.autodoc.directive import DocumenterBridge, Options
 from sphinx.ext.autodoc.importer import import_module
 from sphinx.ext.autodoc.mock import mock
-from sphinx.extension import Extension
 from sphinx.locale import __
 from sphinx.project import Project
 from sphinx.pycode import ModuleAnalyzer, PycodeError
@@ -88,8 +85,16 @@ from sphinx.util.docutils import (
 )
 from sphinx.util.inspect import getmro, signature_from_str
 from sphinx.util.matching import Matcher
-from sphinx.util.typing import OptionSpec
-from sphinx.writers.html import HTML5Translator
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from docutils.nodes import Node, system_message
+
+    from sphinx.application import Sphinx
+    from sphinx.extension import Extension
+    from sphinx.util.typing import OptionSpec
+    from sphinx.writers.html import HTML5Translator
 
 logger = logging.getLogger(__name__)
 
@@ -97,7 +102,7 @@ logger = logging.getLogger(__name__)
 periods_re = re.compile(r'\.(?:\s+)')
 literal_re = re.compile(r'::\s*$')
 
-WELL_KNOWN_ABBREVIATIONS = ('et al.', ' i.e.',)
+WELL_KNOWN_ABBREVIATIONS = ('et al.', 'e.g.', 'i.e.')
 
 
 # -- autosummary_toc node ------------------------------------------------------
@@ -127,7 +132,7 @@ def autosummary_table_visit_html(self: HTML5Translator, node: autosummary_table)
         table = cast(nodes.table, node[0])
         tgroup = cast(nodes.tgroup, table[0])
         tbody = cast(nodes.tbody, tgroup[-1])
-        rows = cast(List[nodes.row], tbody)
+        rows = cast(list[nodes.row], tbody)
         for row in rows:
             col1_entry = cast(nodes.entry, row[0])
             par = cast(nodes.paragraph, col1_entry[0])
@@ -148,7 +153,7 @@ class FakeApplication:
         self.extensions: dict[str, Extension] = {}
         self.srcdir = None
         self.config = Config()
-        self.project = Project(None, None)
+        self.project = Project('', {})
         self.registry = SphinxComponentRegistry()
 
 
@@ -158,7 +163,7 @@ class FakeDirective(DocumenterBridge):
         document = Struct(settings=settings)
         app = FakeApplication()
         app.config.add('autodoc_class_signature', 'mixed', True, None)
-        env = BuildEnvironment(app)  # type: ignore
+        env = BuildEnvironment(app)  # type: ignore[arg-type]
         state = Struct(document=document)
         super().__init__(env, None, Options(), 0, state)
 
@@ -283,7 +288,7 @@ class Autosummary(SphinxDirective):
                     else:
                         errors = exc.exceptions + [exc2]
 
-                    raise ImportExceptionGroup(exc.args[0], errors)
+                    raise ImportExceptionGroup(exc.args[0], errors) from None
 
     def create_documenter(self, app: Sphinx, obj: Any,
                           parent: Any, full_name: str) -> Documenter:
@@ -625,7 +630,7 @@ def get_import_prefixes_from_env(env: BuildEnvironment) -> list[str | None]:
 
 
 def import_by_name(
-    name: str, prefixes: list[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.
@@ -668,7 +673,7 @@ def _import_by_name(name: str, grouped_exception: bool = True) -> tuple[Any, Any
 
         # ... then as MODNAME, MODNAME.OBJ1, MODNAME.OBJ1.OBJ2, ...
         last_j = 0
-        modname = None
+        modname = ''
         for j in reversed(range(1, len(name_parts) + 1)):
             last_j = j
             modname = '.'.join(name_parts[:j])
@@ -692,12 +697,12 @@ def _import_by_name(name: str, grouped_exception: bool = True) -> tuple[Any, Any
     except (ValueError, ImportError, AttributeError, KeyError) as exc:
         errors.append(exc)
         if grouped_exception:
-            raise ImportExceptionGroup('', errors)
+            raise ImportExceptionGroup('', errors) from None  # NoQA: EM101
         else:
             raise ImportError(*exc.args) from exc
 
 
-def import_ivar_by_name(name: str, prefixes: list[str | None] = [None],
+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.
@@ -739,6 +744,7 @@ class AutoLink(SphinxRole):
     """
     def run(self) -> tuple[list[Node], list[system_message]]:
         pyobj_role = self.env.get_domain('py').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)
         if errors: