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

sphinx/util/nodes.py

@@ -95,12 +95,11 @@ class NodeMatcher(Generic[N]):
         confounds type checkers' ability to determine the return type of the iterator.
         """
         for found in node.findall(self):
-            yield cast(N, found)
+            yield cast('N', found)
 
 
 def get_full_module_name(node: Node) -> str:
-    """
-    Return full module dotted path like: 'docutils.nodes.paragraph'
+    """Return full module dotted path like: 'docutils.nodes.paragraph'
 
     :param nodes.Node node: target node
     :return: full module dotted path
@@ -109,8 +108,7 @@ def get_full_module_name(node: Node) -> str:
 
 
 def repr_domxml(node: Node, length: int = 80) -> str:
-    """
-    return DOM XML representation of the specified node like:
+    """Return DOM XML representation of the specified node like:
     '<paragraph translatable="False"><inline classes="versionadded">Added in version...'
 
     :param nodes.Node node: target node
@@ -181,7 +179,8 @@ def apply_source_workaround(node: Element) -> None:
         )
         node.source, node.line = node.parent.source, node.parent.line
 
-    # workaround: literal_block under bullet list (#4913)
+    # workaround: literal_block under bullet list
+    # See: https://github.com/sphinx-doc/sphinx/issues/4913
     if isinstance(node, nodes.literal_block) and node.source is None:
         with contextlib.suppress(ValueError):
             node.source = get_node_source(node)
@@ -197,10 +196,14 @@ def apply_source_workaround(node: Element) -> None:
     if isinstance(
         node,
         (
-            nodes.rubric  # #1305 rubric directive
-            | nodes.line  # #1477 line node
-            | nodes.image  # #3093 image directive in substitution
-            | nodes.field_name  # #3335 field list syntax
+            # https://github.com/sphinx-doc/sphinx/issues/1305 rubric directive
+            nodes.rubric
+            # https://github.com/sphinx-doc/sphinx/issues/1477 line node
+            | nodes.line
+            # https://github.com/sphinx-doc/sphinx/issues/3093 image directive in substitution
+            | nodes.image
+            # https://github.com/sphinx-doc/sphinx/issues/3335 field list syntax
+            | nodes.field_name
         ),
     ):
         logger.debug(
@@ -471,7 +474,7 @@ def inline_all_toctrees(
             if includefile not in traversed:
                 try:
                     traversed.append(includefile)
-                    logger.info(indent + colorfunc(includefile))
+                    logger.info(indent + colorfunc(includefile))  # NoQA: G003
                     subtree = inline_all_toctrees(
                         builder,
                         docnameset,
@@ -487,6 +490,8 @@ def inline_all_toctrees(
                         __('toctree contains ref to nonexisting file %r'),
                         includefile,
                         location=docname,
+                        type='toc',
+                        subtype='not_readable',
                     )
                 else:
                     sof = addnodes.start_of_file(docname=includefile)
@@ -593,7 +598,7 @@ def make_id(
             node_id = None
     elif term:
         node_id = _make_id(term)
-        if node_id == '':
+        if not node_id:
             node_id = None  # fallback to None
 
     while node_id is None or node_id in document.ids:
@@ -709,7 +714,7 @@ def _copy_except__document(el: Element) -> Element:
     """Monkey-patch ```nodes.Element.copy``` to not copy the ``_document``
     attribute.
 
-    xref: https://github.com/sphinx-doc/sphinx/issues/11116#issuecomment-1376767086
+    See: https://github.com/sphinx-doc/sphinx/issues/11116#issuecomment-1376767086
     """
     newnode = object.__new__(el.__class__)
     # set in Element.__init__()

sphinx/util/osutil.py

@@ -5,12 +5,12 @@ from __future__ import annotations
 import contextlib
 import filecmp
 import os
+import os.path
 import re
 import shutil
 import sys
 import unicodedata
 from io import StringIO
-from os import path
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -18,7 +18,7 @@ from sphinx.locale import __
 
 if TYPE_CHECKING:
     from types import TracebackType
-    from typing import Any
+    from typing import Any, Self
 
 # SEP separates path elements in the canonical file names
 #
@@ -29,12 +29,12 @@ SEP = '/'
 
 
 def os_path(canonical_path: str, /) -> str:
-    return canonical_path.replace(SEP, path.sep)
+    return canonical_path.replace(SEP, os.path.sep)
 
 
 def canon_path(native_path: str | os.PathLike[str], /) -> str:
     """Return path in OS-independent form"""
-    return os.fspath(native_path).replace(path.sep, SEP)
+    return os.fspath(native_path).replace(os.path.sep, SEP)
 
 
 def path_stabilize(filepath: str | os.PathLike[str], /) -> str:
@@ -134,10 +134,14 @@ def copyfile(
             logger.warning(msg, source, dest, type='misc', subtype='copy_overwrite')
             return
 
-        shutil.copyfile(source, dest)
-        with contextlib.suppress(OSError):
-            # don't do full copystat because the source may be read-only
-            _copy_times(source, dest)
+        if sys.platform == 'win32':
+            # copy2() uses Windows API calls
+            shutil.copy2(source, dest)
+        else:
+            shutil.copyfile(source, dest)
+            with contextlib.suppress(OSError):
+                # don't do full copystat because the source may be read-only
+                _copy_times(source, dest)
 
 
 _no_fn_re = re.compile(r'[^a-zA-Z0-9_-]')
@@ -166,36 +170,27 @@ def relpath(
         return str(path)
 
 
-safe_relpath = relpath  # for compatibility
-fs_encoding = sys.getfilesystemencoding() or sys.getdefaultencoding()
-
-
-abspath = path.abspath
+def _relative_path(path: Path, root: Path, /) -> Path:
+    """Return a relative filepath to *path* from the given *root* directory.
 
+    This is an alternative of ``Path.relative_to``.
+    It returns the original path if *path* and *root* are on different drives,
+    which may happen on Windows.
+    """
+    if path.anchor != root.anchor or '..' in root.parts:
+        # If the drives are different, no relative path exists.
+        # Path.relative_to() requires fully-resolved paths (no '..').
+        return path
+    if sys.version_info[:2] < (3, 12):
+        return Path(os.path.relpath(path, root))
+    return path.relative_to(root, walk_up=True)
 
-class _chdir:
-    """Remove this fall-back once support for Python 3.10 is removed."""
-
-    def __init__(self, target_dir: str, /) -> None:
-        self.path = target_dir
-        self._dirs: list[str] = []
-
-    def __enter__(self) -> None:
-        self._dirs.append(os.getcwd())
-        os.chdir(self.path)
 
-    def __exit__(
-        self,
-        type: type[BaseException] | None,
-        value: BaseException | None,
-        traceback: TracebackType | None,
-        /,
-    ) -> None:
-        os.chdir(self._dirs.pop())
+safe_relpath = relpath  # for compatibility
+fs_encoding = sys.getfilesystemencoding() or sys.getdefaultencoding()
 
 
-if sys.version_info[:2] < (3, 11):
-    cd = _chdir
+abspath = os.path.abspath
 
 
 class FileAvoidWrite:
@@ -232,19 +227,22 @@ class FileAvoidWrite:
         try:
             with open(self._path, encoding='utf-8') as old_f:
                 old_content = old_f.read()
-                if old_content == buf:
-                    return
+            if old_content == buf:
+                return
         except OSError:
             pass
 
         with open(self._path, 'w', encoding='utf-8') as f:
             f.write(buf)
 
-    def __enter__(self) -> FileAvoidWrite:
+    def __enter__(self) -> Self:
         return self
 
     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,
     ) -> bool:
         self.close()
         return True
@@ -258,8 +256,9 @@ class FileAvoidWrite:
         return getattr(self._io, name)
 
 
-def rmtree(path: str) -> None:
-    if os.path.isdir(path):
+def rmtree(path: str | os.PathLike[str], /) -> None:
+    path = Path(path)
+    if path.is_dir():
         shutil.rmtree(path)
     else:
         os.remove(path)

sphinx/util/parallel.py

@@ -6,7 +6,7 @@ import os
 import time
 import traceback
 from math import sqrt
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 try:
     import multiprocessing
@@ -20,6 +20,7 @@ from sphinx.util import logging
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
+    from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -34,12 +35,15 @@ class SerialTasks:
         pass
 
     def add_task(
-        self, task_func: Callable, arg: Any = None, result_func: Callable | None = None
+        self,
+        task_func: Callable[[Any], Any] | Callable[[], Any],
+        arg: Any = None,
+        result_func: Callable[[Any], Any] | None = None,
     ) -> None:
         if arg is not None:
-            res = task_func(arg)
+            res = task_func(arg)  # type: ignore[call-arg]
         else:
-            res = task_func()
+            res = task_func()  # type: ignore[call-arg]
         if result_func:
             result_func(res)
 
@@ -53,7 +57,7 @@ class ParallelTasks:
     def __init__(self, nproc: int) -> None:
         self.nproc = nproc
         # (optional) function performed by each task on the result of main task
-        self._result_funcs: dict[int, Callable] = {}
+        self._result_funcs: dict[int, Callable[[Any, Any], Any]] = {}
         # task arguments
         self._args: dict[int, list[Any] | None] = {}
         # list of subprocesses (both started and waiting)
@@ -61,20 +65,22 @@ class ParallelTasks:
         # list of receiving pipe connections of running subprocesses
         self._precvs: dict[int, Any] = {}
         # list of receiving pipe connections of waiting subprocesses
-        self._precvsWaiting: dict[int, Any] = {}
+        self._precvs_waiting: dict[int, Any] = {}
         # number of working subprocesses
         self._pworking = 0
         # task number of each subprocess
         self._taskid = 0
 
-    def _process(self, pipe: Any, func: Callable, arg: Any) -> None:
+    def _process(
+        self, pipe: Any, func: Callable[[Any], Any] | Callable[[], Any], arg: Any
+    ) -> None:
         try:
             collector = logging.LogCollector()
             with collector.collect():
                 if arg is None:
-                    ret = func()
+                    ret = func()  # type: ignore[call-arg]
                 else:
-                    ret = func(arg)
+                    ret = func(arg)  # type: ignore[call-arg]
             failed = False
         except BaseException as err:
             failed = True
@@ -84,7 +90,10 @@ class ParallelTasks:
         pipe.send((failed, collector.logs, ret))
 
     def add_task(
-        self, task_func: Callable, arg: Any = None, result_func: Callable | None = None
+        self,
+        task_func: Callable[[Any], Any] | Callable[[], Any],
+        arg: Any = None,
+        result_func: Callable[[Any, Any], Any] | None = None,
     ) -> None:
         tid = self._taskid
         self._taskid += 1
@@ -94,7 +103,7 @@ class ParallelTasks:
         context: Any = multiprocessing.get_context('fork')
         proc = context.Process(target=self._process, args=(psend, task_func, arg))
         self._procs[tid] = proc
-        self._precvsWaiting[tid] = precv
+        self._precvs_waiting[tid] = precv
         try:
             self._join_one()
         except Exception:
@@ -135,8 +144,8 @@ class ParallelTasks:
                 joined_any = True
                 break
 
-        while self._precvsWaiting and self._pworking < self.nproc:
-            newtid, newprecv = self._precvsWaiting.popitem()
+        while self._precvs_waiting and self._pworking < self.nproc:
+            newtid, newprecv = self._precvs_waiting.popitem()
             self._precvs[newtid] = newprecv
             self._procs[newtid].start()
             self._pworking += 1

sphinx/util/parsing.py

@@ -5,12 +5,13 @@ from __future__ import annotations
 import contextlib
 from typing import TYPE_CHECKING
 
-from docutils.nodes import Element, Node
+from docutils.nodes import Element
 from docutils.statemachine import StringList, string2lines
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
+    from docutils.nodes import Node
     from docutils.parsers.rst.states import RSTState
 
 

sphinx/util/png.py

@@ -4,6 +4,10 @@ from __future__ import annotations
 
 import binascii
 import struct
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import os
 
 LEN_IEND = 12
 LEN_DEPTH = 22
@@ -13,7 +17,7 @@ DEPTH_CHUNK_START = b'tEXtDepth\x00'
 IEND_CHUNK = b'\x00\x00\x00\x00IEND\xae\x42\x60\x82'
 
 
-def read_png_depth(filename: str) -> int | None:
+def read_png_depth(filename: str | os.PathLike[str]) -> int | None:
     """Read the special tEXt chunk indicating the depth from a PNG file."""
     with open(filename, 'rb') as f:
         f.seek(-(LEN_IEND + LEN_DEPTH), 2)
@@ -25,7 +29,7 @@ def read_png_depth(filename: str) -> int | None:
             return struct.unpack('!i', depthchunk[14:18])[0]
 
 
-def write_png_depth(filename: str, depth: int) -> None:
+def write_png_depth(filename: str | os.PathLike[str], depth: int) -> None:
     """Write the special tEXt chunk indicating the depth to a PNG file.
 
     The chunk is placed immediately before the special IEND chunk.

sphinx/util/requests.py

@@ -3,20 +3,34 @@
 from __future__ import annotations
 
 import warnings
-from typing import Any
-from urllib.parse import urlsplit
+from typing import TYPE_CHECKING
+from urllib.parse import urljoin, urlsplit
 
 import requests
 from urllib3.exceptions import InsecureRequestWarning
 
 import sphinx
 
+if TYPE_CHECKING:
+    import re
+    from collections.abc import Sequence
+    from typing import Any
+
+
 _USER_AGENT = (
     f'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 Firefox/100.0 '
     f'Sphinx/{sphinx.__version__}'
 )
 
 
+class _IgnoredRedirection(Exception):
+    """Sphinx-internal exception raised when an HTTP redirect is ignored"""
+
+    def __init__(self, destination: str, status_code: int) -> None:
+        self.destination = destination
+        self.status_code = status_code
+
+
 def _get_tls_cacert(url: str, certs: str | dict[str, str] | None) -> str | bool:
     """Get additional CA cert for a specific URL."""
     if not certs:
@@ -50,6 +64,23 @@ def head(url: str, **kwargs: Any) -> requests.Response:
 
 
 class _Session(requests.Session):
+    _ignored_redirects: Sequence[re.Pattern[str]]
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        self._ignored_redirects = kwargs.pop('_ignored_redirects', ())
+        super().__init__(*args, **kwargs)
+
+    def get_redirect_target(self, resp: requests.Response) -> str | None:
+        """Overrides the default requests.Session.get_redirect_target"""
+        # do not follow redirections that match ignored URI patterns
+        if resp.is_redirect:
+            destination = urljoin(resp.url, resp.headers['location'])
+            if any(pat.match(destination) for pat in self._ignored_redirects):
+                raise _IgnoredRedirection(
+                    destination=destination, status_code=resp.status_code
+                )
+        return super().get_redirect_target(resp)
+
     def request(  # type: ignore[override]
         self,
         method: str,

sphinx/util/rst.py

@@ -12,7 +12,7 @@ from docutils.parsers.rst import roles
 from docutils.parsers.rst.languages import en as english  # type: ignore[attr-defined]
 from docutils.parsers.rst.states import Body
 from docutils.utils import Reporter
-from jinja2 import Environment, pass_environment
+from jinja2 import pass_environment
 
 from sphinx.locale import __
 from sphinx.util import docutils, logging
@@ -21,6 +21,7 @@ if TYPE_CHECKING:
     from collections.abc import Iterator
 
     from docutils.statemachine import StringList
+    from jinja2 import Environment
 
 logger = logging.getLogger(__name__)
 
@@ -105,7 +106,7 @@ def append_epilog(content: StringList, epilog: str) -> None:
         if len(content) > 0:
             source, lineno = content.info(-1)
             # lineno will never be None, since len(content) > 0
-            lineno = cast(int, lineno)
+            lineno = cast('int', lineno)
         else:
             source = '<generated>'
             lineno = 0

sphinx/util/tags.py

@@ -112,4 +112,4 @@ class Tags:
             return node.name in self._tags
         else:
             msg = 'invalid node, check parsing'
-            raise ValueError(msg)
+            raise TypeError(msg)

sphinx/util/template.py

@@ -4,8 +4,8 @@ from __future__ import annotations
 
 import os
 from functools import partial
-from os import path
-from typing import TYPE_CHECKING, Any
+from pathlib import Path
+from typing import TYPE_CHECKING
 
 from jinja2 import TemplateNotFound
 from jinja2.loaders import BaseLoader
@@ -18,9 +18,13 @@ from sphinx.util import rst, texescape
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
+    from typing import Any
 
     from jinja2.environment import Environment
 
+_TEMPLATES_PATH = package_dir / 'templates'
+_LATEX_TEMPLATES_PATH = _TEMPLATES_PATH / 'latex'
+
 
 class BaseRenderer:
     def __init__(self, loader: BaseLoader | None = None) -> None:
@@ -49,11 +53,12 @@ class FileRenderer(BaseRenderer):
 
     @classmethod
     def render_from_file(
-        cls: type[FileRenderer], filename: str, context: dict[str, Any]
+        cls: type[FileRenderer],
+        filename: str | os.PathLike[str],
+        context: dict[str, Any],
     ) -> str:
-        dirname = os.path.dirname(filename)
-        basename = os.path.basename(filename)
-        return cls(dirname).render(basename, context)
+        filename = Path(filename)
+        return cls((filename.parent,)).render(filename.name, context)
 
 
 class SphinxRenderer(FileRenderer):
@@ -61,12 +66,14 @@ class SphinxRenderer(FileRenderer):
         self, template_path: Sequence[str | os.PathLike[str]] | None = None
     ) -> None:
         if template_path is None:
-            template_path = os.path.join(package_dir, 'templates')
+            template_path = (_TEMPLATES_PATH,)
         super().__init__(template_path)
 
     @classmethod
     def render_from_file(
-        cls: type[FileRenderer], filename: str, context: dict[str, Any]
+        cls: type[FileRenderer],
+        filename: str | os.PathLike[str],
+        context: dict[str, Any],
     ) -> str:
         return FileRenderer.render_from_file(filename, context)
 
@@ -78,7 +85,7 @@ class LaTeXRenderer(SphinxRenderer):
         latex_engine: str | None = None,
     ) -> None:
         if template_path is None:
-            template_path = [os.path.join(package_dir, 'templates', 'latex')]
+            template_path = (_LATEX_TEMPLATES_PATH,)
         super().__init__(template_path)
 
         # use texescape as escape filter
@@ -126,8 +133,9 @@ class SphinxTemplateLoader(BaseLoader):
         self.loaders = []
         self.sysloaders = []
 
+        conf_dir = Path(confdir)
         for templates_path in templates_paths:
-            loader = SphinxFileSystemLoader(path.join(confdir, templates_path))
+            loader = SphinxFileSystemLoader(conf_dir / templates_path)
             self.loaders.append(loader)
 
         for templates_path in system_templates_paths:

sphinx/util/texescape.py

@@ -29,14 +29,16 @@ tex_replacements = [
     # map some special Unicode characters to similar ASCII ones
     # (even for Unicode LaTeX as may not be supported by OpenType font)
     ('⎽', r'\_'),
-    ('ℯ', r'e'),
-    ('ⅈ', r'i'),
+    ('ℯ', r'e'),  # U+212F # NoQA: RUF001
+    ('ⅈ', r'i'),  # U+2148 # NoQA: RUF001
     # Greek alphabet not escaped: pdflatex handles it via textalpha and inputenc
     # OHM SIGN U+2126 is handled by LaTeX textcomp package
 ]
 
 # A map to avoid TeX ligatures or character replacements in PDF output
-# xelatex/lualatex/uplatex are handled differently (#5790, #6888)
+# xelatex/lualatex/uplatex are handled differently
+# https://github.com/sphinx-doc/sphinx/pull/5790
+# https://github.com/sphinx-doc/sphinx/pull/6888
 ascii_tex_replacements = [
     # Note: the " renders curly in OT1 encoding but straight in T1, T2A, LY1...
     #       escaping it to \textquotedbl would break documents using OT1
@@ -63,7 +65,7 @@ unicode_tex_replacements = [
     ('±', r'\(\pm\)'),
     ('→', r'\(\rightarrow\)'),
     ('‣', r'\(\rightarrow\)'),
-    ('–', r'\textendash{}'),
+    ('\N{EN DASH}', r'\textendash{}'),
     # superscript
     ('⁰', r'\(\sp{\text{0}}\)'),
     ('¹', r'\(\sp{\text{1}}\)'),
@@ -103,7 +105,7 @@ _tex_hlescape_map_without_unicode: dict[int, str] = {}
 
 def escape(s: str, latex_engine: str | None = None) -> str:
     """Escape text for LaTeX output."""
-    if latex_engine in ('lualatex', 'xelatex'):
+    if latex_engine in {'lualatex', 'xelatex'}:
         # unicode based LaTeX engine
         return s.translate(_tex_escape_map_without_unicode)
     else:
@@ -112,7 +114,7 @@ def escape(s: str, latex_engine: str | None = None) -> str:
 
 def hlescape(s: str, latex_engine: str | None = None) -> str:
     """Escape text for LaTeX highlighter."""
-    if latex_engine in ('lualatex', 'xelatex'):
+    if latex_engine in {'lualatex', 'xelatex'}:
         # unicode based LaTeX engine
         return s.translate(_tex_hlescape_map_without_unicode)
     else: