Sphinx 8.0.2__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/util/__init__.py

@@ -6,15 +6,14 @@ import hashlib
 import os
 import posixpath
 import re
-from importlib import import_module
-from os import path
-from typing import IO, Any
-from urllib.parse import parse_qsl, quote_plus, urlencode, urlsplit, urlunsplit
+from typing import Any
 
-from sphinx.errors import ExtensionError, FiletypeNotFoundError
-from sphinx.locale import __
+from sphinx.errors import FiletypeNotFoundError
+from sphinx.util import _files, _importer, logging
 from sphinx.util import index_entries as _index_entries
-from sphinx.util import logging
+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
@@ -44,11 +43,14 @@ 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:]
 
 
-def get_filetype(source_suffix: dict[str, str], filename: str | os.PathLike) -> str:
+def get_filetype(
+    source_suffix: dict[str, str], filename: str | os.PathLike[str]
+) -> str:
     for suffix, filetype in source_suffix.items():
         if os.fspath(filename).endswith(suffix):
             # If default filetype (None), considered as restructuredtext.
@@ -56,49 +58,6 @@ def get_filetype(source_suffix: dict[str, str], filename: str | os.PathLike) ->
     raise FiletypeNotFoundError
 
 
-class FilenameUniqDict(dict):
-    """
-    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:
-        self._existing: set[str] = set()
-
-    def add_file(self, docname: str, newfile: str) -> str:
-        if newfile in self:
-            self[newfile][0].add(docname)
-            return self[newfile][1]
-        uniquename = path.basename(newfile)
-        base, ext = path.splitext(uniquename)
-        i = 0
-        while uniquename in self._existing:
-            i += 1
-            uniquename = f'{base}{i}{ext}'
-        self[newfile] = ({docname}, uniquename)
-        self._existing.add(uniquename)
-        return uniquename
-
-    def purge_doc(self, docname: str) -> None:
-        for filename, (docs, unique) in list(self.items()):
-            docs.discard(docname)
-            if not docs:
-                del self[filename]
-                self._existing.discard(unique)
-
-    def merge_other(self, docnames: set[str], other: dict[str, tuple[set[str], Any]]) -> None:
-        for filename, (docs, _unique) in other.items():
-            for doc in docs & set(docnames):
-                self.add_file(doc, filename)
-
-    def __getstate__(self) -> set[str]:
-        return self._existing
-
-    def __setstate__(self, state: set[str]) -> None:
-        self._existing = state
-
-
 def _md5(data: bytes = b'', **_kw: Any) -> hashlib._Hash:
     """Deprecated wrapper around hashlib.md5
 
@@ -115,153 +74,23 @@ def _sha1(data: bytes = b'', **_kw: Any) -> hashlib._Hash:
     return hashlib.sha1(data, usedforsecurity=False)
 
 
-class DownloadFiles(dict):
-    """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:
-        if filename not in self:
-            digest = hashlib.md5(filename.encode(), usedforsecurity=False).hexdigest()
-            dest = f'{digest}/{os.path.basename(filename)}'
-            self[filename] = (set(), dest)
-
-        self[filename][0].add(docname)
-        return self[filename][1]
-
-    def purge_doc(self, docname: str) -> None:
-        for filename, (docs, _dest) in list(self.items()):
-            docs.discard(docname)
-            if not docs:
-                del self[filename]
-
-    def merge_other(self, docnames: set[str], other: dict[str, tuple[set[str], Any]]) -> None:
-        for filename, (docs, _dest) in other.items():
-            for docname in docs & set(docnames):
-                self.add_file(docname, filename)
-
-
-# a regex to recognize coding cookies
-_coding_re = re.compile(r'coding[:=]\s*([-\w.]+)')
-
-
-class UnicodeDecodeErrorHandler:
-    """Custom error handler for open() that warns and replaces."""
-
-    def __init__(self, docname: str) -> None:
-        self.docname = docname
-
-    def __call__(self, error: UnicodeDecodeError) -> tuple[str, int]:
-        linestart = error.object.rfind(b'\n', 0, error.start)
-        lineend = error.object.find(b'\n', error.start)
-        if lineend == -1:
-            lineend = len(error.object)
-        lineno = error.object.count(b'\n', 0, error.start) + 1
-        logger.warning(__('undecodable source characters, replacing with "?": %r'),
-                       (error.object[linestart + 1:error.start] + b'>>>' +
-                        error.object[error.start:error.end] + b'<<<' +
-                        error.object[error.end:lineend]),
-                       location=(self.docname, lineno))
-        return ('?', error.end)
-
-
-# Low-level utility functions and classes.
-
-class Tee:
-    """
-    File-like object writing to two streams.
-    """
-
-    def __init__(self, stream1: IO, stream2: IO) -> None:
-        self.stream1 = stream1
-        self.stream2 = stream2
-
-    def write(self, text: str) -> None:
-        self.stream1.write(text)
-        self.stream2.write(text)
-
-    def flush(self) -> None:
-        if hasattr(self.stream1, 'flush'):
-            self.stream1.flush()
-        if hasattr(self.stream2, 'flush'):
-            self.stream2.flush()
-
-
-def parselinenos(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.
-    """
-    items = []
-    parts = spec.split(',')
-    for part in parts:
-        try:
-            begend = part.strip().split('-')
-            if begend == ['', '']:
-                raise ValueError
-            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
-                items.extend(range(start - 1, end))
-            else:
-                raise ValueError
-        except ValueError as exc:
-            msg = f'invalid line number spec: {spec!r}'
-            raise ValueError(msg) from exc
-
-    return items
-
-
-def import_object(objname: str, source: str | None = None) -> Any:
-    """Import python object by qualname."""
-    try:
-        objpath = objname.split('.')
-        modname = objpath.pop(0)
-        obj = import_module(modname)
-        for name in objpath:
-            modname += '.' + name
-            try:
-                obj = getattr(obj, name)
-            except AttributeError:
-                obj = import_module(modname)
-
-        return obj
-    except (AttributeError, ImportError) as exc:
-        if source:
-            raise ExtensionError('Could not import %s (needed for %s)' %
-                                 (objname, source), exc) from exc
-        raise ExtensionError('Could not import %s' % objname, exc) from exc
-
-
-def encode_uri(uri: str) -> str:
-    split = list(urlsplit(uri))
-    split[1] = split[1].encode('idna').decode('ascii')
-    split[2] = quote_plus(split[2].encode(), '/')
-    query = [(q, v.encode()) for (q, v) in parse_qsl(split[3])]
-    split[3] = urlencode(query)
-    return urlunsplit(split)
-
-
-def isurl(url: str) -> bool:
-    """Check *url* is URL or not."""
-    return bool(url) and '://' in url
-
-
 # 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)),
+    '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),
+    ),
     '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)),
 }
 
 

sphinx/util/_files.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import hashlib
+import os.path
+from typing import Any
+
+
+class FilenameUniqDict(dict[str, tuple[set[str], str]]):
+    """
+    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:
+        self._existing: set[str] = set()
+
+    def add_file(self, docname: str, newfile: str) -> str:
+        if newfile in self:
+            self[newfile][0].add(docname)
+            return self[newfile][1]
+        uniquename = os.path.basename(newfile)
+        base, ext = os.path.splitext(uniquename)
+        i = 0
+        while uniquename in self._existing:
+            i += 1
+            uniquename = f'{base}{i}{ext}'
+        self[newfile] = ({docname}, uniquename)
+        self._existing.add(uniquename)
+        return uniquename
+
+    def purge_doc(self, docname: str) -> None:
+        for filename, (docs, unique) in list(self.items()):
+            docs.discard(docname)
+            if not docs:
+                del self[filename]
+                self._existing.discard(unique)
+
+    def merge_other(
+        self, docnames: set[str], other: dict[str, tuple[set[str], Any]]
+    ) -> None:
+        for filename, (docs, _unique) in other.items():
+            for doc in docs & set(docnames):
+                self.add_file(doc, filename)
+
+    def __getstate__(self) -> set[str]:
+        return self._existing
+
+    def __setstate__(self, state: set[str]) -> None:
+        self._existing = state
+
+
+class DownloadFiles(dict[str, tuple[set[str], str]]):
+    """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:
+        if filename not in self:
+            digest = hashlib.md5(filename.encode(), usedforsecurity=False).hexdigest()
+            dest = f'{digest}/{os.path.basename(filename)}'
+            self[filename] = (set(), dest)
+
+        self[filename][0].add(docname)
+        return self[filename][1]
+
+    def purge_doc(self, docname: str) -> None:
+        for filename, (docs, _dest) in list(self.items()):
+            docs.discard(docname)
+            if not docs:
+                del self[filename]
+
+    def merge_other(
+        self, docnames: set[str], other: dict[str, tuple[set[str], Any]]
+    ) -> None:
+        for filename, (docs, _dest) in other.items():
+            for docname in docs & set(docnames):
+                self.add_file(docname, filename)

sphinx/util/_importer.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+from sphinx.errors import ExtensionError
+
+
+def import_object(object_name: str, /, source: str = '') -> Any:
+    """Import python object by qualname."""
+    obj_path = object_name.split('.')
+    module_name = obj_path.pop(0)
+    try:
+        obj = import_module(module_name)
+        for name in obj_path:
+            module_name += '.' + name
+            try:
+                obj = getattr(obj, name)
+            except AttributeError:
+                obj = import_module(module_name)
+    except (AttributeError, ImportError) as exc:
+        if source:
+            msg = f'Could not import {object_name} (needed for {source})'
+            raise ExtensionError(msg, exc) from exc
+        msg = f'Could not import {object_name}'
+        raise ExtensionError(msg, exc) from exc
+    return obj

sphinx/util/_io.py

@@ -8,8 +8,7 @@ if TYPE_CHECKING:
     from typing import Protocol
 
     class SupportsWrite(Protocol):
-        def write(self, text: str, /) -> int | None:
-            ...
+        def write(self, text: str, /) -> int | None: ...  # NoQA: E704
 
 
 class TeeStripANSI:

sphinx/util/_lines.py

@@ -0,0 +1,26 @@
+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.
+    """
+    items = []
+    parts = spec.split(',')
+    for part in parts:
+        try:
+            begend = part.strip().split('-')
+            if begend == ['', '']:
+                raise ValueError
+            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
+                items.extend(range(start - 1, end))
+            else:
+                raise ValueError
+        except ValueError as exc:
+            msg = f'invalid line number spec: {spec!r}'
+            raise ValueError(msg) from exc
+
+    return items

sphinx/util/_pathlib.py

@@ -33,9 +33,10 @@ _MSG = (
 # https://docs.python.org/3/library/stdtypes.html#string-methods
 
 if sys.platform == 'win32':
+
     class _StrPath(WindowsPath):
         def replace(  # type: ignore[override]
-            self, old: str, new: str, count: int = -1, /,
+            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
@@ -81,10 +82,12 @@ if sys.platform == 'win32':
         def __len__(self) -> int:
             warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return len(self.__str__())
+
 else:
+
     class _StrPath(PosixPath):
         def replace(  # type: ignore[override]
-            self, old: str, new: str, count: int = -1, /,
+            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

sphinx/util/_serialise.py

@@ -0,0 +1,53 @@
+"""Serialise objects to a stable representation."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import types
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+def stable_hash(obj: Any) -> str:
+    """Return a stable hash for a Python data structure.
+
+    We can't just use the md5 of str(obj) as the order of collections
+    may be random.
+    """
+    if isinstance(obj, dict):
+        obj = sorted(map(stable_hash, obj.items()))
+    if isinstance(obj, list | tuple | set | frozenset):
+        obj = sorted(map(stable_hash, obj))
+    elif isinstance(obj, type | types.FunctionType):
+        # The default repr() of functions includes the ID, which is not ideal.
+        # We use the fully qualified name instead.
+        obj = f'{obj.__module__}.{obj.__qualname__}'
+    return hashlib.md5(str(obj).encode(), usedforsecurity=False).hexdigest()
+
+
+def stable_str(obj: Any, *, indent: int | None = None) -> str:
+    """Return a stable string representation of a Python data structure.
+
+    We can't just use ``str(obj)`` as the order of collections may be random.
+    """
+    return json.dumps(_stable_str_prep(obj), indent=indent)
+
+
+def _stable_str_prep(obj: Any) -> dict[str, Any] | list[Any] | str:
+    if isinstance(obj, dict):
+        # Convert to a sorted dict
+        obj = [(_stable_str_prep(k), _stable_str_prep(v)) for k, v in obj.items()]
+        obj.sort()
+        return dict(obj)
+    if isinstance(obj, list | tuple | set | frozenset):
+        # Convert to a sorted list
+        return sorted(map(_stable_str_prep, obj), key=str)
+    if isinstance(obj, type | types.FunctionType):
+        # The default repr() of functions includes the ID, which is not ideal.
+        # We use the fully qualified name instead.
+        return f'{obj.__module__}.{obj.__qualname__}'
+    # We can't do any better, just use the string representation
+    return str(obj)

sphinx/util/_timestamps.py

@@ -9,4 +9,5 @@ def _format_rfc3339_microseconds(timestamp: int, /) -> str:
     :param timestamp: The timestamp to format, in microseconds.
     """
     seconds, fraction = divmod(timestamp, 10**6)
-    return time.strftime('%Y-%m-%d %H:%M:%S', time.gmtime(seconds)) + f'.{fraction // 1_000}'
+    time_tuple = time.gmtime(seconds)
+    return time.strftime('%Y-%m-%d %H:%M:%S', time_tuple) + f'.{fraction // 1_000}'

sphinx/util/_uri.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from urllib.parse import parse_qsl, quote_plus, urlencode, urlsplit, urlunsplit
+
+
+def encode_uri(uri: str) -> str:
+    scheme, netloc, url, query, fragment = urlsplit(uri)
+    netloc = netloc.encode('idna').decode('ascii')
+    url = quote_plus(url.encode(), '/')
+    query = urlencode([(q, v.encode()) for (q, v) in parse_qsl(query)])
+    return urlunsplit((scheme, netloc, url, query, fragment))
+
+
+def is_url(url: str) -> bool:
+    """Check *url* is URL or not."""
+    return bool(url) and '://' in url