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

sphinx/application.py

@@ -10,15 +10,11 @@ import os
 import pickle
 import sys
 from collections import deque
-from collections.abc import Callable, Collection, Sequence  # NoQA: TCH003
 from io import StringIO
 from os import path
-from typing import IO, TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, overload
 
-from docutils.nodes import TextElement  # NoQA: TCH002
 from docutils.parsers.rst import Directive, roles
-from docutils.transforms import Transform  # NoQA: TCH002
-from pygments.lexer import Lexer  # NoQA: TCH002
 
 import sphinx
 from sphinx import locale, package_dir
@@ -41,14 +37,22 @@ from sphinx.util.osutil import ensuredir, relpath
 from sphinx.util.tags import Tags
 
 if TYPE_CHECKING:
+    from collections.abc import Callable, Collection, Iterable, Sequence, Set
+    from pathlib import Path
+    from typing import IO, Any, Final, Literal
+
     from docutils import nodes
     from docutils.nodes import Element, Node
     from docutils.parsers import Parser
+    from docutils.transforms import Transform
+    from pygments.lexer import Lexer
 
+    from sphinx import addnodes
     from sphinx.builders import Builder
     from sphinx.domains import Domain, Index
     from sphinx.environment.collectors import EnvironmentCollector
-    from sphinx.ext.autodoc import Documenter
+    from sphinx.ext.autodoc import Documenter, _AutodocProcessDocstringListener
+    from sphinx.ext.todo import todo_node
     from sphinx.extension import Extension
     from sphinx.roles import XRefRole
     from sphinx.search import SearchLanguage
@@ -134,7 +138,7 @@ class Sphinx:
     :ivar outdir: Directory for storing build documents.
     """
 
-    warningiserror: bool
+    warningiserror: Final = False
     _warncount: int
 
     def __init__(self, srcdir: str | os.PathLike[str], confdir: str | os.PathLike[str] | None,
@@ -144,7 +148,7 @@ class Sphinx:
                  freshenv: bool = False, warningiserror: bool = False,
                  tags: Sequence[str] = (),
                  verbosity: int = 0, parallel: int = 0, keep_going: bool = False,
-                 pdb: bool = False) -> None:
+                 pdb: bool = False, exception_on_warning: bool = False) -> None:
         """Initialize the Sphinx application.
 
         :param srcdir: The path to the source directory.
@@ -163,8 +167,9 @@ class Sphinx:
         :param verbosity: The verbosity level.
         :param parallel: The maximum number of parallel jobs to use
             when reading/writing documents.
-        :param keep_going: If true, continue processing when an error occurs.
+        :param keep_going: Unused.
         :param pdb: If true, enable the Python debugger on an exception.
+        :param exception_on_warning: If true, raise an exception on warnings.
         """
         self.phase = BuildPhase.INITIALIZATION
         self.verbosity = verbosity
@@ -203,19 +208,17 @@ class Sphinx:
         else:
             self._warning = warning
         self._warncount = 0
-        self.keep_going = warningiserror and keep_going
-        if self.keep_going:
-            self.warningiserror = False
-        else:
-            self.warningiserror = warningiserror
+        self.keep_going = bool(warningiserror)  # Unused
+        self._fail_on_warnings = bool(warningiserror)
         self.pdb = pdb
+        self._exception_on_warning = exception_on_warning
         logging.setup(self, self._status, self._warning)
 
         self.events = EventManager(self)
 
         # keep last few messages for traceback
         # This will be filled by sphinx.util.logging.LastMessagesWriter
-        self.messagelog: deque = deque(maxlen=10)
+        self.messagelog: deque[str] = deque(maxlen=10)
 
         # say hello to the world
         logger.info(bold(__('Running Sphinx v%s')), sphinx.__display_version__)
@@ -386,26 +389,31 @@ class Sphinx:
             self.events.emit('build-finished', err)
             raise
 
-        if self._warncount and self.keep_going:
-            self.statuscode = 1
-
-        status = (__('succeeded') if self.statuscode == 0
-                  else __('finished with problems'))
-        if self._warncount:
-            if self.warningiserror:
-                if self._warncount == 1:
-                    msg = __('build %s, %s warning (with warnings treated as errors).')
-                else:
-                    msg = __('build %s, %s warnings (with warnings treated as errors).')
+        if self._warncount == 0:
+            if self.statuscode != 0:
+                logger.info(bold(__('build finished with problems.')))
             else:
-                if self._warncount == 1:
-                    msg = __('build %s, %s warning.')
-                else:
-                    msg = __('build %s, %s warnings.')
-
-            logger.info(bold(msg), status, self._warncount)
+                logger.info(bold(__('build succeeded.')))
+        elif self._warncount == 1:
+            if self._fail_on_warnings:
+                self.statuscode = 1
+                msg = __('build finished with problems, 1 warning '
+                         '(with warnings treated as errors).')
+            elif self.statuscode != 0:
+                msg = __('build finished with problems, 1 warning.')
+            else:
+                msg = __('build succeeded, 1 warning.')
+            logger.info(bold(msg))
         else:
-            logger.info(bold(__('build %s.')), status)
+            if self._fail_on_warnings:
+                self.statuscode = 1
+                msg = __('build finished with problems, %s warnings '
+                         '(with warnings treated as errors).')
+            elif self.statuscode != 0:
+                msg = __('build finished with problems, %s warnings.')
+            else:
+                msg = __('build succeeded, %s warnings.')
+            logger.info(bold(msg), self._warncount)
 
         if self.statuscode == 0 and self.builder.epilog:
             logger.info('')
@@ -450,6 +458,319 @@ class Sphinx:
             req = f'{major}.{minor}'
             raise VersionRequirementError(req)
 
+    # ---- Core events -------------------------------------------------------
+
+    @overload
+    def connect(
+        self,
+        event: Literal['config-inited'],
+        callback: Callable[[Sphinx, Config], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['builder-inited'],
+        callback: Callable[[Sphinx], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['env-get-outdated'],
+        callback: Callable[
+            [Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]
+        ],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['env-before-read-docs'],
+        callback: Callable[[Sphinx, BuildEnvironment, list[str]], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['env-purge-doc'],
+        callback: Callable[[Sphinx, BuildEnvironment, str], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['source-read'],
+        callback: Callable[[Sphinx, str, list[str]], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['include-read'],
+        callback: Callable[[Sphinx, Path, str, list[str]], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['doctree-read'],
+        callback: Callable[[Sphinx, nodes.document], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['env-merge-info'],
+        callback: Callable[
+            [Sphinx, BuildEnvironment, list[str], BuildEnvironment], None
+        ],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['env-updated'],
+        callback: Callable[[Sphinx, BuildEnvironment], str],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['env-get-updated'],
+        callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['env-check-consistency'],
+        callback: Callable[[Sphinx, BuildEnvironment], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['write-started'],
+        callback: Callable[[Sphinx, Builder], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['doctree-resolved'],
+        callback: Callable[[Sphinx, nodes.document, str], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['missing-reference'],
+        callback: Callable[
+            [Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement],
+            nodes.reference | None,
+        ],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['warn-missing-reference'],
+        callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['build-finished'],
+        callback: Callable[[Sphinx, Exception | None], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    # ---- Events from builtin builders --------------------------------------
+
+    @overload
+    def connect(
+        self,
+        event: Literal['html-collect-pages'],
+        callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['html-page-context'],
+        callback: Callable[
+            [Sphinx, str, str, dict[str, Any], nodes.document], str | None
+        ],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['linkcheck-process-uri'],
+        callback: Callable[[Sphinx, str], str | None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    # ---- Events from builtin extensions-- ----------------------------------
+
+    @overload
+    def connect(
+        self,
+        event: Literal['object-description-transform'],
+        callback: Callable[[Sphinx, str, str, addnodes.desc_content], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    # ---- Events from first-party extensions --------------------------------
+
+    @overload
+    def connect(
+        self,
+        event: Literal['autodoc-process-docstring'],
+        callback: _AutodocProcessDocstringListener,
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['autodoc-before-process-signature'],
+        callback: Callable[[Sphinx, Any, bool], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['autodoc-process-signature'],
+        callback: Callable[
+            [
+                Sphinx,
+                Literal['module', 'class', 'exception', 'function', 'method', 'attribute'],
+                str,
+                Any,
+                dict[str, bool],
+                str | None,
+                str | None,
+            ],
+            tuple[str | None, str | None] | None,
+        ],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['autodoc-process-bases'],
+        callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['autodoc-skip-member'],
+        callback: Callable[
+            [
+                Sphinx,
+                Literal['module', 'class', 'exception', 'function', 'method', 'attribute'],
+                str,
+                Any,
+                bool,
+                dict[str, bool],
+            ],
+            bool,
+        ],
+        priority: int = 500
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['todo-defined'],
+        callback: Callable[[Sphinx, todo_node], None],
+        priority: int = 500,
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['viewcode-find-source'],
+        callback: Callable[
+            [Sphinx, str],
+            tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]],
+        ],
+        priority: int = 500,
+    ) -> int:
+        ...
+
+    @overload
+    def connect(
+        self,
+        event: Literal['viewcode-follow-imported'],
+        callback: Callable[[Sphinx, str, str], str | None],
+        priority: int = 500,
+    ) -> int:
+        ...
+
+    # ---- Catch-all ---------------------------------------------------------
+
+    @overload
+    def connect(
+        self,
+        event: str,
+        callback: Callable[..., Any],
+        priority: int = 500
+    ) -> int:
+        ...
+
     # event interface
     def connect(self, event: str, callback: Callable, priority: int = 500) -> int:
         """Register *callback* to be called when *event* is emitted.
@@ -845,7 +1166,7 @@ class Sphinx:
 
     def add_object_type(self, directivename: str, rolename: str, indextemplate: str = '',
                         parse_node: Callable | None = None,
-                        ref_nodeclass: type[TextElement] | None = None,
+                        ref_nodeclass: type[nodes.TextElement] | None = None,
                         objname: str = '', doc_field_types: Sequence = (),
                         override: bool = False,
                         ) -> None:
@@ -912,9 +1233,11 @@ class Sphinx:
                                       ref_nodeclass, objname, doc_field_types,
                                       override=override)
 
-    def add_crossref_type(self, directivename: str, rolename: str, indextemplate: str = '',
-                          ref_nodeclass: type[TextElement] | None = None, objname: str = '',
-                          override: bool = False) -> None:
+    def add_crossref_type(
+        self, directivename: str, rolename: str, indextemplate: str = '',
+        ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '',
+        override: bool = False,
+    ) -> None:
         """Register a new crossref object type.
 
         This method is very similar to :meth:`~Sphinx.add_object_type` except that the
@@ -1385,7 +1708,7 @@ class TemplateBridge:
         """
         return 0
 
-    def render(self, template: str, context: dict) -> None:
+    def render(self, template: str, context: dict[str, Any]) -> None:
         """Called by the builder to render a template given as a filename with
         a specified context (a Python dictionary).
         """