Sphinx 8.0.2__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/ext/autodoc/__init__.py

@@ -11,7 +11,7 @@ import functools
 import operator
 import re
 from inspect import Parameter, Signature
-from typing import TYPE_CHECKING, Any, ClassVar, NewType, TypeVar
+from typing import TYPE_CHECKING, Any, NewType, TypeVar
 
 from docutils.statemachine import StringList
 
@@ -42,11 +42,19 @@ from sphinx.util.typing import (
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator, Sequence
     from types import ModuleType
+    from typing import ClassVar, Literal, TypeAlias
 
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
     from sphinx.ext.autodoc.directive import DocumenterBridge
 
+    _AutodocObjType = Literal[
+        'module', 'class', 'exception', 'function', 'method', 'attribute'
+    ]
+    _AutodocProcessDocstringListener: TypeAlias = Callable[
+        [Sphinx, _AutodocObjType, str, Any, dict[str, bool], list[str]], None
+    ]
+
 logger = logging.getLogger(__name__)
 
 
@@ -177,7 +185,9 @@ def merge_members_option(options: dict) -> None:
 
 # Some useful event listener factories for autodoc-process-docstring.
 
-def cut_lines(pre: int, post: int = 0, what: str | None = None) -> Callable:
+def cut_lines(
+    pre: int, post: int = 0, what: str | list[str] | None = None
+) -> _AutodocProcessDocstringListener:
     """Return a listener that removes the first *pre* and last *post*
     lines of every docstring.  If *what* is a sequence of strings,
     only docstrings of a type in *what* will be processed.
@@ -185,13 +195,21 @@ def cut_lines(pre: int, post: int = 0, what: str | None = None) -> Callable:
     Use like this (e.g. in the ``setup()`` function of :file:`conf.py`)::
 
        from sphinx.ext.autodoc import cut_lines
-       app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
+       app.connect('autodoc-process-docstring', cut_lines(4, what={'module'}))
 
     This can (and should) be used in place of :confval:`automodule_skip_lines`.
     """
-    def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: list[str],
-                ) -> None:
-        if what and what_ not in what:
+    what_unique = frozenset(what or ())
+
+    def process(
+        app: Sphinx,
+        what_: _AutodocObjType,
+        name: str,
+        obj: Any,
+        options: dict[str, bool],
+        lines: list[str],
+    ) -> None:
+        if what_ not in what_unique:
             return
         del lines[:pre]
         if post:
@@ -210,7 +228,7 @@ def between(
     what: Sequence[str] | None = None,
     keepempty: bool = False,
     exclude: bool = False,
-) -> Callable:
+) -> _AutodocProcessDocstringListener:
     """Return a listener that either keeps, or if *exclude* is True excludes,
     lines between lines that match the *marker* regular expression.  If no line
     matches, the resulting docstring would be empty, so no change will be made
@@ -221,8 +239,14 @@ def between(
     """
     marker_re = re.compile(marker)
 
-    def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: list[str],
-                ) -> None:
+    def process(
+        app: Sphinx,
+        what_: _AutodocObjType,
+        name: str,
+        obj: Any,
+        options: dict[str, bool],
+        lines: list[str],
+    ) -> None:
         if what and what_ not in what:
             return
         deleted = 0
@@ -247,7 +271,7 @@ def between(
 
 # This class is used only in ``sphinx.ext.autodoc.directive``,
 # But we define this class here to keep compatibility (see #4538)
-class Options(dict):
+class Options(dict[str, Any]):
     """A dict/attribute hybrid that returns None on nonexisting keys."""
 
     def copy(self) -> Options:
@@ -415,9 +439,10 @@ class Documenter:
         """
         with mock(self.config.autodoc_mock_imports):
             try:
-                ret = import_object(self.modname, self.objpath, self.objtype,
-                                    attrgetter=self.get_attr,
-                                    warningiserror=self.config.autodoc_warningiserror)
+                ret = import_object(
+                    self.modname, self.objpath, self.objtype,
+                    attrgetter=self.get_attr,
+                )
                 self.module, self.parent, self.object_name, self.object = ret
                 if ismock(self.object):
                     self.object = undecorate(self.object)
@@ -1076,7 +1101,8 @@ class ModuleDocumenter(Documenter):
                 else:
                     logger.warning(__('missing attribute mentioned in :members: option: '
                                       'module %s, attribute %s'),
-                                   safe_getattr(self.object, '__name__', '???', name),
+                                   safe_getattr(self.object, '__name__', '???'),
+                                   name,
                                    type='autodoc')
             return False, ret
 
@@ -1960,7 +1986,7 @@ class UninitializedGlobalVariableMixin(DataDocumenterMixinBase):
             # annotation only instance variable (PEP-526)
             try:
                 with mock(self.config.autodoc_mock_imports):
-                    parent = import_module(self.modname, self.config.autodoc_warningiserror)
+                    parent = import_module(self.modname)
                     annotations = get_type_hints(parent, None,
                                                  self.config.autodoc_type_aliases,
                                                  include_extras=True)
@@ -2455,9 +2481,10 @@ class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
         except ImportError as exc:
             try:
                 with mock(self.config.autodoc_mock_imports):
-                    ret = import_object(self.modname, self.objpath[:-1], 'class',
-                                        attrgetter=self.get_attr,  # type: ignore[attr-defined]
-                                        warningiserror=self.config.autodoc_warningiserror)
+                    ret = import_object(
+                        self.modname, self.objpath[:-1], 'class',
+                        attrgetter=self.get_attr,  # type: ignore[attr-defined]
+                    )
                     parent = ret[3]
                     if self.is_runtime_instance_attribute(parent):
                         self.object = self.RUNTIME_INSTANCE_ATTRIBUTE
@@ -2502,16 +2529,17 @@ class UninitializedInstanceAttributeMixin(DataDocumenterMixinBase):
         return self.objpath[-1] in annotations
 
     def import_object(self, raiseerror: bool = False) -> bool:
-        """Check the exisitence of uninitialized instance attribute when failed to import
+        """Check the existence of uninitialized instance attribute when failed to import
         the attribute.
         """
         try:
             return super().import_object(raiseerror=True)  # type: ignore[misc]
         except ImportError as exc:
             try:
-                ret = import_object(self.modname, self.objpath[:-1], 'class',
-                                    attrgetter=self.get_attr,  # type: ignore[attr-defined]
-                                    warningiserror=self.config.autodoc_warningiserror)
+                ret = import_object(
+                    self.modname, self.objpath[:-1], 'class',
+                    attrgetter=self.get_attr,  # type: ignore[attr-defined]
+                )
                 parent = ret[3]
                 if self.is_uninitialized_instance_attribute(parent):
                     self.object = UNINITIALIZED_ATTR
@@ -2722,7 +2750,7 @@ class PropertyDocumenter(DocstringStripSignatureMixin,  # type: ignore[misc]
             return False
 
     def import_object(self, raiseerror: bool = False) -> bool:
-        """Check the exisitence of uninitialized instance attribute when failed to import
+        """Check the existence of uninitialized instance attribute when failed to import
         the attribute.
         """
         ret = super().import_object(raiseerror)
@@ -2795,7 +2823,7 @@ class PropertyDocumenter(DocstringStripSignatureMixin,  # type: ignore[misc]
 
 def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs: Any) -> Any:
     """Alternative getattr() for types"""
-    for typ, func in app.registry.autodoc_attrgettrs.items():
+    for typ, func in app.registry.autodoc_attrgetters.items():
         if isinstance(obj, typ):
             return func(obj, name, *defargs)
 

sphinx/ext/autodoc/importer.py

@@ -137,24 +137,22 @@ def unmangle(subject: Any, name: str) -> str | None:
     return name
 
 
-def import_module(modname: str, warningiserror: bool = False) -> Any:
+def import_module(modname: str) -> Any:
     """Call importlib.import_module(modname), convert exceptions to ImportError."""
     try:
-        with logging.skip_warningiserror(not warningiserror):
-            return importlib.import_module(modname)
+        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.
         raise ImportError(exc, traceback.format_exc()) from exc
 
 
-def _reload_module(module: ModuleType, warningiserror: bool = False) -> Any:
+def _reload_module(module: ModuleType) -> Any:
     """
     Call importlib.reload(module), convert exceptions to ImportError
     """
     try:
-        with logging.skip_warningiserror(not warningiserror):
-            return importlib.reload(module)
+        return importlib.reload(module)
     except BaseException as exc:
         # Importing modules may cause any side effects, including
         # SystemExit, so we need to catch all errors.
@@ -162,8 +160,7 @@ def _reload_module(module: ModuleType, warningiserror: bool = False) -> Any:
 
 
 def import_object(modname: str, objpath: list[str], objtype: str = '',
-                  attrgetter: Callable[[Any, str], Any] = safe_getattr,
-                  warningiserror: bool = False) -> Any:
+                  attrgetter: Callable[[Any, str], Any] = safe_getattr) -> Any:
     if objpath:
         logger.debug('[autodoc] from %s import %s', modname, '.'.join(objpath))
     else:
@@ -176,7 +173,7 @@ def import_object(modname: str, objpath: list[str], objtype: str = '',
         while module is None:
             try:
                 original_module_names = frozenset(sys.modules)
-                module = import_module(modname, warningiserror=warningiserror)
+                module = import_module(modname)
                 if os.environ.get('SPHINX_AUTODOC_RELOAD_MODULES'):
                     new_modules = [m for m in sys.modules if m not in original_module_names]
                     # Try reloading modules with ``typing.TYPE_CHECKING == True``.

sphinx/ext/autosectionlabel.py

@@ -7,7 +7,6 @@ from typing import TYPE_CHECKING, cast
 from docutils import nodes
 
 import sphinx
-from sphinx.domains.std import StandardDomain
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.nodes import clean_astext
@@ -31,7 +30,7 @@ def get_node_depth(node: Node) -> int:
 
 
 def register_sections_as_label(app: Sphinx, document: Node) -> None:
-    domain = cast(StandardDomain, app.env.get_domain('std'))
+    domain = app.env.domains.standard_domain
     for node in document.findall(nodes.section):
         if (app.config.autosectionlabel_maxdepth and
                 get_node_depth(node) >= app.config.autosectionlabel_maxdepth):

sphinx/ext/autosummary/__init__.py

@@ -151,6 +151,8 @@ def autosummary_table_visit_html(self: HTML5Translator, node: autosummary_table)
 # -- autodoc integration -------------------------------------------------------
 
 class FakeApplication:
+    verbosity = 0
+
     def __init__(self) -> None:
         self.doctreedir = None
         self.events = None
@@ -754,7 +756,7 @@ class AutoLink(SphinxRole):
     """
 
     def run(self) -> tuple[list[Node], list[system_message]]:
-        pyobj_role = self.env.get_domain('py').role('obj')
+        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)

sphinx/ext/autosummary/generate.py

@@ -71,7 +71,7 @@ class DummyApplication:
         self.translator = translator
         self.verbosity = 0
         self._warncount = 0
-        self.warningiserror = False
+        self._exception_on_warning = False
 
         self.config.add('autosummary_context', {}, 'env', ())
         self.config.add('autosummary_filename_map', {}, 'env', ())
@@ -131,7 +131,9 @@ class AutosummaryRenderer:
             msg = 'Expected a Sphinx application object!'
             raise ValueError(msg)
 
-        system_templates_path = [os.path.join(package_dir, 'ext', 'autosummary', 'templates')]
+        system_templates_path = [
+            os.path.join(package_dir, 'ext', 'autosummary', 'templates')
+        ]
         loader = SphinxTemplateLoader(
             app.srcdir, app.config.templates_path, system_templates_path
         )
@@ -297,7 +299,9 @@ def generate_autosummary_content(
         ns['members'] = scanner.scan(imported_members)
 
         respect_module_all = not app.config.autosummary_ignore_module_all
-        imported_members = imported_members or ('__all__' in dir(obj) and respect_module_all)
+        imported_members = imported_members or (
+            '__all__' in dir(obj) and respect_module_all
+        )
 
         ns['functions'], ns['all_functions'] = _get_members(
             doc, app, obj, {'function'}, imported=imported_members
@@ -378,7 +382,9 @@ def generate_autosummary_content(
 
 def _skip_member(app: Sphinx, obj: Any, name: str, objtype: str) -> bool:
     try:
-        return app.emit_firstresult('autodoc-skip-member', objtype, name, obj, False, {})
+        return app.emit_firstresult(
+            'autodoc-skip-member', objtype, name, obj, False, {}
+        )
     except Exception as exc:
         logger.warning(
             __(
@@ -465,7 +471,11 @@ def _get_module_attrs(name: str, members: Any) -> tuple[list[str], list[str]]:
 
 
 def _get_modules(
-    obj: Any, *, skip: Sequence[str], name: str, public_members: Sequence[str] | None = None
+    obj: Any,
+    *,
+    skip: Sequence[str],
+    name: str,
+    public_members: Sequence[str] | None = None,
 ) -> tuple[list[str], list[str]]:
     items: list[str] = []
     public: list[str] = []
@@ -511,7 +521,9 @@ def generate_autosummary_docs(
     showed_sources = sorted(sources)
     if len(showed_sources) > 20:
         showed_sources = showed_sources[:10] + ['...'] + showed_sources[-10:]
-    logger.info(__('[autosummary] generating autosummary for: %s'), ', '.join(showed_sources))
+    logger.info(
+        __('[autosummary] generating autosummary for: %s'), ', '.join(showed_sources)
+    )
 
     if output_dir:
         logger.info(__('[autosummary] writing to %s'), output_dir)
@@ -710,9 +722,7 @@ def find_autosummary_in_lines(
 
             m = autosummary_item_re.match(line)
             if m:
-                name = m.group(1).strip()
-                if name.startswith('~'):
-                    name = name[1:]
+                name = m.group(1).strip().removeprefix('~')
                 if current_module and not name.startswith(current_module + '.'):
                     name = f'{current_module}.{name}'
                 documented.append(AutosummaryEntry(name, toctree, template, recursive))
@@ -736,7 +746,9 @@ def find_autosummary_in_lines(
         if m:
             current_module = m.group(1).strip()
             # recurse into the automodule docstring
-            documented.extend(find_autosummary_in_docstring(current_module, filename=filename))
+            documented.extend(
+                find_autosummary_in_docstring(current_module, filename=filename)
+            )
             continue
 
         m = module_re.match(line)
@@ -789,7 +801,7 @@ The format of the autosummary directive is documented in the
         action='store',
         dest='suffix',
         default='rst',
-        help=__('default suffix for files (default: ' '%(default)s)'),
+        help=__('default suffix for files (default: %(default)s)'),
     )
     parser.add_argument(
         '-t',
@@ -797,7 +809,7 @@ The format of the autosummary directive is documented in the
         action='store',
         dest='templates',
         default=None,
-        help=__('custom template directory (default: ' '%(default)s)'),
+        help=__('custom template directory (default: %(default)s)'),
     )
     parser.add_argument(
         '-i',
@@ -805,7 +817,7 @@ The format of the autosummary directive is documented in the
         action='store_true',
         dest='imported_members',
         default=False,
-        help=__('document imported members (default: ' '%(default)s)'),
+        help=__('document imported members (default: %(default)s)'),
     )
     parser.add_argument(
         '-a',
@@ -823,7 +835,9 @@ The format of the autosummary directive is documented in the
         action='store_true',
         dest='remove_old',
         default=False,
-        help=__('Remove existing files in the output directory that were not generated'),
+        help=__(
+            'Remove existing files in the output directory that were not generated'
+        ),
     )
 
     return parser

sphinx/ext/coverage.py

@@ -192,7 +192,7 @@ class CoverageBuilder(Builder):
     def get_outdated_docs(self) -> str:
         return 'coverage overview'
 
-    def write(self, *ignored: Any) -> None:
+    def write_documents(self, _docnames: Set[str]) -> None:
         self.py_undoc: dict[str, dict[str, Any]] = {}
         self.py_undocumented: dict[str, Set[str]] = {}
         self.py_documented: dict[str, Set[str]] = {}
@@ -205,7 +205,7 @@ class CoverageBuilder(Builder):
 
     def build_c_coverage(self) -> None:
         c_objects = {}
-        for obj in self.env.domains['c'].get_objects():
+        for obj in self.env.domains.c_domain.get_objects():
             c_objects[obj[2]] = obj[1]
         for filename in self.c_sourcefiles:
             undoc: set[tuple[str, str]] = set()
@@ -241,7 +241,7 @@ class CoverageBuilder(Builder):
                 for typ, name in sorted(undoc):
                     op.write(' * %-50s [%9s]\n' % (name, typ))
                     if self.config.coverage_show_missing_items:
-                        if self.app.quiet or self.app.warningiserror:
+                        if self.app.quiet:
                             logger.warning(__('undocumented c api: %s [%s] in file %s'),
                                            name, typ, filename)
                         else:
@@ -423,7 +423,7 @@ class CoverageBuilder(Builder):
                         op.write('Functions:\n')
                         op.writelines(' * %s\n' % x for x in undoc['funcs'])
                         if self.config.coverage_show_missing_items:
-                            if self.app.quiet or self.app.warningiserror:
+                            if self.app.quiet:
                                 for func in undoc['funcs']:
                                     logger.warning(
                                         __('undocumented python function: %s :: %s'),
@@ -440,7 +440,7 @@ class CoverageBuilder(Builder):
                             if not methods:
                                 op.write(' * %s\n' % class_name)
                                 if self.config.coverage_show_missing_items:
-                                    if self.app.quiet or self.app.warningiserror:
+                                    if self.app.quiet:
                                         logger.warning(
                                             __('undocumented python class: %s :: %s'),
                                             name, class_name)
@@ -452,10 +452,10 @@ class CoverageBuilder(Builder):
                                 op.write(' * %s -- missing methods:\n\n' % class_name)
                                 op.writelines('   - %s\n' % x for x in methods)
                                 if self.config.coverage_show_missing_items:
-                                    if self.app.quiet or self.app.warningiserror:
+                                    if self.app.quiet:
                                         for meth in methods:
                                             logger.warning(
-                                                __('undocumented python method:' +
+                                                __('undocumented python method:'
                                                    ' %s :: %s :: %s'),
                                                 name, class_name, meth)
                                     else:

sphinx/ext/doctest.py

@@ -27,7 +27,7 @@ from sphinx.util.docutils import SphinxDirective
 from sphinx.util.osutil import relpath
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Sequence
+    from collections.abc import Callable, Set
 
     from docutils.nodes import Element, Node, TextElement
 
@@ -322,7 +322,7 @@ class DocTestBuilder(Builder):
         self.outfile.write(text)
 
     def _warn_out(self, text: str) -> None:
-        if self.app.quiet or self.app.warningiserror:
+        if self.app.quiet:
             logger.warning(text)
         else:
             logger.info(text, nonl=True)
@@ -355,13 +355,9 @@ Doctest summary
         if self.total_failures or self.setup_failures or self.cleanup_failures:
             self.app.statuscode = 1
 
-    def write(self, build_docnames: Iterable[str] | None, updated_docnames: Sequence[str],
-              method: str = 'update') -> None:
-        if build_docnames is None:
-            build_docnames = sorted(self.env.all_docs)
-
+    def write_documents(self, docnames: Set[str]) -> None:
         logger.info(bold('running tests...'))
-        for docname in build_docnames:
+        for docname in sorted(docnames):
             # no need to resolve the doctree
             doctree = self.env.get_doctree(docname)
             self.test_doc(docname, doctree)

sphinx/ext/duration.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import time
 from itertools import islice
 from operator import itemgetter
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING
 
 import sphinx
 from sphinx.domains import Domain
@@ -13,6 +13,7 @@ from sphinx.locale import __
 from sphinx.util import logging
 
 if TYPE_CHECKING:
+    from collections.abc import Set
     from typing import TypedDict
 
     from docutils import nodes
@@ -43,7 +44,7 @@ class DurationDomain(Domain):
     def clear_doc(self, docname: str) -> None:
         self.reading_durations.pop(docname, None)
 
-    def merge_domaindata(self, docnames: list[str], otherdata: _DurationDomainData) -> None:  # type: ignore[override]
+    def merge_domaindata(self, docnames: Set[str], otherdata: _DurationDomainData) -> None:  # type: ignore[override]
         other_reading_durations = otherdata.get('reading_durations', {})
         docnames_set = frozenset(docnames)
         for docname, duration in other_reading_durations.items():
@@ -56,7 +57,7 @@ def on_builder_inited(app: Sphinx) -> None:
 
     This clears the results of the last build.
     """
-    domain = cast(DurationDomain, app.env.get_domain('duration'))
+    domain = app.env.domains['duration']
     domain.clear()
 
 
@@ -69,13 +70,13 @@ def on_doctree_read(app: Sphinx, doctree: nodes.document) -> None:
     """Record a reading duration."""
     started_at = app.env.temp_data['started_at']
     duration = time.monotonic() - started_at
-    domain = cast(DurationDomain, app.env.get_domain('duration'))
+    domain = app.env.domains['duration']
     domain.note_reading_duration(duration)
 
 
 def on_build_finished(app: Sphinx, error: Exception) -> None:
     """Display duration ranking on the current build."""
-    domain = cast(DurationDomain, app.env.get_domain('duration'))
+    domain = app.env.domains['duration']
     if not domain.reading_durations:
         return
     durations = sorted(domain.reading_durations.items(), key=itemgetter(1), reverse=True)

sphinx/ext/inheritance_diagram.py

@@ -359,7 +359,7 @@ class InheritanceDiagram(SphinxDirective):
         node = inheritance_diagram()
         node.document = self.state.document
         class_names = self.arguments[0].split()
-        class_role = self.env.get_domain('py').role('class')
+        class_role = self.env.domains.python_domain.role('class')
         # Store the original content for use as a hash
         node['parts'] = self.options.get('parts', 0)
         node['content'] = ', '.join(class_names)

sphinx/ext/intersphinx/_cli.py

@@ -10,9 +10,11 @@ from sphinx.ext.intersphinx._load import _fetch_inventory
 def inspect_main(argv: list[str], /) -> int:
     """Debug functionality to print out an inventory"""
     if len(argv) < 1:
-        print('Print out an inventory file.\n'
-              'Error: must specify local path or URL to an inventory file.',
-              file=sys.stderr)
+        print(
+            'Print out an inventory file.\n'
+            'Error: must specify local path or URL to an inventory file.',
+            file=sys.stderr,
+        )
         return 1
 
     class MockConfig:
@@ -27,7 +29,7 @@ def inspect_main(argv: list[str], /) -> int:
             target_uri='',
             inv_location=filename,
             config=MockConfig(),  # type: ignore[arg-type]
-            srcdir=''  # type: ignore[arg-type]
+            srcdir='',  # type: ignore[arg-type]
         )
         for key in sorted(inv_data or {}):
             print(key)