Sphinx 7.3.6__py3-none-any.whl → 7.4.0__py3-none-any.whl

sphinx/util/nodes.py

@@ -13,13 +13,14 @@ from docutils.nodes import Node
 from sphinx import addnodes
 from sphinx.locale import __
 from sphinx.util import logging
+from sphinx.util.parsing import _fresh_title_style_context
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator
 
     from docutils.nodes import Element
     from docutils.parsers.rst import Directive
-    from docutils.parsers.rst.states import Inliner
+    from docutils.parsers.rst.states import Inliner, RSTState
     from docutils.statemachine import StringList
 
     from sphinx.builders import Builder
@@ -324,24 +325,20 @@ def traverse_translatable_index(
         yield node, entries
 
 
-def nested_parse_with_titles(state: Any, content: StringList, node: Node,
+def nested_parse_with_titles(state: RSTState, content: StringList, node: Node,
                              content_offset: int = 0) -> str:
     """Version of state.nested_parse() that allows titles and does not require
     titles to have the same decoration as the calling document.
 
     This is useful when the parsed content comes from a completely different
     context, such as docstrings.
+
+    This function is retained for compatibility and will be deprecated in
+    Sphinx 8. Prefer ``nested_parse_to_nodes()``.
     """
-    # hack around title style bookkeeping
-    surrounding_title_styles = state.memo.title_styles
-    surrounding_section_level = state.memo.section_level
-    state.memo.title_styles = []
-    state.memo.section_level = 0
-    try:
-        return state.nested_parse(content, content_offset, node, match_titles=1)
-    finally:
-        state.memo.title_styles = surrounding_title_styles
-        state.memo.section_level = surrounding_section_level
+    with _fresh_title_style_context(state):
+        ret = state.nested_parse(content, content_offset, node, match_titles=True)
+    return ret
 
 
 def clean_astext(node: Element) -> str:

sphinx/util/osutil.py

@@ -17,6 +17,7 @@ from sphinx.deprecation import _deprecation_warning
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
+    from pathlib import Path
     from types import TracebackType
     from typing import Any
 
@@ -107,16 +108,15 @@ def copyfile(source: str | os.PathLike[str], dest: str | os.PathLike[str]) -> No
             copytimes(source, dest)
 
 
-no_fn_re = re.compile(r'[^a-zA-Z0-9_-]')
-project_suffix_re = re.compile(' Documentation$')
+_no_fn_re = re.compile(r'[^a-zA-Z0-9_-]')
 
 
 def make_filename(string: str) -> str:
-    return no_fn_re.sub('', string) or 'sphinx'
+    return _no_fn_re.sub('', string) or 'sphinx'
 
 
 def make_filename_from_project(project: str) -> str:
-    return make_filename(project_suffix_re.sub('', project)).lower()
+    return make_filename(project.removesuffix(' Documentation')).lower()
 
 
 def relpath(path: str | os.PathLike[str],
@@ -182,7 +182,7 @@ class FileAvoidWrite:
     Objects can be used as context managers.
     """
 
-    def __init__(self, path: str) -> None:
+    def __init__(self, path: str | Path) -> None:
         self._path = path
         self._io: StringIO | None = None
 

sphinx/util/parsing.py

@@ -0,0 +1,93 @@
+"""Docutils utility functions for parsing text."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import TYPE_CHECKING
+
+from docutils.nodes import Element, Node
+from docutils.statemachine import StringList, string2lines
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from docutils.parsers.rst.states import RSTState
+
+
+def nested_parse_to_nodes(
+    state: RSTState,
+    text: str | StringList,
+    *,
+    source: str = '<generated text>',
+    offset: int = 0,
+    allow_section_headings: bool = True,
+    keep_title_context: bool = False,
+) -> list[Node]:  # Element | nodes.Text
+    """Parse *text* into nodes.
+
+    :param state:
+        The state machine state. Must be a subclass of ``RSTState``.
+    :param text:
+        Text, in string form. ``StringList`` is also accepted.
+    :param source:
+        The text's source, used when creating a new ``StringList``.
+    :param offset:
+        The offset of the content.
+    :param allow_section_headings:
+        Are titles (sections) allowed in *text*?
+        Note that this option bypasses Docutils' usual checks on
+        doctree structure, and misuse of this option can lead to
+        an incoherent doctree. In Docutils, section nodes should
+        only be children of ``Structural`` nodes, which includes
+        ``document``, ``section``, and ``sidebar`` nodes.
+    :param keep_title_context:
+        If this is False (the default), then *content* is parsed as if it were
+        an independent document, meaning that title decorations (e.g. underlines)
+        do not need to match the surrounding document.
+        This is useful when the parsed content comes from
+        a completely different context, such as docstrings.
+        If this is True, then title underlines must match those in
+        the surrounding document, otherwise the behaviour is undefined.
+
+    .. versionadded:: 7.4
+    """
+    document = state.document
+    content = _text_to_string_list(
+        text, source=source, tab_width=document.settings.tab_width,
+    )
+    node = Element()  # Anonymous container for parsing
+    node.document = document
+
+    if keep_title_context:
+        state.nested_parse(content, offset, node, match_titles=allow_section_headings)
+    else:
+        with _fresh_title_style_context(state):
+            state.nested_parse(content, offset, node, match_titles=allow_section_headings)
+    return node.children
+
+
+@contextlib.contextmanager
+def _fresh_title_style_context(state: RSTState) -> Iterator[None]:
+    # hack around title style bookkeeping
+    memo = state.memo
+    surrounding_title_styles: list[str | tuple[str, str]] = memo.title_styles
+    surrounding_section_level: int = memo.section_level
+    # clear current title styles
+    memo.title_styles = []
+    memo.section_level = 0
+    try:
+        yield
+    finally:
+        # reset title styles
+        memo.title_styles = surrounding_title_styles
+        memo.section_level = surrounding_section_level
+
+
+def _text_to_string_list(
+    text: str | StringList, /, *, source: str, tab_width: int,
+) -> StringList:
+    # Doesn't really belong in this module, but avoids circular imports.
+    if isinstance(text, StringList):
+        return text
+    content = string2lines(text, tab_width, convert_whitespace=True)
+    return StringList(content, source=source)

sphinx/util/tags.py

@@ -1,36 +1,36 @@
 from __future__ import annotations
 
+import warnings
 from typing import TYPE_CHECKING
 
-from jinja2 import nodes
-from jinja2.environment import Environment
-from jinja2.parser import Parser
+import jinja2.environment
+import jinja2.nodes
+import jinja2.parser
 
-if TYPE_CHECKING:
-    from collections.abc import Iterator
-
-    from jinja2.nodes import Node
+from sphinx.deprecation import RemovedInSphinx90Warning
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+    from typing import Literal
 
-env = Environment()
+_ENV = jinja2.environment.Environment()
 
 
-class BooleanParser(Parser):
-    """
-    Only allow condition exprs and/or/not operations.
-    """
+class BooleanParser(jinja2.parser.Parser):
+    """Only allow conditional expressions and binary operators."""
 
-    def parse_compare(self) -> nodes.Expr:
-        node: nodes.Expr
+    def parse_compare(self) -> jinja2.nodes.Expr:
+        node: jinja2.nodes.Expr
         token = self.stream.current
         if token.type == 'name':
-            if token.value in ('true', 'false', 'True', 'False'):
-                node = nodes.Const(token.value in ('true', 'True'),
-                                   lineno=token.lineno)
-            elif token.value in ('none', 'None'):
-                node = nodes.Const(None, lineno=token.lineno)
+            if token.value in {'true', 'True'}:
+                node = jinja2.nodes.Const(True, lineno=token.lineno)
+            elif token.value in {'false', 'False'}:
+                node = jinja2.nodes.Const(False, lineno=token.lineno)
+            elif token.value in {'none', 'None'}:
+                node = jinja2.nodes.Const(None, lineno=token.lineno)
             else:
-                node = nodes.Name(token.value, 'load', lineno=token.lineno)
+                node = jinja2.nodes.Name(token.value, 'load', lineno=token.lineno)
             next(self.stream)
         elif token.type == 'lparen':
             next(self.stream)
@@ -42,47 +42,71 @@ class BooleanParser(Parser):
 
 
 class Tags:
-    def __init__(self, tags: list[str] | None = None) -> None:
-        self.tags = dict.fromkeys(tags or [], True)
+    def __init__(self, tags: Sequence[str] = ()) -> None:
+        self._tags = set(tags or ())
+        self._condition_cache: dict[str, bool] = {}
 
-    def has(self, tag: str) -> bool:
-        return tag in self.tags
+    def __str__(self) -> str:
+        return f'{self.__class__.__name__}({", ".join(sorted(self._tags))})'
 
-    __contains__ = has
+    def __repr__(self) -> str:
+        return f'{self.__class__.__name__}({tuple(sorted(self._tags))})'
 
     def __iter__(self) -> Iterator[str]:
-        return iter(self.tags)
+        return iter(self._tags)
+
+    def __contains__(self, tag: str) -> bool:
+        return tag in self._tags
+
+    def has(self, tag: str) -> bool:
+        return tag in self._tags
 
     def add(self, tag: str) -> None:
-        self.tags[tag] = True
+        self._tags.add(tag)
 
     def remove(self, tag: str) -> None:
-        self.tags.pop(tag, None)
+        self._tags.discard(tag)
+
+    @property
+    def tags(self) -> dict[str, Literal[True]]:
+        warnings.warn('Tags.tags is deprecated, use methods on Tags.',
+                      RemovedInSphinx90Warning, stacklevel=2)
+        return dict.fromkeys(self._tags, True)
 
     def eval_condition(self, condition: str) -> bool:
+        """Evaluate a boolean condition.
+
+        Only conditional expressions and binary operators (and, or, not)
+        are permitted, and operate on tag names, where truthy values mean
+        the tag is present and vice versa.
+        """
+        if condition in self._condition_cache:
+            return self._condition_cache[condition]
+
         # exceptions are handled by the caller
-        parser = BooleanParser(env, condition, state='variable')
+        parser = BooleanParser(_ENV, condition, state='variable')
         expr = parser.parse_expression()
         if not parser.stream.eos:
             msg = 'chunk after expression'
             raise ValueError(msg)
 
-        def eval_node(node: Node | None) -> bool:
-            if isinstance(node, nodes.CondExpr):
-                if eval_node(node.test):
-                    return eval_node(node.expr1)
-                else:
-                    return eval_node(node.expr2)
-            elif isinstance(node, nodes.And):
-                return eval_node(node.left) and eval_node(node.right)
-            elif isinstance(node, nodes.Or):
-                return eval_node(node.left) or eval_node(node.right)
-            elif isinstance(node, nodes.Not):
-                return not eval_node(node.node)
-            elif isinstance(node, nodes.Name):
-                return self.tags.get(node.name, False)
-            else:
-                msg = 'invalid node, check parsing'
-                raise ValueError(msg)
+        evaluated = self._condition_cache[condition] = self._eval_node(expr)
+        return evaluated
 
-        return eval_node(expr)
+    def _eval_node(self, node: jinja2.nodes.Node | None) -> bool:
+        if isinstance(node, jinja2.nodes.CondExpr):
+            if self._eval_node(node.test):
+                return self._eval_node(node.expr1)
+            else:
+                return self._eval_node(node.expr2)
+        elif isinstance(node, jinja2.nodes.And):
+            return self._eval_node(node.left) and self._eval_node(node.right)
+        elif isinstance(node, jinja2.nodes.Or):
+            return self._eval_node(node.left) or self._eval_node(node.right)
+        elif isinstance(node, jinja2.nodes.Not):
+            return not self._eval_node(node.node)
+        elif isinstance(node, jinja2.nodes.Name):
+            return node.name in self._tags
+        else:
+            msg = 'invalid node, check parsing'
+            raise ValueError(msg)