Sphinx 7.2.5__py3-none-any.whl → 7.3.0__py3-none-any.whl

sphinx/deprecation.py

@@ -19,23 +19,32 @@ RemovedInNextVersionWarning = RemovedInSphinx80Warning
 def _deprecation_warning(
     module: str,
     attribute: str,
-    canonical_name: str,
+    canonical_name: str = '',
     *,
     remove: tuple[int, int],
+    raises: bool = False,
 ) -> None:
-    """Helper function for module-level deprecations using __getattr__
+    """Helper function for module-level deprecations using ``__getattr__``.
 
-    Exemplar usage:
+    :param module: The module containing a deprecated object.
+    :param attribute: The name of the deprecated object.
+    :param canonical_name: Optional fully-qualified name for its replacement.
+    :param remove: Target version for removal.
+    :param raises: Indicate whether to raise an exception instead of a warning.
 
-    .. code:: python
+    When *raises* is ``True``, an :exc:`AttributeError` is raised instead
+    of emitting a warning so that it is easy to locate deprecated objects
+    in tests that could suppress deprecation warnings.
 
-       # deprecated name -> (object to return, canonical path or empty string)
+    Usage::
+
+       # deprecated name -> (object to return, canonical path or empty string, removal version)
        _DEPRECATED_OBJECTS = {
            'deprecated_name': (object_to_return, 'fully_qualified_replacement_name', (8, 0)),
        }
 
 
-       def __getattr__(name):
+       def __getattr__(name: str) -> Any:
            if name not in _DEPRECATED_OBJECTS:
                msg = f'module {__name__!r} has no attribute {name!r}'
                raise AttributeError(msg)
@@ -46,7 +55,6 @@ def _deprecation_warning(
            _deprecation_warning(__name__, name, canonical_name, remove=remove)
            return deprecated_object
     """
-
     if remove == (8, 0):
         warning_class: type[Warning] = RemovedInSphinx80Warning
     elif remove == (9, 0):
@@ -55,12 +63,14 @@ def _deprecation_warning(
         msg = f'removal version {remove!r} is invalid!'
         raise RuntimeError(msg)
 
-    qualified_name = f'{module}.{attribute}'
+    qualname = f'{module}.{attribute}'
     if canonical_name:
-        message = (f'The alias {qualified_name!r} is deprecated, '
-                   f'use {canonical_name!r} instead.')
+        message = f'The alias {qualname!r} is deprecated, use {canonical_name!r} instead.'
     else:
-        message = f'{qualified_name!r} is deprecated.'
+        message = f'{qualname!r} is deprecated.'
+
+    if raises:
+        raise AttributeError(message)
 
-    warnings.warn(message + " Check CHANGES for Sphinx API modifications.",
-                  warning_class, stacklevel=3)
+    message = f'{message} Check CHANGES for Sphinx API modifications.'
+    warnings.warn(message, warning_class, stacklevel=3)

sphinx/directives/__init__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
+from typing import TYPE_CHECKING, ClassVar, Generic, TypeVar, cast
 
 from docutils import nodes
 from docutils.parsers.rst import directives, roles
@@ -14,7 +14,7 @@ from sphinx.util import docutils
 from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import nested_parse_with_titles
-from sphinx.util.typing import OptionSpec  # NoQA: TCH001
+from sphinx.util.typing import ExtensionMetadata, OptionSpec  # NoQA: TCH001
 
 if TYPE_CHECKING:
     from docutils.nodes import Node
@@ -55,7 +55,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'no-index': directives.flag,
         'no-index-entry': directives.flag,
         'no-contents-entry': directives.flag,
@@ -118,7 +118,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
 
         *name* is whatever :meth:`handle_signature()` returned.
         """
-        return  # do nothing by default
+        pass  # do nothing by default
 
     def before_content(self) -> None:
         """
@@ -296,7 +296,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
             # If ``:no-index:`` is set, or there are no ids on the node
             # or any of its children, then just return the index node,
             # as Docutils expects a target node to have at least one id.
-            if node_ids := [node_id for el in node.findall(nodes.Element)
+            if node_ids := [node_id for el in node.findall(nodes.Element)  # type: ignore[var-annotated]
                             for node_id in el.get('ids', ())]:
                 target_node = nodes.target(ids=node_ids)
                 self.set_source_info(target_node)
@@ -320,7 +320,7 @@ class DefaultRole(SphinxDirective):
         role_name = self.arguments[0]
         role, messages = roles.role(role_name, self.state_machine.language,
                                     self.lineno, self.state.reporter)
-        if role:  # type: ignore[truthy-function]
+        if role:
             docutils.register_role('', role)  # type: ignore[arg-type]
             self.env.temp_data['default_role'] = role_name
         else:
@@ -342,7 +342,7 @@ class DefaultDomain(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         domain_name = self.arguments[0].lower()
@@ -356,7 +356,7 @@ class DefaultDomain(SphinxDirective):
         return []
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_config_value("strip_signature_backslash", False, 'env')
     directives.register_directive('default-role', DefaultRole)
     directives.register_directive('default-domain', DefaultDomain)

sphinx/directives/code.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import sys
 import textwrap
 from difflib import unified_diff
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, ClassVar
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -20,7 +20,7 @@ if TYPE_CHECKING:
 
     from sphinx.application import Sphinx
     from sphinx.config import Config
-    from sphinx.util.typing import OptionSpec
+    from sphinx.util.typing import ExtensionMetadata, OptionSpec
 
 logger = logging.getLogger(__name__)
 
@@ -35,7 +35,7 @@ class Highlight(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'force': directives.flag,
         'linenothreshold': directives.positive_int,
     }
@@ -102,7 +102,7 @@ class CodeBlock(SphinxDirective):
     required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = False
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'force': directives.flag,
         'linenos': directives.flag,
         'dedent': optional_int,
@@ -287,7 +287,7 @@ class LiteralIncludeReader:
                                         'set of "lines"'))
 
             lines = [lines[n] for n in linelist if n < len(lines)]
-            if lines == []:
+            if not lines:
                 raise ValueError(__('Line spec %r: no lines pulled from include file %r') %
                                  (linespec, self.filename))
 
@@ -393,7 +393,7 @@ class LiteralInclude(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'dedent': optional_int,
         'linenos': directives.flag,
         'lineno-start': int,
@@ -469,7 +469,7 @@ class LiteralInclude(SphinxDirective):
             return [document.reporter.warning(exc, line=self.lineno)]
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     directives.register_directive('highlight', Highlight)
     directives.register_directive('code-block', CodeBlock)
     directives.register_directive('sourcecode', CodeBlock)

sphinx/directives/other.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import re
 from os.path import abspath, relpath
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -13,7 +13,7 @@ from docutils.parsers.rst.directives.misc import Include as BaseInclude
 from docutils.statemachine import StateMachine
 
 from sphinx import addnodes
-from sphinx.domains.changeset import VersionChange  # noqa: F401  # for compatibility
+from sphinx.domains.changeset import VersionChange  # NoQA: F401  # for compatibility
 from sphinx.domains.std import StandardDomain
 from sphinx.locale import _, __
 from sphinx.util import docname_join, logging, url_re
@@ -22,10 +22,12 @@ from sphinx.util.matching import Matcher, patfilter
 from sphinx.util.nodes import explicit_title_re
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from docutils.nodes import Element, Node
 
     from sphinx.application import Sphinx
-    from sphinx.util.typing import OptionSpec
+    from sphinx.util.typing import ExtensionMetadata, OptionSpec
 
 
 glob_re = re.compile(r'.*[*?\[].*')
@@ -43,6 +45,7 @@ class TocTree(SphinxDirective):
     Directive to notify Sphinx about the hierarchical structure of the docs,
     and to include a table-of-contents like tree in the current document.
     """
+
     has_content = True
     required_arguments = 0
     optional_arguments = 0
@@ -173,11 +176,12 @@ class Author(SphinxDirective):
     Directive to give the name of the author of the current document
     or section. Shown in the output only if the show_authors option is on.
     """
+
     has_content = False
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         if not self.config.show_authors:
@@ -206,6 +210,7 @@ class SeeAlso(BaseAdmonition):
     """
     An admonition mentioning things to look at as reference.
     """
+
     node_class = addnodes.seealso
 
 
@@ -213,11 +218,12 @@ class TabularColumns(SphinxDirective):
     """
     Directive to give an explicit tabulary column definition to LaTeX.
     """
+
     has_content = False
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         node = addnodes.tabular_col_spec()
@@ -230,11 +236,12 @@ class Centered(SphinxDirective):
     """
     Directive to create a centered line of bold text.
     """
+
     has_content = False
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         if not self.arguments:
@@ -252,11 +259,12 @@ class Acks(SphinxDirective):
     """
     Directive for a list of names.
     """
+
     has_content = True
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         node = addnodes.acks()
@@ -274,11 +282,12 @@ class HList(SphinxDirective):
     """
     Directive for a list that gets compacted horizontally.
     """
+
     has_content = True
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'columns': int,
     }
 
@@ -311,11 +320,12 @@ class Only(SphinxDirective):
     """
     Directive to only include text if the given tag(s) are enabled.
     """
+
     has_content = True
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         node = addnodes.only()
@@ -371,14 +381,14 @@ class Include(BaseInclude, SphinxDirective):
     "correctly", i.e. relative to source directory.
     """
 
-    def run(self) -> list[Node]:
+    def run(self) -> Sequence[Node]:
 
         # To properly emit "include-read" events from included RST text,
         # we must patch the ``StateMachine.insert_input()`` method.
         # In the future, docutils will hopefully offer a way for Sphinx
         # to provide the RST parser to use
         # when parsing RST text that comes in via Include directive.
-        def _insert_input(include_lines, source):
+        def _insert_input(include_lines: list[str], source: str) -> None:
             # First, we need to combine the lines back into text so that
             # we can send it with the include-read event.
             # In docutils 0.18 and later, there are two lines at the end
@@ -405,7 +415,7 @@ class Include(BaseInclude, SphinxDirective):
         # Only enable this patch if there are listeners for 'include-read'.
         if self.env.app.events.listeners.get('include-read'):
             # See https://github.com/python/mypy/issues/2427 for details on the mypy issue
-            self.state_machine.insert_input = _insert_input  # type: ignore[method-assign]
+            self.state_machine.insert_input = _insert_input
 
         if self.arguments[0].startswith('<') and \
            self.arguments[0].endswith('>'):
@@ -417,7 +427,7 @@ class Include(BaseInclude, SphinxDirective):
         return super().run()
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     directives.register_directive('toctree', TocTree)
     directives.register_directive('sectionauthor', Author)
     directives.register_directive('moduleauthor', Author)

sphinx/directives/patches.py

@@ -2,13 +2,13 @@ from __future__ import annotations
 
 import os
 from os import path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, ClassVar, cast
 
 from docutils import nodes
 from docutils.nodes import Node, make_id
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives import images, tables
-from docutils.parsers.rst.directives.misc import Meta  # type: ignore[attr-defined]
+from docutils.parsers.rst.directives.misc import Meta
 from docutils.parsers.rst.roles import set_classes
 
 from sphinx.directives import optional_int
@@ -21,7 +21,7 @@ from sphinx.util.osutil import SEP, os_path, relpath
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
-    from sphinx.util.typing import OptionSpec
+    from sphinx.util.typing import ExtensionMetadata, OptionSpec
 
 
 logger = logging.getLogger(__name__)
@@ -80,8 +80,9 @@ class Code(SphinxDirective):
 
     This is compatible with docutils' :rst:dir:`code` directive.
     """
+
     optional_arguments = 1
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'class': directives.class_option,
         'force': directives.flag,
         'name': directives.unchanged,
@@ -126,7 +127,7 @@ class MathDirective(SphinxDirective):
     required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = True
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'label': directives.unchanged,
         'name': directives.unchanged,
         'class': directives.class_option,
@@ -175,7 +176,7 @@ class MathDirective(SphinxDirective):
         ret.insert(0, target)
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     directives.register_directive('figure', Figure)
     directives.register_directive('meta', Meta)
     directives.register_directive('csv-table', CSVTable)

sphinx/domains/__init__.py

@@ -93,7 +93,7 @@ class Index(ABC):
     shortname: str | None = None
 
     def __init__(self, domain: Domain) -> None:
-        if self.name is None or self.localname is None:
+        if not self.name or self.localname is None:
             raise SphinxError('Index subclass %s has no valid name or localname'
                               % self.__class__.__name__)
         self.domain = domain
@@ -296,7 +296,7 @@ class Domain:
         """Remove traces of a document in the domain-specific inventories."""
         pass
 
-    def merge_domaindata(self, docnames: list[str], otherdata: dict) -> None:
+    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
         """Merge in data regarding *docnames* from a different domaindata
         inventory (coming from a subprocess in parallel builds).
         """