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

sphinx/util/__init__.py

@@ -20,8 +20,8 @@ from sphinx.util import index_entries as _index_entries
 from sphinx.util import logging
 from sphinx.util import osutil as _osutil
 from sphinx.util.console import strip_colors  # NoQA: F401
-from sphinx.util.matching import patfilter  # noqa: F401
-from sphinx.util.nodes import (  # noqa: F401
+from sphinx.util.matching import patfilter  # NoQA: F401
+from sphinx.util.nodes import (  # NoQA: F401
     caption_ref_re,
     explicit_title_re,
     nested_parse_with_titles,
@@ -30,7 +30,7 @@ from sphinx.util.nodes import (  # noqa: F401
 
 # import other utilities; partly for backwards compatibility, so don't
 # prune unused ones indiscriminately
-from sphinx.util.osutil import (  # noqa: F401
+from sphinx.util.osutil import (  # NoQA: F401
     SEP,
     copyfile,
     copytimes,
@@ -68,6 +68,7 @@ class FilenameUniqDict(dict):
     interpreted as filenames, and keeps track of a set of docnames they
     appear in.  Used for images and downloadable files in the environment.
     """
+
     def __init__(self) -> None:
         self._existing: set[str] = set()
 
@@ -104,7 +105,7 @@ class FilenameUniqDict(dict):
         self._existing = state
 
 
-def _md5(data=b'', **_kw):
+def _md5(data: bytes = b'', **_kw: Any) -> hashlib._Hash:
     """Deprecated wrapper around hashlib.md5
 
     To be removed in Sphinx 9.0
@@ -112,7 +113,7 @@ def _md5(data=b'', **_kw):
     return hashlib.md5(data, usedforsecurity=False)
 
 
-def _sha1(data=b'', **_kw):
+def _sha1(data: bytes = b'', **_kw: Any) -> hashlib._Hash:
     """Deprecated wrapper around hashlib.sha1
 
     To be removed in Sphinx 9.0
@@ -178,6 +179,7 @@ class Tee:
     """
     File-like object writing to two streams.
     """
+
     def __init__(self, stream1: IO, stream2: IO) -> None:
         self.stream1 = stream1
         self.stream2 = stream2
@@ -202,7 +204,7 @@ def parselinenos(spec: str, total: int) -> list[int]:
     for part in parts:
         try:
             begend = part.strip().split('-')
-            if ['', ''] == begend:
+            if begend == ['', '']:
                 raise ValueError
             if len(begend) == 1:
                 items.append(int(begend[0]) - 1)
@@ -256,7 +258,7 @@ def isurl(url: str) -> bool:
     return bool(url) and '://' in url
 
 
-def _xml_name_checker():
+def _xml_name_checker() -> re.Pattern[str]:
     # to prevent import cycles
     from sphinx.builders.epub3 import _XML_NAME_PATTERN
 
@@ -264,7 +266,7 @@ def _xml_name_checker():
 
 
 # deprecated name -> (object to return, canonical path or empty string)
-_DEPRECATED_OBJECTS = {
+_DEPRECATED_OBJECTS: dict[str, tuple[Any, str] | tuple[Any, str, tuple[int, int]]] = {
     'path_stabilize': (_osutil.path_stabilize, 'sphinx.util.osutil.path_stabilize'),
     'display_chunk': (_display.display_chunk, 'sphinx.util.display.display_chunk'),
     'status_iterator': (_display.status_iterator, 'sphinx.util.display.status_iterator'),
@@ -285,13 +287,15 @@ _DEPRECATED_OBJECTS = {
 }
 
 
-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)
 
     from sphinx.deprecation import _deprecation_warning
 
-    deprecated_object, canonical_name = _DEPRECATED_OBJECTS[name]
-    _deprecation_warning(__name__, name, canonical_name, remove=(8, 0))
+    info = _DEPRECATED_OBJECTS[name]
+    deprecated_object, canonical_name = info[:2]
+    remove = info[2] if len(info) == 3 else (8, 0)
+    _deprecation_warning(__name__, name, canonical_name, remove=remove)
     return deprecated_object

sphinx/util/_io.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sphinx.util.console import strip_escape_sequences
+
+if TYPE_CHECKING:
+    from typing import Protocol
+
+    class SupportsWrite(Protocol):
+        def write(self, text: str, /) -> int | None:
+            ...
+
+
+class TeeStripANSI:
+    """File-like object writing to two streams."""
+
+    def __init__(
+        self,
+        stream_term: SupportsWrite,
+        stream_file: SupportsWrite,
+    ) -> None:
+        self.stream_term = stream_term
+        self.stream_file = stream_file
+
+    def write(self, text: str, /) -> None:
+        self.stream_term.write(text)
+        self.stream_file.write(strip_escape_sequences(text))
+
+    def flush(self) -> None:
+        if hasattr(self.stream_term, 'flush'):
+            self.stream_term.flush()
+        if hasattr(self.stream_file, 'flush'):
+            self.stream_file.flush()

sphinx/util/_pathlib.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import sys
 import warnings
 from pathlib import Path, PosixPath, PurePath, WindowsPath
+from typing import Any
 
 from sphinx.deprecation import RemovedInSphinx80Warning
 
@@ -21,34 +22,36 @@ _MSG = (
 
 if sys.platform == 'win32':
     class _StrPath(WindowsPath):
-        def replace(self, old, new, count=-1, /):
+        def replace(  # type: ignore[override]
+            self, old: str, new: str, count: int = -1, /,
+        ) -> str:
             # replace exists in both Path and str;
             # in Path it makes filesystem changes, so we use the safer str version
             warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
             return self.__str__().replace(old, new, count)
 
-        def __getattr__(self, item):
+        def __getattr__(self, item: str) -> Any:
             if item in _STR_METHODS:
                 warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
                 return getattr(self.__str__(), item)
             msg = f'{_PATH_NAME!r} has no attribute {item!r}'
             raise AttributeError(msg)
 
-        def __add__(self, other):
+        def __add__(self, other: str) -> str:
             warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
             return self.__str__() + other
 
-        def __bool__(self):
+        def __bool__(self) -> bool:
             if not self.__str__():
                 warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
                 return False
             return True
 
-        def __contains__(self, item):
+        def __contains__(self, item: str) -> bool:
             warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
             return item in self.__str__()
 
-        def __eq__(self, other):
+        def __eq__(self, other: object) -> bool:
             if isinstance(other, PurePath):
                 return super().__eq__(other)
             if isinstance(other, str):
@@ -56,46 +59,48 @@ if sys.platform == 'win32':
                 return self.__str__() == other
             return NotImplemented
 
-        def __hash__(self):
+        def __hash__(self) -> int:
             return super().__hash__()
 
-        def __getitem__(self, item):
+        def __getitem__(self, item: int | slice) -> str:
             warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
             return self.__str__()[item]
 
-        def __len__(self):
+        def __len__(self) -> int:
             warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
             return len(self.__str__())
 else:
     class _StrPath(PosixPath):
-        def replace(self, old, new, count=-1, /):
+        def replace(  # type: ignore[override]
+            self, old: str, new: str, count: int = -1, /,
+        ) -> str:
             # replace exists in both Path and str;
             # in Path it makes filesystem changes, so we use the safer str version
             warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
             return self.__str__().replace(old, new, count)
 
-        def __getattr__(self, item):
+        def __getattr__(self, item: str) -> Any:
             if item in _STR_METHODS:
                 warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
                 return getattr(self.__str__(), item)
             msg = f'{_PATH_NAME!r} has no attribute {item!r}'
             raise AttributeError(msg)
 
-        def __add__(self, other):
+        def __add__(self, other: str) -> str:
             warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
             return self.__str__() + other
 
-        def __bool__(self):
+        def __bool__(self) -> bool:
             if not self.__str__():
                 warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
                 return False
             return True
 
-        def __contains__(self, item):
+        def __contains__(self, item: str) -> bool:
             warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
             return item in self.__str__()
 
-        def __eq__(self, other):
+        def __eq__(self, other: object) -> bool:
             if isinstance(other, PurePath):
                 return super().__eq__(other)
             if isinstance(other, str):
@@ -103,13 +108,13 @@ else:
                 return self.__str__() == other
             return NotImplemented
 
-        def __hash__(self):
+        def __hash__(self) -> int:
             return super().__hash__()
 
-        def __getitem__(self, item):
+        def __getitem__(self, item: int | slice) -> str:
             warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
             return self.__str__()[item]
 
-        def __len__(self):
+        def __len__(self) -> int:
             warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
             return len(self.__str__())

sphinx/util/build_phase.py

@@ -5,6 +5,7 @@ from enum import IntEnum
 
 class BuildPhase(IntEnum):
     """Build phase of Sphinx application."""
+
     INITIALIZATION = 1
     READING = 2
     CONSISTENCY_CHECK = 3

sphinx/util/cfamily.py

@@ -12,6 +12,8 @@ from sphinx import addnodes
 from sphinx.util import logging
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from docutils.nodes import TextElement
 
     from sphinx.config import Config
@@ -86,7 +88,7 @@ class NoOldIdError(Exception):
 
 
 class ASTBaseBase:
-    def __eq__(self, other: Any) -> bool:
+    def __eq__(self, other: object) -> bool:
         if type(self) is not type(other):
             return False
         try:
@@ -107,7 +109,7 @@ class ASTBaseBase:
         raise NotImplementedError(repr(self))
 
     def __str__(self) -> str:
-        return self._stringify(lambda ast: str(ast))
+        return self._stringify(str)
 
     def get_display_string(self) -> str:
         return self._stringify(lambda ast: ast.get_display_string())
@@ -143,6 +145,11 @@ class ASTGnuAttribute(ASTBaseBase):
         self.name = name
         self.args = args
 
+    def __eq__(self, other: object) -> bool:
+        if type(other) is not ASTGnuAttribute:
+            return NotImplemented
+        return self.name == other.name and self.args == other.args
+
     def _stringify(self, transform: StringifyTransform) -> str:
         res = [self.name]
         if self.args:
@@ -202,6 +209,11 @@ class ASTAttributeList(ASTBaseBase):
     def __init__(self, attrs: list[ASTAttribute]) -> None:
         self.attrs = attrs
 
+    def __eq__(self, other: object) -> bool:
+        if type(other) is not ASTAttributeList:
+            return NotImplemented
+        return self.attrs == other.attrs
+
     def __len__(self) -> int:
         return len(self.attrs)
 
@@ -265,14 +277,11 @@ class BaseParser:
         for e in errors:
             if len(e[1]) > 0:
                 indent = '  '
-                result.append(e[1])
-                result.append(':\n')
+                result.extend((e[1], ':\n'))
                 for line in str(e[0]).split('\n'):
                     if len(line) == 0:
                         continue
-                    result.append(indent)
-                    result.append(line)
-                    result.append('\n')
+                    result.extend((indent, line, '\n'))
             else:
                 result.append(str(e[0]))
         return DefinitionError(''.join(result))
@@ -293,8 +302,7 @@ class BaseParser:
             'Invalid %s declaration: %s [error at %d]\n  %s\n  %s' %
             (self.language, msg, self.pos, self.definition, indicator))
         errors.append((exMain, "Main error"))
-        for err in self.otherErrors:
-            errors.append((err, "Potential other error"))
+        errors.extend((err, "Potential other error") for err in self.otherErrors)
         self.otherErrors = []
         raise self._make_multi_error(errors, '')
 
@@ -369,11 +377,11 @@ class BaseParser:
     ################################################################################
 
     @property
-    def id_attributes(self):
+    def id_attributes(self) -> Sequence[str]:
         raise NotImplementedError
 
     @property
-    def paren_attributes(self):
+    def paren_attributes(self) -> Sequence[str]:
         raise NotImplementedError
 
     def _parse_balanced_token_seq(self, end: list[str]) -> str:

sphinx/util/console.py

@@ -6,6 +6,37 @@ import os
 import re
 import shutil
 import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Final
+
+    # fmt: off
+    def reset(text: str) -> str: ...  # NoQA: E704
+    def bold(text: str) -> str: ...  # NoQA: E704
+    def faint(text: str) -> str: ...  # NoQA: E704
+    def standout(text: str) -> str: ...  # NoQA: E704
+    def underline(text: str) -> str: ...  # NoQA: E704
+    def blink(text: str) -> str: ...  # NoQA: E704
+
+    def black(text: str) -> str: ...  # NoQA: E704
+    def white(text: str) -> str: ...  # NoQA: E704
+    def red(text: str) -> str: ...  # NoQA: E704
+    def green(text: str) -> str: ...  # NoQA: E704
+    def yellow(text: str) -> str: ...  # NoQA: E704
+    def blue(text: str) -> str: ...  # NoQA: E704
+    def fuchsia(text: str) -> str: ...  # NoQA: E704
+    def teal(text: str) -> str: ...  # NoQA: E704
+
+    def darkgray(text: str) -> str: ...  # NoQA: E704
+    def lightgray(text: str) -> str: ...  # NoQA: E704
+    def darkred(text: str) -> str: ...  # NoQA: E704
+    def darkgreen(text: str) -> str: ...  # NoQA: E704
+    def brown(text: str) -> str: ...  # NoQA: E704
+    def darkblue(text: str) -> str: ...  # NoQA: E704
+    def purple(text: str) -> str: ...  # NoQA: E704
+    def turquoise(text: str) -> str: ...  # NoQA: E704
+    # fmt: on
 
 try:
     # check if colorama is installed to support color on Windows
@@ -13,8 +44,26 @@ try:
 except ImportError:
     colorama = None
 
+_CSI: Final[str] = re.escape('\x1b[')  # 'ESC [': Control Sequence Introducer
+
+# Pattern matching ANSI control sequences containing colors.
+_ansi_color_re: Final[re.Pattern[str]] = re.compile(r'\x1b\[(?:\d+;){0,2}\d*m')
+
+_ansi_re: Final[re.Pattern[str]] = re.compile(
+    _CSI
+    + r"""
+    (?:
+      (?:\d+;){0,2}\d*m     # ANSI color code    ('m' is equivalent to '0m')
+    |
+      [012]?K               # ANSI Erase in Line ('K' is equivalent to '0K')
+    )""",
+    re.VERBOSE | re.ASCII,
+)
+"""Pattern matching ANSI CSI colors (SGR) and erase line (EL) sequences.
+
+See :func:`strip_escape_sequences` for details.
+"""
 
-_ansi_re: re.Pattern[str] = re.compile('\x1b\\[(\\d\\d;){0,2}\\d\\dm')
 codes: dict[str, str] = {}
 
 
@@ -37,7 +86,7 @@ def term_width_line(text: str) -> str:
         return text + '\n'
     else:
         # codes are not displayed, this must be taken into account
-        return text.ljust(_tw + len(text) - len(_ansi_re.sub('', text))) + '\r'
+        return text.ljust(_tw + len(text) - len(strip_escape_sequences(text))) + '\r'
 
 
 def color_terminal() -> bool:
@@ -55,9 +104,7 @@ def color_terminal() -> bool:
     if 'COLORTERM' in os.environ:
         return True
     term = os.environ.get('TERM', 'dumb').lower()
-    if term in ('xterm', 'linux') or 'color' in term:
-        return True
-    return False
+    return term in ('xterm', 'linux') or 'color' in term
 
 
 def nocolor() -> None:
@@ -87,41 +134,74 @@ def colorize(name: str, text: str, input_mode: bool = False) -> str:
 
 
 def strip_colors(s: str) -> str:
-    return re.compile('\x1b.*?m').sub('', s)
+    """Remove the ANSI color codes in a string *s*.
+
+    .. caution::
+
+       This function is not meant to be used in production and should only
+       be used for testing Sphinx's output messages.
+
+    .. seealso:: :func:`strip_escape_sequences`
+    """
+    return _ansi_color_re.sub('', s)
+
+
+def strip_escape_sequences(text: str, /) -> str:
+    r"""Remove the ANSI CSI colors and "erase in line" sequences.
+
+    Other `escape sequences `__ (e.g., VT100-specific functions) are not
+    supported and only control sequences *natively* known to Sphinx (i.e.,
+    colors declared in this module and "erase entire line" (``'\x1b[2K'``))
+    are eliminated by this function.
+
+    .. caution::
+
+       This function is not meant to be used in production and should only
+       be used for testing Sphinx's output messages that were not tempered
+       with by third-party extensions.
+
+    .. versionadded:: 7.3
+
+       This function is added as an *experimental* feature.
+
+    __ https://en.wikipedia.org/wiki/ANSI_escape_code
+    """
+    return _ansi_re.sub('', text)
 
 
 def create_color_func(name: str) -> None:
     def inner(text: str) -> str:
         return colorize(name, text)
+
     globals()[name] = inner
 
 
 _attrs = {
-    'reset':     '39;49;00m',
-    'bold':      '01m',
-    'faint':     '02m',
-    'standout':  '03m',
+    'reset': '39;49;00m',
+    'bold': '01m',
+    'faint': '02m',
+    'standout': '03m',
     'underline': '04m',
-    'blink':     '05m',
+    'blink': '05m',
 }
 
-for _name, _value in _attrs.items():
-    codes[_name] = '\x1b[' + _value
+for __name, __value in _attrs.items():
+    codes[__name] = '\x1b[' + __value
 
 _colors = [
-    ('black',     'darkgray'),
-    ('darkred',   'red'),
+    ('black', 'darkgray'),
+    ('darkred', 'red'),
     ('darkgreen', 'green'),
-    ('brown',     'yellow'),
-    ('darkblue',  'blue'),
-    ('purple',    'fuchsia'),
+    ('brown', 'yellow'),
+    ('darkblue', 'blue'),
+    ('purple', 'fuchsia'),
     ('turquoise', 'teal'),
     ('lightgray', 'white'),
 ]
 
-for i, (dark, light) in enumerate(_colors, 30):
-    codes[dark] = '\x1b[%im' % i
-    codes[light] = '\x1b[%im' % (i + 60)
+for __i, (__dark, __light) in enumerate(_colors, 30):
+    codes[__dark] = '\x1b[%im' % __i
+    codes[__light] = '\x1b[%im' % (__i + 60)
 
 _orig_codes = codes.copy()
 

sphinx/util/display.py

@@ -5,7 +5,7 @@ from typing import Any, Callable, TypeVar
 
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import bold  # type: ignore[attr-defined]
+from sphinx.util.console import bold, color_terminal
 
 if False:
     from collections.abc import Iterable, Iterator
@@ -33,7 +33,8 @@ def status_iterator(
     verbosity: int = 0,
     stringify_func: Callable[[Any], str] = display_chunk,
 ) -> Iterator[T]:
-    single_line = verbosity < 1
+    # printing on a single line requires ANSI control sequences
+    single_line = verbosity < 1 and color_terminal()
     bold_summary = bold(summary)
     if length == 0:
         logger.info(bold_summary, nonl=True)

sphinx/util/docfields.py

@@ -34,9 +34,7 @@ def _is_single_paragraph(node: nodes.field_body) -> bool:
         for subnode in node[1:]:  # type: Node
             if not isinstance(subnode, nodes.system_message):
                 return False
-    if isinstance(node[0], nodes.paragraph):
-        return True
-    return False
+    return isinstance(node[0], nodes.paragraph)
 
 
 class Field:
@@ -52,6 +50,7 @@ class Field:
        :returns: description of the return value
        :rtype: description of the return type
     """
+
     is_grouped = False
     is_typed = False
 
@@ -79,7 +78,7 @@ class Field:
         assert env is not None
         assert (inliner is None) == (location is None), (inliner, location)
         if not rolename:
-            return contnode or innernode(target, target)
+            return contnode or innernode(target, target)  # type: ignore[call-arg]
         # The domain is passed from DocFieldTransformer. So it surely exists.
         # So we don't need to take care the env.get_domain() raises an exception.
         role = env.get_domain(domain).role(rolename)
@@ -90,7 +89,7 @@ class Field:
                 logger.warning(__(msg), domain, rolename, location=location)
             refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False,
                                             reftype=rolename, reftarget=target)
-            refnode += contnode or innernode(target, target)
+            refnode += contnode or innernode(target, target)  # type: ignore[call-arg]
             env.get_domain(domain).process_field_xref(refnode)
             return refnode
         lineno = -1
@@ -152,6 +151,7 @@ class GroupedField(Field):
 
        :raises ErrorClass: description when it is raised
     """
+
     is_grouped = True
     list_type = nodes.bullet_list
 
@@ -208,6 +208,7 @@ class TypedField(GroupedField):
 
        :param SomeClass foo: description of parameter foo
     """
+
     is_typed = True
 
     def __init__(
@@ -233,7 +234,7 @@ class TypedField(GroupedField):
         inliner: Inliner | None = None,
         location: Element | None = None,
     ) -> nodes.field:
-        def handle_item(fieldarg: str, content: str) -> nodes.paragraph:
+        def handle_item(fieldarg: str, content: list[Node]) -> nodes.paragraph:
             par = nodes.paragraph()
             par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
                                        addnodes.literal_strong, env=env))
@@ -251,8 +252,10 @@ class TypedField(GroupedField):
                 else:
                     par += fieldtype
                 par += nodes.Text(')')
-            par += nodes.Text(' -- ')
-            par += content
+            has_content = any(c.astext().strip() for c in content)
+            if has_content:
+                par += nodes.Text(' -- ')
+                par += content
             return par
 
         fieldname = nodes.field_name('', self.label)
@@ -272,6 +275,7 @@ class DocFieldTransformer:
     Transforms field lists in "doc field" syntax into better-looking
     equivalents, using the field type definitions given on a domain.
     """
+
     typemap: dict[str, tuple[Field, bool]]
 
     def __init__(self, directive: ObjectDescription) -> None: