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

sphinx/util/inventory.py

@@ -2,11 +2,13 @@
 
 from __future__ import annotations
 
-import os
+import posixpath
 import re
+import warnings
 import zlib
 from typing import TYPE_CHECKING
 
+from sphinx.deprecation import RemovedInSphinx10Warning
 from sphinx.locale import __
 from sphinx.util import logging
 
@@ -14,127 +16,101 @@ BUFSIZE = 16 * 1024
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator
+    import os
+    from collections.abc import Callable, Iterator, Sequence
+    from typing import NoReturn, Protocol
 
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
-    from sphinx.util.typing import Inventory, InventoryItem, _ReadableStream
-
-
-class InventoryFileReader:
-    """A file reader for an inventory file.
-
-    This reader supports mixture of texts and compressed texts.
-    """
-
-    def __init__(self, stream: _ReadableStream[bytes]) -> 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')
+    from sphinx.util.typing import Inventory
+
+    # Readable file stream for inventory loading
+    class _SupportsRead(Protocol):
+        def read(self, size: int = ...) -> bytes: ...
+
+    _JoinFunc = Callable[[str, str], str]
+
+
+def __getattr__(name: str) -> object:
+    if name == 'InventoryFileReader':
+        from sphinx.util._inventory_file_reader import InventoryFileReader
+
+        return InventoryFileReader
+    msg = f'module {__name__!r} has no attribute {name!r}'
+    raise AttributeError(msg)
 
 
 class InventoryFile:
     @classmethod
-    def load(
-        cls: type[InventoryFile],
-        stream: _ReadableStream[bytes],
+    def loads(
+        cls,
+        content: bytes,
+        *,
         uri: str,
-        joinfunc: Callable[[str, str], str],
-    ) -> Inventory:
-        reader = InventoryFileReader(stream)
-        line = reader.readline().rstrip()
-        if line == '# Sphinx inventory version 1':
-            return cls.load_v1(reader, uri, joinfunc)
-        elif line == '# Sphinx inventory version 2':
-            return cls.load_v2(reader, uri, joinfunc)
-        else:
-            raise ValueError('invalid inventory header: %s' % line)
+    ) -> _Inventory:
+        format_line, _, content = content.partition(b'\n')
+        format_line = format_line.rstrip()  # remove trailing \r or spaces
+        if format_line == b'# Sphinx inventory version 2':
+            return cls._loads_v2(content, uri=uri)
+        if format_line == b'# Sphinx inventory version 1':
+            lines = content.decode().splitlines()
+            return cls._loads_v1(lines, uri=uri)
+        if format_line.startswith(b'# Sphinx inventory version '):
+            unknown_version = format_line[27:].decode()
+            msg = f'unknown or unsupported inventory version: {unknown_version!r}'
+            raise ValueError(msg)
+        msg = f'invalid inventory header: {format_line.decode()}'
+        raise ValueError(msg)
 
     @classmethod
-    def load_v1(
-        cls: type[InventoryFile],
-        stream: InventoryFileReader,
-        uri: str,
-        join: Callable[[str, str], str],
-    ) -> Inventory:
-        invdata: Inventory = {}
-        projname = stream.readline().rstrip()[11:]
-        version = stream.readline().rstrip()[11:]
-        for line in stream.readlines():
-            name, type, location = line.rstrip().split(None, 2)
-            location = join(uri, location)
+    def load(cls, stream: _SupportsRead, uri: str, joinfunc: _JoinFunc) -> Inventory:
+        return cls.loads(stream.read(), uri=uri).data
+
+    @classmethod
+    def _loads_v1(cls, lines: Sequence[str], *, uri: str) -> _Inventory:
+        if len(lines) < 2:
+            msg = 'invalid inventory header: missing project name or version'
+            raise ValueError(msg)
+        inv = _Inventory({})
+        projname = lines[0].rstrip()[11:]  # Project name
+        version = lines[1].rstrip()[11:]  # Project version
+        for line in lines[2:]:
+            name, item_type, location = line.rstrip().split(None, 2)
+            location = posixpath.join(uri, location)
             # version 1 did not add anchors to the location
-            if type == 'mod':
-                type = 'py:module'
-                location += '#module-' + name
+            if item_type == 'mod':
+                item_type = 'py:module'
+                location += f'#module-{name}'
             else:
-                type = 'py:' + type
-                location += '#' + name
-            invdata.setdefault(type, {})[name] = (projname, version, location, '-')
-        return invdata
+                item_type = f'py:{item_type}'
+                location += f'#{name}'
+            inv[item_type, name] = _InventoryItem(
+                project_name=projname,
+                project_version=version,
+                uri=location,
+                display_name='-',
+            )
+        return inv
 
     @classmethod
-    def load_v2(
-        cls: type[InventoryFile],
-        stream: InventoryFileReader,
-        uri: str,
-        join: Callable[[str, str], str],
-    ) -> Inventory:
-        invdata: Inventory = {}
-        projname = stream.readline().rstrip()[11:]
-        version = stream.readline().rstrip()[11:]
-        # definition -> priority, location, display name
+    def _loads_v2(cls, inv_data: bytes, *, uri: str) -> _Inventory:
+        try:
+            line_1, line_2, check_line, compressed = inv_data.split(b'\n', maxsplit=3)
+        except ValueError:
+            msg = 'invalid inventory header: missing project name or version'
+            raise ValueError(msg) from None
+        inv = _Inventory({})
+        projname = line_1.rstrip()[11:].decode()  # Project name
+        version = line_2.rstrip()[11:].decode()  # Project version
+        # definition -> (priority, location, display name)
         potential_ambiguities: dict[str, tuple[str, str, str]] = {}
         actual_ambiguities = set()
-        line = stream.readline()
-        if 'zlib' not in line:
-            raise ValueError('invalid inventory header (not compressed): %s' % line)
+        if b'zlib' not in check_line:  # '... compressed using zlib'
+            msg = f'invalid inventory header (not compressed): {check_line.decode()}'
+            raise ValueError(msg)
 
-        for line in stream.read_compressed_lines():
+        decompressed_content = zlib.decompress(compressed)
+        for line in decompressed_content.decode().splitlines():
             # be careful to handle names with embedded spaces correctly
             m = re.match(
                 r'(.+?)\s+(\S+)\s+(-?\d+)\s+?(\S*)\s+(.*)',
@@ -147,9 +123,10 @@ class InventoryFile:
             if ':' not in type:
                 # wrong type value. type should be in the form of "{domain}:{objtype}"
                 #
-                # Note: To avoid the regex DoS, this is implemented in python (refs: #8175)
+                # Note: To avoid the regex DoS, this is implemented in Python
+                # See: https://github.com/sphinx-doc/sphinx/issues/8175
                 continue
-            if type == 'py:module' and type in invdata and name in invdata[type]:
+            if type == 'py:module' and (type, name) in inv:
                 # due to a bug in 1.1 and below,
                 # two inventory entries are created
                 # for Python modules, and the first
@@ -177,9 +154,13 @@ class InventoryFile:
                     potential_ambiguities[lowercase_definition] = content
             if location.endswith('$'):
                 location = location[:-1] + name
-            location = join(uri, location)
-            inv_item: InventoryItem = projname, version, location, dispname
-            invdata.setdefault(type, {})[name] = inv_item
+            location = posixpath.join(uri, location)
+            inv[type, name] = _InventoryItem(
+                project_name=projname,
+                project_version=version,
+                uri=location,
+                display_name=dispname,
+            )
         for ambiguity in actual_ambiguities:
             logger.info(
                 __('inventory <%s> contains multiple definitions for %s'),
@@ -188,19 +169,16 @@ class InventoryFile:
                 type='intersphinx',
                 subtype='external',
             )
-        return invdata
+        return inv
 
     @classmethod
     def dump(
-        cls: type[InventoryFile],
-        filename: str,
-        env: BuildEnvironment,
-        builder: Builder,
+        cls, filename: str | os.PathLike[str], env: BuildEnvironment, builder: Builder
     ) -> None:
         def escape(string: str) -> str:
             return re.sub('\\s+', ' ', string)
 
-        with open(os.path.join(filename), 'wb') as f:
+        with open(filename, 'wb') as f:
             # header
             f.write(
                 (
@@ -227,3 +205,124 @@ class InventoryFile:
                     entry = f'{fullname} {domain.name}:{type} {prio} {uri} {dispname}\n'
                     f.write(compressor.compress(entry.encode()))
             f.write(compressor.flush())
+
+
+class _Inventory:
+    """Inventory data in memory."""
+
+    __slots__ = ('data',)
+
+    data: dict[str, dict[str, _InventoryItem]]
+
+    def __init__(self, data: dict[str, dict[str, _InventoryItem]], /) -> None:
+        # type -> name -> _InventoryItem
+        self.data: dict[str, dict[str, _InventoryItem]] = data
+
+    def __repr__(self) -> str:
+        return f'_Inventory({self.data!r})'
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _Inventory):
+            return NotImplemented
+        return self.data == other.data
+
+    def __hash__(self) -> int:
+        return hash(self.data)
+
+    def __getitem__(self, item: tuple[str, str]) -> _InventoryItem:
+        obj_type, name = item
+        return self.data.setdefault(obj_type, {})[name]
+
+    def __setitem__(self, item: tuple[str, str], value: _InventoryItem) -> None:
+        obj_type, name = item
+        self.data.setdefault(obj_type, {})[name] = value
+
+    def __contains__(self, item: tuple[str, str]) -> bool:
+        obj_type, name = item
+        return obj_type in self.data and name in self.data[obj_type]
+
+
+class _InventoryItem:
+    __slots__ = 'project_name', 'project_version', 'uri', 'display_name'
+
+    project_name: str
+    project_version: str
+    uri: str
+    display_name: str
+
+    def __init__(
+        self,
+        *,
+        project_name: str,
+        project_version: str,
+        uri: str,
+        display_name: str,
+    ) -> None:
+        object.__setattr__(self, 'project_name', project_name)
+        object.__setattr__(self, 'project_version', project_version)
+        object.__setattr__(self, 'uri', uri)
+        object.__setattr__(self, 'display_name', display_name)
+
+    def __repr__(self) -> str:
+        return (
+            '_InventoryItem('
+            f'project_name={self.project_name!r}, '
+            f'project_version={self.project_version!r}, '
+            f'uri={self.uri!r}, '
+            f'display_name={self.display_name!r}'
+            ')'
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _InventoryItem):
+            return NotImplemented
+        return (
+            self.project_name == other.project_name
+            and self.project_version == other.project_version
+            and self.uri == other.uri
+            and self.display_name == other.display_name
+        )
+
+    def __hash__(self) -> int:
+        return hash((
+            self.project_name,
+            self.project_version,
+            self.uri,
+            self.display_name,
+        ))
+
+    def __setattr__(self, key: str, value: object) -> NoReturn:
+        msg = '_InventoryItem is immutable'
+        raise AttributeError(msg)
+
+    def __delattr__(self, key: str) -> NoReturn:
+        msg = '_InventoryItem is immutable'
+        raise AttributeError(msg)
+
+    def __getstate__(self) -> tuple[str, str, str, str]:
+        return self.project_name, self.project_version, self.uri, self.display_name
+
+    def __setstate__(self, state: tuple[str, str, str, str]) -> None:
+        project_name, project_version, uri, display_name = state
+        object.__setattr__(self, 'project_name', project_name)
+        object.__setattr__(self, 'project_version', project_version)
+        object.__setattr__(self, 'uri', uri)
+        object.__setattr__(self, 'display_name', display_name)
+
+    def __getitem__(self, key: int | slice) -> str | tuple[str, ...]:
+        warnings.warn(
+            'The tuple interface for _InventoryItem objects is deprecated.',
+            RemovedInSphinx10Warning,
+            stacklevel=2,
+        )
+        tpl = self.project_name, self.project_version, self.uri, self.display_name
+        return tpl[key]
+
+    def __iter__(self) -> Iterator[str]:
+        warnings.warn(
+            'The iter() interface for _InventoryItem objects is deprecated.',
+            RemovedInSphinx10Warning,
+            stacklevel=2,
+        )
+        tpl = self.project_name, self.project_version, self.uri, self.display_name
+        return iter(tpl)

sphinx/util/logging.py

@@ -4,20 +4,20 @@ from __future__ import annotations
 
 import logging
 import logging.handlers
+import os.path
 from collections import defaultdict
 from contextlib import contextmanager, nullcontext
-from typing import IO, TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.utils import get_source_line
 
+from sphinx._cli.util.colour import colourise
 from sphinx.errors import SphinxWarning
-from sphinx.util.console import colorize
-from sphinx.util.osutil import abspath
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Sequence, Set
-    from typing import NoReturn
+    from collections.abc import Iterator, Mapping, Sequence, Set
+    from typing import IO, Any, NoReturn
 
     from docutils.nodes import Node
 
@@ -49,14 +49,11 @@ VERBOSITY_MAP: defaultdict[int, int] = defaultdict(
     },
 )
 
-COLOR_MAP: defaultdict[int, str] = defaultdict(
-    lambda: 'blue',
-    {
-        logging.ERROR: 'darkred',
-        logging.WARNING: 'red',
-        logging.DEBUG: 'darkgray',
-    },
-)
+COLOR_MAP: dict[int, str] = {
+    logging.ERROR: 'darkred',
+    logging.WARNING: 'red',
+    logging.DEBUG: 'darkgray',
+}
 
 
 def getLogger(name: str) -> SphinxLoggerAdapter:
@@ -129,7 +126,7 @@ class SphinxWarningLogRecord(SphinxLogRecord):
             return 'WARNING: '
 
 
-class SphinxLoggerAdapter(logging.LoggerAdapter):
+class SphinxLoggerAdapter(logging.LoggerAdapter[logging.Logger]):
     """LoggerAdapter allowing ``type`` and ``subtype`` keywords."""
 
     KEYWORDS = ['type', 'subtype', 'location', 'nonl', 'color', 'once']
@@ -146,7 +143,7 @@ class SphinxLoggerAdapter(logging.LoggerAdapter):
     def verbose(self, msg: str, *args: Any, **kwargs: Any) -> None:
         self.log(VERBOSE, msg, *args, **kwargs)
 
-    def process(self, msg: str, kwargs: dict) -> tuple[str, dict]:  # type: ignore[override]
+    def process(self, msg: str, kwargs: dict[str, Any]) -> tuple[str, dict[str, Any]]:  # type: ignore[override]
         extra = kwargs.setdefault('extra', {})
         for keyword in self.KEYWORDS:
             if keyword in kwargs:
@@ -161,9 +158,9 @@ class SphinxLoggerAdapter(logging.LoggerAdapter):
         self,
         msg: object,
         *args: object,
-        type: None | str = None,
-        subtype: None | str = None,
-        location: None | str | tuple[str | None, int | None] | Node = None,
+        type: str | None = None,
+        subtype: str | None = None,
+        location: str | tuple[str | None, int | None] | Node | None = None,
         nonl: bool = True,
         color: str | None = None,
         once: bool = False,
@@ -204,13 +201,13 @@ class SphinxLoggerAdapter(logging.LoggerAdapter):
         )
 
 
-class WarningStreamHandler(logging.StreamHandler):
+class WarningStreamHandler(logging.StreamHandler['SafeEncodingWriter']):
     """StreamHandler for warnings."""
 
     pass
 
 
-class NewLineStreamHandler(logging.StreamHandler):
+class NewLineStreamHandler(logging.StreamHandler['SafeEncodingWriter']):
     """StreamHandler which switches line terminator by record.nonl flag."""
 
     def emit(self, record: logging.LogRecord) -> None:
@@ -471,7 +468,9 @@ class OnceFilter(logging.Filter):
 
     def __init__(self, name: str = '') -> None:
         super().__init__(name)
-        self.messages: dict[str, list] = {}
+        self.messages: dict[
+            str, list[tuple[object, ...] | Mapping[str, object] | None]
+        ] = {}
 
     def filter(self, record: logging.LogRecord) -> bool:
         once = getattr(record, 'once', '')
@@ -555,9 +554,9 @@ class WarningLogRecordTranslator(SphinxLogRecordTranslator):
 def get_node_location(node: Node) -> str | None:
     source, line = get_source_line(node)
     if source and line:
-        return f'{abspath(source)}:{line}'
+        return f'{os.path.abspath(source)}:{line}'
     if source:
-        return f'{abspath(source)}:'
+        return f'{os.path.abspath(source)}:'
     if line:
         return f'<unknown>:{line}'
     return None
@@ -566,20 +565,21 @@ def get_node_location(node: Node) -> str | None:
 class ColorizeFormatter(logging.Formatter):
     def format(self, record: logging.LogRecord) -> str:
         message = super().format(record)
-        color = getattr(record, 'color', None)
-        if color is None:
-            color = COLOR_MAP.get(record.levelno)
-
-        if color:
-            return colorize(color, message)
-        else:
+        colour_name = getattr(record, 'color', '')
+        if not colour_name:
+            colour_name = COLOR_MAP.get(record.levelno, '')
+        if not colour_name:
+            return message
+        try:
+            return colourise(colour_name, message)
+        except ValueError:
             return message
 
 
 class SafeEncodingWriter:
     """Stream writer which ignores UnicodeEncodeError silently"""
 
-    def __init__(self, stream: IO) -> None:
+    def __init__(self, stream: IO[str]) -> None:
         self.stream = stream
         self.encoding = getattr(stream, 'encoding', 'ascii') or 'ascii'
 
@@ -601,14 +601,14 @@ class SafeEncodingWriter:
 class LastMessagesWriter:
     """Stream writer storing last 10 messages in memory to save trackback"""
 
-    def __init__(self, app: Sphinx, stream: IO) -> None:
+    def __init__(self, app: Sphinx, stream: IO[str]) -> None:
         self.app = app
 
     def write(self, data: str) -> None:
         self.app.messagelog.append(data)
 
 
-def setup(app: Sphinx, status: IO, warning: IO) -> None:
+def setup(app: Sphinx, status: IO[str], warning: IO[str]) -> None:
     """Setup root logger for Sphinx"""
     logger = logging.getLogger(NAMESPACE)
     logger.setLevel(logging.DEBUG)

sphinx/util/matching.py

@@ -4,9 +4,11 @@ from __future__ import annotations
 
 import os.path
 import re
+import unicodedata
+from pathlib import Path
 from typing import TYPE_CHECKING
 
-from sphinx.util.osutil import canon_path, path_stabilize
+from sphinx.util.osutil import canon_path
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
@@ -125,7 +127,7 @@ def get_matching_files(
 
     """
     # dirname is a normalized absolute path.
-    dirname = os.path.normpath(os.path.abspath(dirname))
+    dirname = Path(dirname).resolve()
 
     exclude_matchers = compile_matchers(exclude_patterns)
     include_matchers = compile_matchers(include_patterns)
@@ -134,11 +136,12 @@ def get_matching_files(
         relative_root = os.path.relpath(root, dirname)
         if relative_root == '.':
             relative_root = ''  # suppress dirname for files on the target dir
+        relative_root_path = Path(relative_root)
 
         # Filter files
         included_files = []
         for entry in sorted(files):
-            entry = path_stabilize(os.path.join(relative_root, entry))
+            entry = _unicode_nfc((relative_root_path / entry).as_posix())
             keep = False
             for matcher in include_matchers:
                 if matcher(entry):
@@ -156,7 +159,7 @@ def get_matching_files(
         # Filter directories
         filtered_dirs = []
         for dir_name in sorted(dirs):
-            normalised = path_stabilize(os.path.join(relative_root, dir_name))
+            normalised = _unicode_nfc((relative_root_path / dir_name).as_posix())
             for matcher in exclude_matchers:
                 if matcher(normalised):
                     break  # break the inner loop
@@ -168,3 +171,8 @@ def get_matching_files(
 
         # Yield filtered files
         yield from included_files
+
+
+def _unicode_nfc(s: str, /) -> str:
+    """Normalise the string to NFC form."""
+    return unicodedata.normalize('NFC', s)