Sphinx 8.1.3__py3-none-any.whl → 8.2.0rc1__py3-none-any.whl

sphinx/util/docutils.py

@@ -4,22 +4,20 @@ from __future__ import annotations
 
 import os
 import re
-from collections.abc import Sequence  # NoQA: TCH003
 from contextlib import contextmanager
 from copy import copy
-from os import path
-from typing import IO, TYPE_CHECKING, Any, cast
+from pathlib import Path
+from typing import TYPE_CHECKING
 
 import docutils
 from docutils import nodes
 from docutils.io import FileOutput
 from docutils.parsers.rst import Directive, directives, roles
-from docutils.parsers.rst.states import Inliner  # NoQA: TCH002
-from docutils.statemachine import State, StateMachine, StringList
+from docutils.statemachine import StateMachine
 from docutils.utils import Reporter, unescape
 
 from sphinx.errors import SphinxError
-from sphinx.locale import _, __
+from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.parsing import nested_parse_to_nodes
 
@@ -29,17 +27,44 @@ report_re = re.compile(
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator  # NoQA: TCH003
-    from types import ModuleType
+    from collections.abc import Iterator, Sequence
+    from types import ModuleType, TracebackType
+    from typing import Any, Protocol
 
     from docutils.frontend import Values
     from docutils.nodes import Element, Node, system_message
+    from docutils.parsers.rst.states import Inliner
+    from docutils.statemachine import State, StringList
 
     from sphinx.builders import Builder
     from sphinx.config import Config
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import RoleFunction
 
+    class _LanguageModule(Protocol):
+        labels: dict[str, str]
+        author_separators: list[str]
+        bibliographic_fields: list[str]
+
+    class _DirectivesDispatcher(Protocol):
+        def __call__(
+            self,
+            directive_name: str,
+            language_module: _LanguageModule,
+            document: nodes.document,
+            /,
+        ) -> tuple[type[Directive] | None, list[system_message]]: ...
+
+    class _RolesDispatcher(Protocol):
+        def __call__(
+            self,
+            role_name: str,
+            language_module: _LanguageModule,
+            lineno: int,
+            reporter: Reporter,
+            /,
+        ) -> tuple[RoleFunction | None, list[system_message]]: ...
+
 
 additional_nodes: set[type[Element]] = set()
 
@@ -127,7 +152,7 @@ def patched_get_language() -> Iterator[None]:
     """Patch docutils.languages.get_language() temporarily.
 
     This ignores the second argument ``reporter`` to suppress warnings.
-    refs: https://github.com/sphinx-doc/sphinx/issues/3788
+    See: https://github.com/sphinx-doc/sphinx/issues/3788
     """
     from docutils.languages import get_language
 
@@ -153,7 +178,7 @@ def patched_rst_get_language() -> Iterator[None]:
     This should also work for old versions of docutils,
     because reporter is none by default.
 
-    refs: https://github.com/sphinx-doc/sphinx/issues/10179
+    See: https://github.com/sphinx-doc/sphinx/issues/10179
     """
     from docutils.parsers.rst.languages import get_language
 
@@ -171,25 +196,23 @@ def patched_rst_get_language() -> Iterator[None]:
 
 
 @contextmanager
-def using_user_docutils_conf(confdir: str | None) -> Iterator[None]:
+def using_user_docutils_conf(confdir: str | os.PathLike[str] | None) -> Iterator[None]:
     """Let docutils know the location of ``docutils.conf`` for Sphinx."""
     try:
-        docutilsconfig = os.environ.get('DOCUTILSCONFIG', None)
+        docutils_config = os.environ.get('DOCUTILSCONFIG', None)
         if confdir:
-            os.environ['DOCUTILSCONFIG'] = path.join(
-                path.abspath(confdir), 'docutils.conf'
-            )
-
+            docutils_conf_path = Path(confdir, 'docutils.conf').resolve()
+            os.environ['DOCUTILSCONFIG'] = str(docutils_conf_path)
         yield
     finally:
-        if docutilsconfig is None:
+        if docutils_config is None:
             os.environ.pop('DOCUTILSCONFIG', None)
         else:
-            os.environ['DOCUTILSCONFIG'] = docutilsconfig
+            os.environ['DOCUTILSCONFIG'] = docutils_config
 
 
 @contextmanager
-def patch_docutils(confdir: str | None = None) -> Iterator[None]:
+def patch_docutils(confdir: str | os.PathLike[str] | None = None) -> Iterator[None]:
     """Patch to docutils temporarily."""
     with (
         patched_get_language(),
@@ -207,14 +230,17 @@ class CustomReSTDispatcher:
     """
 
     def __init__(self) -> None:
-        self.directive_func: Callable = lambda *args: (None, [])
-        self.roles_func: Callable = lambda *args: (None, [])
+        self.directive_func: _DirectivesDispatcher = lambda *args: (None, [])
+        self.roles_func: _RolesDispatcher = lambda *args: (None, [])
 
     def __enter__(self) -> None:
         self.enable()
 
     def __exit__(
-        self, exc_type: type[Exception], exc_value: Exception, traceback: Any
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
     ) -> None:
         self.disable()
 
@@ -226,7 +252,7 @@ class CustomReSTDispatcher:
         roles.role = self.role  # type: ignore[assignment]
 
     def disable(self) -> None:
-        directives.directive = self.directive_func
+        directives.directive = self.directive_func  # type: ignore[assignment]
         roles.role = self.role_func
 
     def directive(
@@ -262,51 +288,44 @@ class sphinx_domains(CustomReSTDispatcher):
     """
 
     def __init__(self, env: BuildEnvironment) -> None:
-        self.env = env
+        self.domains = env.domains
+        self.current_document = env.current_document
         super().__init__()
 
-    def lookup_domain_element(self, type: str, name: str) -> Any:
-        """Lookup a markup element (directive or role), given its name which can
-        be a full name (with domain).
-        """
-        name = name.lower()
+    def directive(
+        self,
+        directive_name: str,
+        language_module: ModuleType,
+        document: nodes.document,
+    ) -> tuple[type[Directive] | None, list[system_message]]:
+        """Lookup a directive, given its name which can include a domain."""
+        directive_name = directive_name.lower()
         # explicit domain given?
-        if ':' in name:
-            domain_name, name = name.split(':', 1)
-            if domain_name in self.env.domains:
-                domain = self.env.get_domain(domain_name)
-                element = getattr(domain, type)(name)
+        if ':' in directive_name:
+            domain_name, _, name = directive_name.partition(':')
+            try:
+                domain = self.domains[domain_name]
+            except KeyError:
+                logger.warning(__('unknown directive name: %s'), directive_name)
+            else:
+                element = domain.directive(name)
                 if element is not None:
                     return element, []
-            else:
-                logger.warning(
-                    _('unknown directive or role name: %s:%s'), domain_name, name
-                )
         # else look in the default domain
         else:
-            def_domain = self.env.temp_data.get('default_domain')
-            if def_domain is not None:
-                element = getattr(def_domain, type)(name)
+            name = directive_name
+            default_domain = self.current_document.default_domain
+            if default_domain is not None:
+                element = default_domain.directive(name)
                 if element is not None:
                     return element, []
 
         # always look in the std domain
-        element = getattr(self.env.domains.standard_domain, type)(name)
+        element = self.domains.standard_domain.directive(name)
         if element is not None:
             return element, []
 
-        raise ElementLookupError
-
-    def directive(
-        self,
-        directive_name: str,
-        language_module: ModuleType,
-        document: nodes.document,
-    ) -> tuple[type[Directive] | None, list[system_message]]:
-        try:
-            return self.lookup_domain_element('directive', directive_name)
-        except ElementLookupError:
-            return super().directive(directive_name, language_module, document)
+        return super().directive(directive_name, language_module, document)
 
     def role(
         self,
@@ -315,10 +334,34 @@ class sphinx_domains(CustomReSTDispatcher):
         lineno: int,
         reporter: Reporter,
     ) -> tuple[RoleFunction, list[system_message]]:
-        try:
-            return self.lookup_domain_element('role', role_name)
-        except ElementLookupError:
-            return super().role(role_name, language_module, lineno, reporter)
+        """Lookup a role, given its name which can include a domain."""
+        role_name = role_name.lower()
+        # explicit domain given?
+        if ':' in role_name:
+            domain_name, _, name = role_name.partition(':')
+            try:
+                domain = self.domains[domain_name]
+            except KeyError:
+                logger.warning(__('unknown role name: %s'), role_name)
+            else:
+                element = domain.role(name)
+                if element is not None:
+                    return element, []
+        # else look in the default domain
+        else:
+            name = role_name
+            default_domain = self.current_document.default_domain
+            if default_domain is not None:
+                element = default_domain.role(name)
+                if element is not None:
+                    return element, []
+
+        # always look in the std domain
+        element = self.domains.standard_domain.role(name)
+        if element is not None:
+            return element, []
+
+        return super().role(role_name, language_module, lineno, reporter)
 
 
 class WarningStream:
@@ -354,7 +397,7 @@ class LoggingReporter(Reporter):
         debug: bool = False,
         error_handler: str = 'backslashreplace',
     ) -> None:
-        stream = cast(IO, WarningStream())
+        stream = WarningStream()
         super().__init__(
             source, report_level, halt_level, stream, debug, error_handler=error_handler
         )
@@ -368,7 +411,7 @@ class NullReporter(Reporter):
 
 
 @contextmanager
-def switch_source_input(state: State, content: StringList) -> Iterator[None]:
+def switch_source_input(state: State[list[str]], content: StringList) -> Iterator[None]:
     """Switch current source input of state temporarily."""
     try:
         # remember the original ``get_source_and_line()`` method
@@ -377,7 +420,7 @@ def switch_source_input(state: State, content: StringList) -> Iterator[None]:
         # replace it by new one
         state_machine: StateMachine[None] = StateMachine([], None)  # type: ignore[arg-type]
         state_machine.input_lines = content
-        state.memo.reporter.get_source_and_line = state_machine.get_source_and_line  # type: ignore[attr-defined]  # NoQA: E501
+        state.memo.reporter.get_source_and_line = state_machine.get_source_and_line  # type: ignore[attr-defined]
 
         yield
     finally:
@@ -402,9 +445,10 @@ class SphinxFileOutput(FileOutput):
             and os.path.exists(self.destination_path)
         ):
             with open(self.destination_path, encoding=self.encoding) as f:
-                # skip writing: content not changed
-                if f.read() == data:
-                    return data
+                on_disk = f.read()
+            # skip writing: content not changed
+            if on_disk == data:
+                return data
 
         return super().write(data)
 
@@ -572,7 +616,7 @@ class SphinxRole:
         text: str,
         lineno: int,
         inliner: Inliner,
-        options: dict | None = None,
+        options: dict[str, Any] | None = None,
         content: Sequence[str] = (),
     ) -> tuple[list[Node], list[system_message]]:
         self.rawtext = rawtext
@@ -586,7 +630,7 @@ class SphinxRole:
         if name:
             self.name = name.lower()
         else:
-            self.name = self.env.temp_data.get('default_role', '')
+            self.name = self.env.current_document.default_role
             if not self.name:
                 self.name = self.env.config.default_role
             if not self.name:
@@ -666,7 +710,7 @@ class ReferenceRole(SphinxRole):
         text: str,
         lineno: int,
         inliner: Inliner,
-        options: dict | None = None,
+        options: dict[str, Any] | None = None,
         content: Sequence[str] = (),
     ) -> tuple[list[Node], list[system_message]]:
         if options is None:
@@ -707,10 +751,10 @@ class SphinxTranslator(nodes.NodeVisitor):
         self.builder = builder
         self.config = builder.config
         self.settings = document.settings
+        self._domains = builder.env.domains
 
     def dispatch_visit(self, node: Node) -> None:
-        """
-        Dispatch node to appropriate visitor method.
+        """Dispatch node to appropriate visitor method.
         The priority of visitor method is:
 
         1. ``self.visit_{node_class}()``
@@ -718,7 +762,7 @@ class SphinxTranslator(nodes.NodeVisitor):
         3. ``self.unknown_visit()``
         """
         for node_class in node.__class__.__mro__:
-            method = getattr(self, 'visit_%s' % (node_class.__name__), None)
+            method = getattr(self, 'visit_%s' % node_class.__name__, None)
             if method:
                 method(node)
                 break
@@ -726,8 +770,7 @@ class SphinxTranslator(nodes.NodeVisitor):
             super().dispatch_visit(node)
 
     def dispatch_departure(self, node: Node) -> None:
-        """
-        Dispatch node to appropriate departure method.
+        """Dispatch node to appropriate departure method.
         The priority of departure method is:
 
         1. ``self.depart_{node_class}()``
@@ -735,7 +778,7 @@ class SphinxTranslator(nodes.NodeVisitor):
         3. ``self.unknown_departure()``
         """
         for node_class in node.__class__.__mro__:
-            method = getattr(self, 'depart_%s' % (node_class.__name__), None)
+            method = getattr(self, 'depart_%s' % node_class.__name__, None)
             if method:
                 method(node)
                 break
@@ -758,7 +801,7 @@ def new_document(source_path: str, settings: Any = None) -> nodes.document:
     caches the result of docutils' and use it on second call for instantiation.
     This makes an instantiation of document nodes much faster.
     """
-    global __document_cache__
+    global __document_cache__  # NoQA: PLW0603
     try:
         cached_settings, reporter = __document_cache__
     except NameError:
@@ -770,8 +813,6 @@ def new_document(source_path: str, settings: Any = None) -> nodes.document:
         settings = copy(cached_settings)
 
     # Create a new instance of nodes.document using cached reporter
-    from sphinx import addnodes
-
-    document = addnodes.document(settings, reporter, source=source_path)
+    document = nodes.document(settings, reporter, source=source_path)
     document.note_source(source_path, -1)
     return document

sphinx/util/fileutil.py

@@ -5,16 +5,15 @@ from __future__ import annotations
 import os
 import posixpath
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-from docutils.utils import relative_path
+from typing import TYPE_CHECKING
 
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.osutil import copyfile, ensuredir
+from sphinx.util.osutil import _relative_path, copyfile, ensuredir
 
 if TYPE_CHECKING:
     from collections.abc import Callable
+    from typing import Any
 
     from sphinx.util.template import BaseRenderer
     from sphinx.util.typing import PathMatcher
@@ -22,16 +21,16 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-def _template_basename(filename: str | os.PathLike[str]) -> str | None:
+def _template_basename(filename: Path) -> Path | None:
     """Given an input filename:
     If the input looks like a template, then return the filename output should
     be written to.  Otherwise, return no result (None).
     """
-    basename = os.path.basename(filename)
-    if basename.lower().endswith('_t'):
-        return str(filename)[:-2]
-    elif basename.lower().endswith('.jinja'):
-        return str(filename)[:-6]
+    basename = filename.name.lower()
+    if basename.endswith('_t'):
+        return filename.with_name(filename.name[:-2])
+    elif basename.endswith('.jinja'):
+        return filename.with_name(filename.name[:-6])
     return None
 
 
@@ -54,13 +53,14 @@ def copy_asset_file(
     :param renderer: The template engine.  If not given, SphinxRenderer is used by default
     :param bool force: Overwrite the destination file even if it exists.
     """
-    if not os.path.exists(source):
+    source = Path(source)
+    if not source.exists():
         return
 
     destination = Path(destination)
     if destination.is_dir():
         # Use source filename if destination points a directory
-        destination /= os.path.basename(source)
+        destination /= source.name
 
     if _template_basename(source) and context is not None:
         if renderer is None:
@@ -68,8 +68,7 @@ def copy_asset_file(
 
             renderer = SphinxRenderer()
 
-        with open(source, encoding='utf-8') as fsrc:
-            template_content = fsrc.read()
+        template_content = source.read_text(encoding='utf-8')
         rendered_template = renderer.render_string(template_content, context)
 
         if not force and destination.exists() and template_content != rendered_template:
@@ -87,15 +86,14 @@ def copy_asset_file(
             return
 
         destination = _template_basename(destination) or destination
-        with open(destination, 'w', encoding='utf-8') as fdst:
-            msg = __('Writing evaluated template result to %s')
-            logger.info(
-                msg,
-                os.fsdecode(destination),
-                type='misc',
-                subtype='template_evaluation',
-            )
-            fdst.write(rendered_template)
+        msg = __('Writing evaluated template result to %s')
+        logger.info(
+            msg,
+            os.fsdecode(destination),
+            type='misc',
+            subtype='template_evaluation',
+        )
+        destination.write_text(rendered_template, encoding='utf-8')
     else:
         copyfile(source, destination, force=force)
 
@@ -125,7 +123,8 @@ def copy_asset(
     :param onerror: The error handler.
     :param bool force: Overwrite the destination file even if it exists.
     """
-    if not os.path.exists(source):
+    source = Path(source)
+    if not source.exists():
         return
 
     if renderer is None:
@@ -134,14 +133,14 @@ def copy_asset(
         renderer = SphinxRenderer()
 
     ensuredir(destination)
-    if os.path.isfile(source):
+    if source.is_file():
         copy_asset_file(
             source, destination, context=context, renderer=renderer, force=force
         )
         return
 
     for root, dirs, files in os.walk(source, followlinks=True):
-        reldir = relative_path(source, root)
+        reldir = _relative_path(Path(root), source).as_posix()
         for dir in dirs.copy():
             if excluded(posixpath.join(reldir, dir)):
                 dirs.remove(dir)

sphinx/util/http_date.py

@@ -3,6 +3,8 @@
 Reference: https://www.rfc-editor.org/rfc/rfc7231#section-7.1.1.1
 """
 
+from __future__ import annotations
+
 import time
 import warnings
 from email.utils import parsedate_tz