Sphinx 7.1.1__py3-none-any.whl → 7.2.0__py3-none-any.whl

sphinx/util/nodes.py

@@ -5,19 +5,22 @@ from __future__ import annotations
 import contextlib
 import re
 import unicodedata
-from typing import TYPE_CHECKING, Any, Callable, Iterable
+from typing import TYPE_CHECKING, Any, Callable
 
 from docutils import nodes
-from docutils.nodes import Element, Node
-from docutils.parsers.rst import Directive
-from docutils.parsers.rst.states import Inliner
-from docutils.statemachine import StringList
 
 from sphinx import addnodes
 from sphinx.locale import __
 from sphinx.util import logging
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from docutils.nodes import Element, Node
+    from docutils.parsers.rst import Directive
+    from docutils.parsers.rst.states import Inliner
+    from docutils.statemachine import StringList
+
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
     from sphinx.util.tags import Tags
@@ -47,7 +50,7 @@ class NodeMatcher:
     following example searches ``reference`` node having ``refdomain`` attributes::
 
         from __future__ import annotations
-from typing import Any
+from typing import TYPE_CHECKING, Any
         matcher = NodeMatcher(nodes.reference, refdomain=Any)
         doctree.findall(matcher)
         # => [<reference ...>, <reference ...>, ...]
@@ -196,7 +199,7 @@ def is_translatable(node: Node) -> bool:
     if isinstance(node, nodes.image) and (node.get('translatable') or node.get('alt')):
         return True
 
-    if isinstance(node, nodes.Inline) and 'translatable' not in node:  # type: ignore
+    if isinstance(node, nodes.Inline) and 'translatable' not in node:  # type: ignore[operator]
         # inline node must not be translated if 'translatable' is not set
         return False
 
@@ -223,7 +226,7 @@ def is_translatable(node: Node) -> bool:
             return False
         return True
 
-    if isinstance(node, nodes.meta):  # type: ignore
+    if isinstance(node, nodes.meta):  # type: ignore[attr-defined]
         return True
 
     return False
@@ -255,10 +258,11 @@ def extract_messages(doctree: Element) -> Iterable[tuple[Element, str]]:
             if node.get('alt'):
                 yield node, node['alt']
             if node.get('translatable'):
-                msg = '.. image:: %s' % node['uri']
+                image_uri = node.get('original_uri', node['uri'])
+                msg = f'.. image:: {image_uri}'
             else:
                 msg = ''
-        elif isinstance(node, nodes.meta):  # type: ignore
+        elif isinstance(node, nodes.meta):  # type: ignore[attr-defined]
             msg = node["content"]
         else:
             msg = node.rawsource.replace('\n', ' ').strip()
@@ -272,14 +276,16 @@ def get_node_source(node: Element) -> str:
     for pnode in traverse_parent(node):
         if pnode.source:
             return pnode.source
-    raise ValueError("node source not found")
+    msg = 'node source not found'
+    raise ValueError(msg)
 
 
 def get_node_line(node: Element) -> int:
     for pnode in traverse_parent(node):
         if pnode.line:
             return pnode.line
-    raise ValueError("node line not found")
+    msg = 'node line not found'
+    raise ValueError(msg)
 
 
 def traverse_parent(node: Element, cls: Any = None) -> Iterable[Element]:
@@ -564,7 +570,8 @@ def set_source_info(directive: Directive, node: Node) -> None:
 
 
 def set_role_source_info(inliner: Inliner, lineno: int, node: Node) -> None:
-    node.source, node.line = inliner.reporter.get_source_and_line(lineno)  # type: ignore
+    gsal = inliner.reporter.get_source_and_line  # type: ignore[attr-defined]
+    node.source, node.line = gsal(lineno)
 
 
 def copy_source_info(src: Element, dst: Element) -> None:
@@ -601,33 +608,65 @@ def is_smartquotable(node: Node) -> bool:
 def process_only_nodes(document: Node, tags: Tags) -> None:
     """Filter ``only`` nodes which do not match *tags*."""
     for node in document.findall(addnodes.only):
-        try:
-            ret = tags.eval_condition(node['expr'])
-        except Exception as err:
-            logger.warning(__('exception while evaluating only directive expression: %s'), err,
-                           location=node)
+        if _only_node_keep_children(node, tags):
             node.replace_self(node.children or nodes.comment())
         else:
-            if ret:
-                node.replace_self(node.children or nodes.comment())
-            else:
-                # A comment on the comment() nodes being inserted: replacing by [] would
-                # result in a "Losing ids" exception if there is a target node before
-                # the only node, so we make sure docutils can transfer the id to
-                # something, even if it's just a comment and will lose the id anyway...
-                node.replace_self(nodes.comment())
+            # A comment on the comment() nodes being inserted: replacing by [] would
+            # result in a "Losing ids" exception if there is a target node before
+            # the only node, so we make sure docutils can transfer the id to
+            # something, even if it's just a comment and will lose the id anyway...
+            node.replace_self(nodes.comment())
 
 
-def _copy_except__document(self: Element) -> Element:
+def _only_node_keep_children(node: addnodes.only, tags: Tags) -> bool:
+    """Keep children if tags match or error."""
+    try:
+        return tags.eval_condition(node['expr'])
+    except Exception as err:
+        logger.warning(
+            __('exception while evaluating only directive expression: %s'),
+            err,
+            location=node)
+        return True
+
+
+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
     """
-    newnode = self.__class__(rawsource=self.rawsource, **self.attributes)
-    newnode.source = self.source
-    newnode.line = self.line
+    newnode = object.__new__(el.__class__)
+    # set in Element.__init__()
+    newnode.children = []
+    newnode.rawsource = el.rawsource
+    newnode.tagname = el.tagname
+    # copied in Element.copy()
+    newnode.attributes = {k: (v
+                              if k not in {'ids', 'classes', 'names', 'dupnames', 'backrefs'}
+                              else v[:])
+                          for k, v in el.attributes.items()}
+    newnode.line = el.line
+    newnode.source = el.source
+    return newnode
+
+
+nodes.Element.copy = _copy_except__document  # type: ignore[assignment]
+
+
+def _deepcopy(el: Element) -> Element:
+    """Monkey-patch ```nodes.Element.deepcopy``` for speed."""
+    newnode = el.copy()
+    newnode.children = [child.deepcopy() for child in el.children]
+    for child in newnode.children:
+        child.parent = newnode
+        if el.document:
+            child.document = el.document
+            if child.source is None:
+                child.source = el.document.current_source
+            if child.line is None:
+                child.line = el.document.current_line
     return newnode
 
 
-nodes.Element.copy = _copy_except__document  # type: ignore
+nodes.Element.deepcopy = _deepcopy  # type: ignore[assignment]

sphinx/util/osutil.py

@@ -11,16 +11,12 @@ import sys
 import unicodedata
 from io import StringIO
 from os import path
-from typing import Any, Iterator
+from typing import TYPE_CHECKING, Any
 
 from sphinx.deprecation import _deprecation_warning
 
-try:
-    # for ALT Linux (#6712)
-    from sphinx.testing.path import path as Path
-except ImportError:
-    Path = None  # type: ignore
-
+if TYPE_CHECKING:
+    from collections.abc import Iterator
 
 # SEP separates path elements in the canonical file names
 #
@@ -30,16 +26,16 @@ except ImportError:
 SEP = "/"
 
 
-def os_path(canonicalpath: str) -> str:
-    return canonicalpath.replace(SEP, path.sep)
+def os_path(canonical_path: str, /) -> str:
+    return canonical_path.replace(SEP, path.sep)
 
 
-def canon_path(nativepath: str) -> str:
+def canon_path(native_path: str | os.PathLike[str], /) -> str:
     """Return path in OS-independent form"""
-    return nativepath.replace(path.sep, SEP)
+    return os.fspath(native_path).replace(path.sep, SEP)
 
 
-def path_stabilize(filepath: str) -> str:
+def path_stabilize(filepath: str | os.PathLike[str], /) -> str:
     "Normalize path separator and unicode string"
     new_path = canon_path(filepath)
     return unicodedata.normalize('NFC', new_path)
@@ -68,9 +64,9 @@ def relative_uri(base: str, to: str) -> str:
     return ('..' + SEP) * (len(b2) - 1) + SEP.join(t2)
 
 
-def ensuredir(path: str) -> None:
+def ensuredir(file: str | os.PathLike[str]) -> None:
     """Ensure that a path exists."""
-    os.makedirs(path, exist_ok=True)
+    os.makedirs(file, exist_ok=True)
 
 
 def mtimes_of_files(dirnames: list[str], suffix: str) -> Iterator[float]:
@@ -78,30 +74,26 @@ def mtimes_of_files(dirnames: list[str], suffix: str) -> Iterator[float]:
         for root, _dirs, files in os.walk(dirname):
             for sfile in files:
                 if sfile.endswith(suffix):
-                    try:
+                    with contextlib.suppress(OSError):
                         yield path.getmtime(path.join(root, sfile))
-                    except OSError:
-                        pass
 
 
-def copytimes(source: str, dest: str) -> None:
+def copytimes(source: str | os.PathLike[str], dest: str | os.PathLike[str]) -> None:
     """Copy a file's modification times."""
     st = os.stat(source)
     if hasattr(os, 'utime'):
         os.utime(dest, (st.st_atime, st.st_mtime))
 
 
-def copyfile(source: str, dest: str) -> None:
+def copyfile(source: str | os.PathLike[str], dest: str | os.PathLike[str]) -> None:
     """Copy a file and its modification times, if possible.
 
     Note: ``copyfile`` skips copying if the file has not been changed"""
     if not path.exists(dest) or not filecmp.cmp(source, dest):
         shutil.copyfile(source, dest)
-        try:
+        with contextlib.suppress(OSError):
             # don't do full copystat because the source may be read-only
             copytimes(source, dest)
-        except OSError:
-            pass
 
 
 no_fn_re = re.compile(r'[^a-zA-Z0-9_-]')
@@ -116,7 +108,8 @@ def make_filename_from_project(project: str) -> str:
     return make_filename(project_suffix_re.sub('', project)).lower()
 
 
-def relpath(path: str, start: str | None = os.curdir) -> str:
+def relpath(path: str | os.PathLike[str],
+            start: str | os.PathLike[str] | None = os.curdir) -> str:
     """Return a relative filepath to *path* either from the current directory or
     from an optional *start* directory.
 
@@ -126,26 +119,14 @@ def relpath(path: str, start: str | None = os.curdir) -> str:
     try:
         return os.path.relpath(path, start)
     except ValueError:
-        return path
+        return str(path)
 
 
 safe_relpath = relpath  # for compatibility
 fs_encoding = sys.getfilesystemencoding() or sys.getdefaultencoding()
 
 
-def abspath(pathdir: str) -> str:
-    if Path is not None and isinstance(pathdir, Path):
-        return pathdir.abspath()
-    else:
-        pathdir = path.abspath(pathdir)
-        if isinstance(pathdir, bytes):
-            try:
-                pathdir = pathdir.decode(fs_encoding)
-            except UnicodeDecodeError as exc:
-                raise UnicodeDecodeError('multibyte filename not supported on '
-                                         'this filesystem encoding '
-                                         '(%r)' % fs_encoding) from exc
-        return pathdir
+abspath = path.abspath
 
 
 class _chdir:
@@ -194,7 +175,8 @@ class FileAvoidWrite:
     def close(self) -> None:
         """Stop accepting writes and write file, if needed."""
         if not self._io:
-            raise Exception('FileAvoidWrite does not support empty files.')
+            msg = 'FileAvoidWrite does not support empty files.'
+            raise Exception(msg)
 
         buf = self.getvalue()
         self._io.close()
@@ -222,8 +204,8 @@ class FileAvoidWrite:
     def __getattr__(self, name: str) -> Any:
         # Proxy to _io instance.
         if not self._io:
-            raise Exception('Must write to FileAvoidWrite before other '
-                            'methods can be used')
+            msg = 'Must write to FileAvoidWrite before other methods can be used'
+            raise Exception(msg)
 
         return getattr(self._io, name)
 

sphinx/util/parallel.py

@@ -6,7 +6,7 @@ import os
 import time
 import traceback
 from math import sqrt
-from typing import Any, Callable, Sequence
+from typing import TYPE_CHECKING, Any, Callable
 
 try:
     import multiprocessing
@@ -17,6 +17,9 @@ except ImportError:
 from sphinx.errors import SphinxParallelError
 from sphinx.util import logging
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 logger = logging.getLogger(__name__)
 
 # our parallel functionality only works for the forking Process

sphinx/util/rst.py

@@ -5,19 +5,23 @@ from __future__ import annotations
 import re
 from collections import defaultdict
 from contextlib import contextmanager
-from typing import Generator
+from typing import TYPE_CHECKING
 from unicodedata import east_asian_width
 
 from docutils.parsers.rst import roles
 from docutils.parsers.rst.languages import en as english
 from docutils.parsers.rst.states import Body
-from docutils.statemachine import StringList
 from docutils.utils import Reporter
 from jinja2 import Environment, pass_environment
 
 from sphinx.locale import __
 from sphinx.util import docutils, logging
 
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from docutils.statemachine import StringList
+
 logger = logging.getLogger(__name__)
 
 FIELD_NAME_RE = re.compile(Body.patterns['field_marker'])
@@ -61,7 +65,7 @@ def default_role(docname: str, name: str) -> Generator[None, None, None]:
         dummy_reporter = Reporter('', 4, 4)
         role_fn, _ = roles.role(name, english, 0, dummy_reporter)
         if role_fn:  # type: ignore[truthy-function]
-            docutils.register_role('', role_fn)
+            docutils.register_role('', role_fn)  # type: ignore[arg-type]
         else:
             logger.warning(__('default role %s not found'), name, location=docname)
 

sphinx/util/tags.py

@@ -1,12 +1,17 @@
 from __future__ import annotations
 
-from typing import Iterator
+from typing import TYPE_CHECKING
 
 from jinja2 import nodes
 from jinja2.environment import Environment
-from jinja2.nodes import Node
 from jinja2.parser import Parser
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from jinja2.nodes import Node
+
+
 env = Environment()
 
 
@@ -59,7 +64,8 @@ class Tags:
         parser = BooleanParser(env, condition, state='variable')
         expr = parser.parse_expression()
         if not parser.stream.eos:
-            raise ValueError('chunk after expression')
+            msg = 'chunk after expression'
+            raise ValueError(msg)
 
         def eval_node(node: Node) -> bool:
             if isinstance(node, nodes.CondExpr):
@@ -76,6 +82,7 @@ class Tags:
             elif isinstance(node, nodes.Name):
                 return self.tags.get(node.name, False)
             else:
-                raise ValueError('invalid node, check parsing')
+                msg = 'invalid node, check parsing'
+                raise ValueError(msg)
 
         return eval_node(expr)

sphinx/util/template.py

@@ -5,10 +5,9 @@ from __future__ import annotations
 import os
 from functools import partial
 from os import path
-from typing import Any, Callable
+from typing import TYPE_CHECKING, Any, Callable
 
 from jinja2 import TemplateNotFound
-from jinja2.environment import Environment
 from jinja2.loaders import BaseLoader
 from jinja2.sandbox import SandboxedEnvironment
 
@@ -17,6 +16,11 @@ from sphinx.jinja2glue import SphinxFileSystemLoader
 from sphinx.locale import get_translator
 from sphinx.util import rst, texescape
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from jinja2.environment import Environment
+
 
 class BaseRenderer:
     def __init__(self, loader: BaseLoader | None = None) -> None:
@@ -32,8 +36,8 @@ class BaseRenderer:
 
 
 class FileRenderer(BaseRenderer):
-    def __init__(self, search_path: str | list[str]) -> None:
-        if isinstance(search_path, str):
+    def __init__(self, search_path: Sequence[str | os.PathLike[str]]) -> None:
+        if isinstance(search_path, (str, os.PathLike)):
             search_path = [search_path]
         else:
             # filter "None" paths
@@ -50,7 +54,7 @@ class FileRenderer(BaseRenderer):
 
 
 class SphinxRenderer(FileRenderer):
-    def __init__(self, template_path: None | str | list[str] = None) -> None:
+    def __init__(self, template_path: Sequence[str | os.PathLike[str]] | None = None) -> None:
         if template_path is None:
             template_path = os.path.join(package_dir, 'templates')
         super().__init__(template_path)
@@ -61,11 +65,10 @@ class SphinxRenderer(FileRenderer):
 
 
 class LaTeXRenderer(SphinxRenderer):
-    def __init__(
-        self, template_path: str | None = None, latex_engine: str | None = None,
-    ) -> None:
+    def __init__(self, template_path: Sequence[str | os.PathLike[str]] | None = None,
+                 latex_engine: str | None = None) -> None:
         if template_path is None:
-            template_path = os.path.join(package_dir, 'templates', 'latex')
+            template_path = [os.path.join(package_dir, 'templates', 'latex')]
         super().__init__(template_path)
 
         # use texescape as escape filter
@@ -85,9 +88,8 @@ class LaTeXRenderer(SphinxRenderer):
 
 
 class ReSTRenderer(SphinxRenderer):
-    def __init__(
-        self, template_path: None | str | list[str] = None, language: str | None = None,
-    ) -> None:
+    def __init__(self, template_path: Sequence[str | os.PathLike[str]] | None = None,
+                 language: str | None = None) -> None:
         super().__init__(template_path)
 
         # add language to environment
@@ -102,8 +104,9 @@ class ReSTRenderer(SphinxRenderer):
 class SphinxTemplateLoader(BaseLoader):
     """A loader supporting template inheritance"""
 
-    def __init__(self, confdir: str, templates_paths: list[str],
-                 system_templates_paths: list[str]) -> None:
+    def __init__(self, confdir: str | os.PathLike[str],
+                 templates_paths: Sequence[str | os.PathLike[str]],
+                 system_templates_paths: Sequence[str | os.PathLike[str]]) -> None:
         self.loaders = []
         self.sysloaders = []