Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/util/__init__.py

@@ -2,56 +2,33 @@
 
 from __future__ import annotations
 
-import hashlib
 import os
 import posixpath
 import re
-from typing import Any
-
-from sphinx.errors import ExtensionError as _ExtensionError
-from sphinx.errors import FiletypeNotFoundError
-from sphinx.util import _files, _importer, logging
-from sphinx.util import index_entries as _index_entries
-from sphinx.util._lines import parse_line_num_spec as parselinenos  # NoQA: F401
-from sphinx.util._uri import encode_uri  # NoQA: F401
-from sphinx.util._uri import is_url as isurl  # NoQA: F401
-from sphinx.util.console import strip_colors  # 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,
-    split_explicit_title,
-)
-
-# import other utilities; partly for backwards compatibility, so don't
-# prune unused ones indiscriminately
-from sphinx.util.osutil import (  # NoQA: F401
-    SEP,
-    copyfile,
-    ensuredir,
-    make_filename,
-    os_path,
-    relative_uri,
-)
-
-logger = logging.getLogger(__name__)
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    import hashlib
+    from collections.abc import Callable
+    from types import ModuleType
+    from typing import Any
 
 # Generally useful regular expressions.
 ws_re: re.Pattern[str] = re.compile(r'\s+')
 url_re: re.Pattern[str] = re.compile(r'(?P<schema>.+)://.*')
 
-
 # High-level utility functions.
 
 
 def docname_join(basedocname: str, docname: str) -> str:
-    return posixpath.normpath(posixpath.join('/' + basedocname, '..', docname))[1:]
+    return posixpath.normpath(posixpath.join(f'/{basedocname}', '..', docname))[1:]
 
 
 def get_filetype(
     source_suffix: dict[str, str], filename: str | os.PathLike[str]
 ) -> str:
+    from sphinx.errors import FiletypeNotFoundError
+
     for suffix, filetype in source_suffix.items():
         if os.fspath(filename).endswith(suffix):
             # If default filetype (None), considered as restructuredtext.
@@ -64,6 +41,8 @@ def _md5(data: bytes = b'', **_kw: Any) -> hashlib._Hash:
 
     To be removed in Sphinx 9.0
     """
+    import hashlib
+
     return hashlib.md5(data, usedforsecurity=False)
 
 
@@ -72,37 +51,107 @@ def _sha1(data: bytes = b'', **_kw: Any) -> hashlib._Hash:
 
     To be removed in Sphinx 9.0
     """
+    import hashlib
+
     return hashlib.sha1(data, usedforsecurity=False)
 
 
-# deprecated name -> (object to return, canonical path or empty string)
-_DEPRECATED_OBJECTS: dict[str, tuple[Any, str, tuple[int, int]]] = {
-    'split_index_msg': (
-        _index_entries.split_index_msg,
-        'sphinx.util.index_entries.split_index_msg',
-        (9, 0),
-    ),
-    'split_into': (
-        _index_entries.split_index_msg,
-        'sphinx.util.index_entries.split_into',
-        (9, 0),
-    ),
-    'ExtensionError': (_ExtensionError, 'sphinx.errors.ExtensionError', (9, 0)),
-    'md5': (_md5, '', (9, 0)),
-    'sha1': (_sha1, '', (9, 0)),
-    'import_object': (_importer.import_object, '', (10, 0)),
-    'FilenameUniqDict': (_files.FilenameUniqDict, '', (10, 0)),
-    'DownloadFiles': (_files.DownloadFiles, '', (10, 0)),
-}
+def __getattr__(name: str) -> Any:
+    from sphinx.deprecation import _deprecation_warning
 
+    obj: Callable[..., Any]
+    mod: ModuleType
 
-def __getattr__(name: str) -> Any:
-    if name not in _DEPRECATED_OBJECTS:
-        msg = f'module {__name__!r} has no attribute {name!r}'
-        raise AttributeError(msg)
+    # RemovedInSphinx90Warning
+    if name == 'split_index_msg':
+        from sphinx.util.index_entries import split_index_msg as obj
 
-    from sphinx.deprecation import _deprecation_warning
+        canonical_name = f'{obj.__module__}.{obj.__qualname__}'
+        _deprecation_warning(__name__, name, canonical_name, remove=(9, 0))
+        return obj
+
+    if name == 'split_into':
+        from sphinx.util.index_entries import _split_into as obj
+
+        _deprecation_warning(__name__, name, '', remove=(9, 0))
+        return obj
+
+    if name == 'ExtensionError':
+        from sphinx.errors import ExtensionError as obj  # NoQA: N813
+
+        canonical_name = f'{obj.__module__}.{obj.__qualname__}'
+        _deprecation_warning(__name__, name, canonical_name, remove=(9, 0))
+        return obj
+
+    if name in {'md5', 'sha1'}:
+        obj = globals()[f'_{name}']
+        canonical_name = f'hashlib.{name}'
+        _deprecation_warning(__name__, name, canonical_name, remove=(9, 0))
+        return obj
+
+    # RemovedInSphinx10Warning
+
+    if name in {'DownloadFiles', 'FilenameUniqDict'}:
+        from sphinx.util import _files as mod
+
+        obj = getattr(mod, name)
+        _deprecation_warning(__name__, name, '', remove=(10, 0))
+        return obj
+
+    # Re-exported for backwards compatibility,
+    # but not currently deprecated
+
+    if name == 'encode_uri':
+        from sphinx.util._uri import encode_uri
+
+        return encode_uri
+
+    if name == 'import_object':
+        from sphinx.util._importer import import_object
+
+        return import_object
+
+    if name == 'isurl':
+        from sphinx.util._uri import is_url
+
+        return is_url
+
+    if name == 'parselinenos':
+        from sphinx.util._lines import parse_line_num_spec
+
+        return parse_line_num_spec
+
+    if name == 'patfilter':
+        from sphinx.util.matching import patfilter
+
+        return patfilter
+
+    if name == 'strip_escape_sequences':
+        from sphinx._cli.util.errors import strip_escape_sequences
+
+        return strip_escape_sequences
+
+    if name in {
+        'caption_ref_re',
+        'explicit_title_re',
+        'nested_parse_with_titles',
+        'split_explicit_title',
+    }:
+        from sphinx.util import nodes as mod
+
+        return getattr(mod, name)
+
+    if name in {
+        'SEP',
+        'copyfile',
+        'ensuredir',
+        'make_filename',
+        'os_path',
+        'relative_uri',
+    }:
+        from sphinx.util import osutil as mod
+
+        return getattr(mod, name)
 
-    deprecated_object, canonical_name, remove = _DEPRECATED_OBJECTS[name]
-    _deprecation_warning(__name__, name, canonical_name, remove=remove)
-    return deprecated_object
+    msg = f'module {__name__!r} has no attribute {name!r}'
+    raise AttributeError(msg)

sphinx/util/_files.py

@@ -1,33 +1,44 @@
 from __future__ import annotations
 
 import hashlib
-import os.path
-from typing import Any
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sphinx.util._pathlib import _StrPath
+
+if TYPE_CHECKING:
+    import os
+    from collections.abc import Set
 
 
 class FilenameUniqDict(dict[str, tuple[set[str], str]]):
-    """
-    A dictionary that automatically generates unique names for its keys,
+    """A dictionary that automatically generates unique names for its keys,
     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:
+        super().__init__()
         self._existing: set[str] = set()
 
-    def add_file(self, docname: str, newfile: str) -> str:
+    def add_file(self, docname: str, newfile: str | os.PathLike[str]) -> str:
+        newfile = str(newfile)
         if newfile in self:
-            self[newfile][0].add(docname)
-            return self[newfile][1]
-        uniquename = os.path.basename(newfile)
-        base, ext = os.path.splitext(uniquename)
+            docnames, unique_name = self[newfile]
+            docnames.add(docname)
+            return unique_name
+
+        new_file = Path(newfile)
+        unique_name = new_file.name
+        base = new_file.stem
+        ext = new_file.suffix
         i = 0
-        while uniquename in self._existing:
+        while unique_name in self._existing:
             i += 1
-            uniquename = f'{base}{i}{ext}'
-        self[newfile] = ({docname}, uniquename)
-        self._existing.add(uniquename)
-        return uniquename
+            unique_name = f'{base}{i}{ext}'
+        self[newfile] = ({docname}, unique_name)
+        self._existing.add(unique_name)
+        return unique_name
 
     def purge_doc(self, docname: str) -> None:
         for filename, (docs, unique) in list(self.items()):
@@ -37,7 +48,7 @@ class FilenameUniqDict(dict[str, tuple[set[str], str]]):
                 self._existing.discard(unique)
 
     def merge_other(
-        self, docnames: set[str], other: dict[str, tuple[set[str], Any]]
+        self, docnames: Set[str], other: dict[str, tuple[set[str], str]]
     ) -> None:
         for filename, (docs, _unique) in other.items():
             for doc in docs & set(docnames):
@@ -50,21 +61,26 @@ class FilenameUniqDict(dict[str, tuple[set[str], str]]):
         self._existing = state
 
 
-class DownloadFiles(dict[str, tuple[set[str], str]]):
+class DownloadFiles(dict[Path, tuple[set[str], _StrPath]]):
     """A special dictionary for download files.
 
     .. important:: This class would be refactored in nearly future.
                    Hence don't hack this directly.
     """
 
-    def add_file(self, docname: str, filename: str) -> str:
+    def add_file(self, docname: str, filename: str | os.PathLike[str]) -> _StrPath:
+        filename = Path(filename)
         if filename not in self:
-            digest = hashlib.md5(filename.encode(), usedforsecurity=False).hexdigest()
-            dest = f'{digest}/{os.path.basename(filename)}'
-            self[filename] = (set(), dest)
+            digest = hashlib.md5(
+                filename.as_posix().encode(), usedforsecurity=False
+            ).hexdigest()
+            dest_path = _StrPath(digest, filename.name)
+            self[filename] = ({docname}, dest_path)
+            return dest_path
 
-        self[filename][0].add(docname)
-        return self[filename][1]
+        docnames, dest_path = self[filename]
+        docnames.add(docname)
+        return dest_path
 
     def purge_doc(self, docname: str) -> None:
         for filename, (docs, _dest) in list(self.items()):
@@ -73,7 +89,7 @@ class DownloadFiles(dict[str, tuple[set[str], str]]):
                 del self[filename]
 
     def merge_other(
-        self, docnames: set[str], other: dict[str, tuple[set[str], Any]]
+        self, docnames: Set[str], other: dict[Path, tuple[set[str], _StrPath]]
     ) -> None:
         for filename, (docs, _dest) in other.items():
             for docname in docs & set(docnames):

sphinx/util/_importer.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
 from importlib import import_module
-from typing import Any
+from typing import TYPE_CHECKING
 
 from sphinx.errors import ExtensionError
 
+if TYPE_CHECKING:
+    from typing import Any
+
 
 def import_object(object_name: str, /, source: str = '') -> Any:
     """Import python object by qualname."""

sphinx/util/_inventory_file_reader.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import zlib
+from typing import TYPE_CHECKING
+
+from sphinx.util import logging
+
+BUFSIZE = 16 * 1024
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from typing import Protocol
+
+    # Readable file stream for inventory loading
+    class _SupportsRead(Protocol):
+        def read(self, size: int = ...) -> bytes: ...
+
+
+__all__ = ('InventoryFileReader',)
+
+
+class InventoryFileReader:
+    """A file reader for an inventory file.
+
+    This reader supports mixture of texts and compressed texts.
+    """
+
+    def __init__(self, stream: _SupportsRead) -> None:
+        self.stream = stream
+        self.buffer = b''
+        self.eof = False
+
+    def read_buffer(self) -> None:
+        chunk = self.stream.read(BUFSIZE)
+        if chunk == b'':
+            self.eof = True
+        self.buffer += chunk
+
+    def readline(self) -> str:
+        pos = self.buffer.find(b'\n')
+        if pos != -1:
+            line = self.buffer[:pos].decode()
+            self.buffer = self.buffer[pos + 1 :]
+        elif self.eof:
+            line = self.buffer.decode()
+            self.buffer = b''
+        else:
+            self.read_buffer()
+            line = self.readline()
+
+        return line
+
+    def readlines(self) -> Iterator[str]:
+        while not self.eof:
+            line = self.readline()
+            if line:
+                yield line
+
+    def read_compressed_chunks(self) -> Iterator[bytes]:
+        decompressor = zlib.decompressobj()
+        while not self.eof:
+            self.read_buffer()
+            yield decompressor.decompress(self.buffer)
+            self.buffer = b''
+        yield decompressor.flush()
+
+    def read_compressed_lines(self) -> Iterator[str]:
+        buf = b''
+        for chunk in self.read_compressed_chunks():
+            buf += chunk
+            pos = buf.find(b'\n')
+            while pos != -1:
+                yield buf[:pos].decode()
+                buf = buf[pos + 1 :]
+                pos = buf.find(b'\n')

sphinx/util/_io.py

@@ -2,13 +2,13 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from sphinx.util.console import strip_escape_sequences
+from sphinx._cli.util.errors import strip_escape_sequences
 
 if TYPE_CHECKING:
     from typing import Protocol
 
     class SupportsWrite(Protocol):
-        def write(self, text: str, /) -> int | None: ...  # NoQA: E704
+        def write(self, text: str, /) -> int | None: ...
 
 
 class TeeStripANSI:

sphinx/util/_lines.py

@@ -1,3 +1,6 @@
+from __future__ import annotations
+
+
 def parse_line_num_spec(spec: str, total: int) -> list[int]:
     """Parse a line number spec (such as "1,2,4-6") and return a list of
     wanted line numbers.
@@ -8,17 +11,17 @@ def parse_line_num_spec(spec: str, total: int) -> list[int]:
         try:
             begend = part.strip().split('-')
             if begend == ['', '']:
-                raise ValueError
+                raise ValueError  # NoQA: TRY301
             if len(begend) == 1:
                 items.append(int(begend[0]) - 1)
             elif len(begend) == 2:
                 start = int(begend[0] or 1)  # left half open (cf. -10)
                 end = int(begend[1] or max(start, total))  # right half open (cf. 10-)
                 if start > end:  # invalid range (cf. 10-1)
-                    raise ValueError
+                    raise ValueError  # NoQA: TRY301
                 items.extend(range(start - 1, end))
             else:
-                raise ValueError
+                raise ValueError  # NoQA: TRY301
         except ValueError as exc:
             msg = f'invalid line number spec: {spec!r}'
             raise ValueError(msg) from exc

sphinx/util/_pathlib.py

@@ -3,7 +3,7 @@
 Instances of _StrPath should not be constructed except in Sphinx itself.
 Consumers of Sphinx APIs should prefer using ``pathlib.Path`` objects
 where possible. _StrPath objects can be treated as equivalent to ``Path``,
-save that ``_StrPath.replace`` is overriden with ``str.replace``.
+save that ``_StrPath.replace`` is overridden with ``str.replace``.
 
 To continue treating path-like objects as strings, use ``os.fspath``,
 or explicit string coercion.
@@ -17,10 +17,13 @@ from __future__ import annotations
 import sys
 import warnings
 from pathlib import Path, PosixPath, PurePath, WindowsPath
-from typing import Any
+from typing import TYPE_CHECKING, overload
 
 from sphinx.deprecation import RemovedInSphinx90Warning
 
+if TYPE_CHECKING:
+    from typing import Any
+
 _STR_METHODS = frozenset(str.__dict__)
 _PATH_NAME = Path().__class__.__name__
 
@@ -133,3 +136,38 @@ else:
         def __len__(self) -> int:
             warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return len(self.__str__())
+
+
+class _StrPathProperty:
+    def __init__(self) -> None:
+        self.instance_attr: str = ''
+
+    def __set_name__(self, owner: object, name: str) -> None:
+        self.instance_attr = f'_{name}'  # i.e. '_srcdir'
+
+    @overload
+    def __get__(self, obj: None, objtype: None) -> _StrPathProperty: ...
+
+    @overload
+    def __get__(self, obj: object, objtype: type[object]) -> _StrPath: ...
+
+    def __get__(
+        self, obj: object | None, objtype: type[object] | None = None
+    ) -> _StrPathProperty | _StrPath:
+        if obj is None:
+            return self
+        if not self.instance_attr:
+            raise AttributeError
+        return getattr(obj, self.instance_attr)
+
+    def __set__(self, obj: Any, value: _StrPath | Path) -> None:
+        try:
+            setattr(obj, self.instance_attr, _StrPath(value))
+        except TypeError as err:
+            cls_name = type(obj).__qualname__
+            name = self.instance_attr.removeprefix('_')
+            msg = f'{cls_name}.{name} may only be set to path-like objects'
+            raise TypeError(msg) from err
+
+    def __delete__(self, obj: Any) -> None:
+        delattr(obj, self.instance_attr)

sphinx/util/build_phase.py

@@ -1,5 +1,7 @@
 """Build phase of Sphinx application."""
 
+from __future__ import annotations
+
 from enum import IntEnum
 
 

sphinx/util/cfamily.py

@@ -13,7 +13,7 @@ from sphinx.util import logging
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
-    from typing import Any, TypeAlias
+    from typing import Any, NoReturn, TypeAlias
 
     from docutils.nodes import TextElement
 
@@ -33,7 +33,7 @@ identifier_re = re.compile(
     |   (@[a-zA-Z0-9_])  # our extension for names of anonymous entities
     )
     [a-zA-Z0-9_]*\b
-""",
+    """,
     flags=re.VERBOSE,
 )
 integer_literal_re = re.compile(r'[1-9][0-9]*(\'[0-9]+)*')
@@ -50,7 +50,7 @@ integers_literal_suffix_re = re.compile(
     )\b
     # the ending word boundary is important for distinguishing
     # between suffixes and UDLs in C++
-""",
+    """,
     flags=re.VERBOSE,
 )
 float_literal_re = re.compile(
@@ -66,7 +66,7 @@ float_literal_re = re.compile(
         [0-9a-fA-F]+(\'[0-9a-fA-F]+)*([pP][+-]?[0-9a-fA-F]+(\'[0-9a-fA-F]+)*)?)
     | (0[xX][0-9a-fA-F]+(\'[0-9a-fA-F]+)*\.([pP][+-]?[0-9a-fA-F]+(\'[0-9a-fA-F]+)*)?)
     )
-""",
+    """,
     flags=re.VERBOSE,
 )
 float_literal_suffix_re = re.compile(r'[fFlL]\b')
@@ -84,13 +84,13 @@ char_literal_re = re.compile(
       | (?:U[0-9a-fA-F]{8})
       ))
     )'
-""",
+    """,
     flags=re.VERBOSE,
 )
 
 
 def verify_description_mode(mode: str) -> None:
-    if mode not in ('lastIsName', 'noneIsName', 'markType', 'markName', 'param', 'udl'):
+    if mode not in {'lastIsName', 'noneIsName', 'markType', 'markName', 'param', 'udl'}:
         raise Exception("Description mode '%s' is invalid." % mode)
 
 
@@ -108,11 +108,14 @@ class ASTBaseBase:
         except AttributeError:
             return False
 
+    def __hash__(self) -> int:
+        return hash(sorted(self.__dict__.items()))
+
     def clone(self) -> Any:
         return deepcopy(self)
 
     def _stringify(self, transform: StringifyTransform) -> str:
-        raise NotImplementedError(repr(self))
+        raise NotImplementedError
 
     def __str__(self) -> str:
         return self._stringify(str)
@@ -121,7 +124,9 @@ class ASTBaseBase:
         return self._stringify(lambda ast: ast.get_display_string())
 
     def __repr__(self) -> str:
-        return f'<{self.__class__.__name__}: {self._stringify(repr)}>'
+        if repr_string := self._stringify(repr):
+            return f'<{self.__class__.__name__}: {repr_string}>'
+        return f'<{self.__class__.__name__}>'
 
 
 ################################################################################
@@ -336,7 +341,7 @@ class BaseParser:
         indicator = '-' * self.pos + '^'
         logger.debug(f'{msg}\n{self.definition}\n{indicator}')  # NoQA: G004
 
-    def fail(self, msg: str) -> None:
+    def fail(self, msg: str) -> NoReturn:
         errors = []
         indicator = '-' * self.pos + '^'
         msg = (
@@ -431,7 +436,7 @@ class BaseParser:
     def _parse_balanced_token_seq(self, end: list[str]) -> str:
         # TODO: add handling of string literals and similar
         brackets = {'(': ')', '[': ']', '{': '}'}
-        startPos = self.pos
+        start_pos = self.pos
         symbols: list[str] = []
         while not self.eof:
             if len(symbols) == 0 and self.current_char in end:
@@ -445,17 +450,17 @@ class BaseParser:
             self.pos += 1
         if self.eof:
             self.fail(
-                f'Could not find end of balanced-token-seq starting at {startPos}.'
+                f'Could not find end of balanced-token-seq starting at {start_pos}.'
             )
-        return self.definition[startPos : self.pos]
+        return self.definition[start_pos : self.pos]
 
     def _parse_attribute(self) -> ASTAttribute | None:
         self.skip_ws()
         # try C++11 style
-        startPos = self.pos
+        start_pos = self.pos
         if self.skip_string_and_ws('['):
             if not self.skip_string('['):
-                self.pos = startPos
+                self.pos = start_pos
             else:
                 # TODO: actually implement the correct grammar
                 arg = self._parse_balanced_token_seq(end=[']'])