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

sphinx/util/images.py

@@ -13,6 +13,7 @@ if TYPE_CHECKING:
 
 try:
     from PIL import Image
+
     PILLOW_AVAILABLE = True
 except ImportError:
     PILLOW_AVAILABLE = False
@@ -54,13 +55,13 @@ def get_image_size(filename: str) -> tuple[int, int] | None:
 
 
 @overload
-def guess_mimetype(filename: PathLike[str] | str, default: str) -> str:
-    ...
+def guess_mimetype(filename: PathLike[str] | str, default: str) -> str: ...  # NoQA: E704
 
 
 @overload
-def guess_mimetype(filename: PathLike[str] | str, default: None = None) -> str | None:
-    ...
+def guess_mimetype(  # NoQA: E704
+    filename: PathLike[str] | str, default: None = None
+) -> str | None: ...
 
 
 def guess_mimetype(
@@ -121,12 +122,12 @@ def _image_type_from_file(filename: PathLike[str] | str) -> str:
 
     # JPEG data
     # https://en.wikipedia.org/wiki/JPEG_File_Interchange_Format#File_format_structure
-    if header.startswith(b'\xFF\xD8'):
+    if header.startswith(b'\xff\xd8'):
         return 'jpeg'
 
     # Portable Network Graphics
     # https://en.wikipedia.org/wiki/PNG#File_header
-    if header.startswith(b'\x89PNG\r\n\x1A\n'):
+    if header.startswith(b'\x89PNG\r\n\x1a\n'):
         return 'png'
 
     # Scalable Vector Graphics

sphinx/util/inspect.py

@@ -52,11 +52,7 @@ if TYPE_CHECKING:
         | types.MethodDescriptorType
         | types.ClassMethodDescriptorType
     )
-    _SignatureType: TypeAlias = (
-        Callable[..., Any]
-        | staticmethod
-        | classmethod
-    )
+    _SignatureType: TypeAlias = Callable[..., Any] | staticmethod | classmethod
 
 logger = logging.getLogger(__name__)
 
@@ -266,7 +262,8 @@ def isstaticmethod(
 def isdescriptor(x: Any) -> TypeIs[_SupportsGet | _SupportsSet | _SupportsDelete]:
     """Check if the object is a :external+python:term:`descriptor`."""
     return any(
-        callable(safe_getattr(x, item, None)) for item in ('__get__', '__set__', '__delete__')
+        callable(safe_getattr(x, item, None))
+        for item in ('__get__', '__set__', '__delete__')
     )
 
 
@@ -392,6 +389,10 @@ def isgenericalias(obj: Any) -> TypeIs[types.GenericAlias]:
 
 def safe_getattr(obj: Any, name: str, *defargs: Any) -> Any:
     """A getattr() that turns all exceptions into AttributeErrors."""
+    if len(defargs) > 1:
+        msg = f'safe_getattr expected at most 3 arguments, got {len(defargs)}'
+        raise TypeError(msg)
+
     try:
         return getattr(obj, name, *defargs)
     except Exception as exc:
@@ -429,7 +430,10 @@ def object_description(obj: Any, *, _seen: frozenset[int] = frozenset()) -> str:
             sorted_keys = sorted(obj, key=lambda k: object_description(k, _seen=seen))
 
         items = (
-            (object_description(key, _seen=seen), object_description(obj[key], _seen=seen))
+            (
+                object_description(key, _seen=seen),
+                object_description(obj[key], _seen=seen),
+            )
             for key in sorted_keys
         )
         return '{%s}' % ', '.join(f'{key}: {value}' for (key, value) in items)
@@ -442,7 +446,9 @@ def object_description(obj: Any, *, _seen: frozenset[int] = frozenset()) -> str:
         except TypeError:
             # Cannot sort set values, fall back to using descriptions as a sort key
             sorted_values = sorted(obj, key=lambda x: object_description(x, _seen=seen))
-        return '{%s}' % ', '.join(object_description(x, _seen=seen) for x in sorted_values)
+        return '{%s}' % ', '.join(
+            object_description(x, _seen=seen) for x in sorted_values
+        )
     elif isinstance(obj, frozenset):
         if id(obj) in seen:
             return 'frozenset(...)'
@@ -760,7 +766,10 @@ def stringify_signature(
     args = []
     last_kind = None
     for param in sig.parameters.values():
-        if param.kind != Parameter.POSITIONAL_ONLY and last_kind == Parameter.POSITIONAL_ONLY:
+        if (
+            param.kind != Parameter.POSITIONAL_ONLY
+            and last_kind == Parameter.POSITIONAL_ONLY
+        ):
             # PEP-570: Separator for Positional Only Parameter: /
             args.append('/')
         if param.kind == Parameter.KEYWORD_ONLY and last_kind in (
@@ -797,7 +806,11 @@ def stringify_signature(
         args.append('/')
 
     concatenated_args = ', '.join(args)
-    if sig.return_annotation is EMPTY or not show_annotation or not show_return_annotation:
+    if (
+        sig.return_annotation is EMPTY
+        or not show_annotation
+        or not show_return_annotation
+    ):
         return f'({concatenated_args})'
     else:
         retann = stringify_annotation(sig.return_annotation, mode)  # type: ignore[arg-type]
@@ -842,11 +855,15 @@ def signature_from_ast(node: ast.FunctionDef, code: str = '') -> Signature:
 
     # normal arguments
     for arg, defexpr in zip(args.args, defaults[pos_only_offset:], strict=False):
-        params.append(_define(Parameter.POSITIONAL_OR_KEYWORD, arg, code, defexpr=defexpr))
+        params.append(
+            _define(Parameter.POSITIONAL_OR_KEYWORD, arg, code, defexpr=defexpr)
+        )
 
     # variadic positional argument (no possible default expression)
     if args.vararg:
-        params.append(_define(Parameter.VAR_POSITIONAL, args.vararg, code, defexpr=None))
+        params.append(
+            _define(Parameter.VAR_POSITIONAL, args.vararg, code, defexpr=None)
+        )
 
     # keyword-only arguments
     for arg, defexpr in zip(args.kwonlyargs, args.kw_defaults, strict=False):

sphinx/util/inventory.py

@@ -1,10 +1,11 @@
 """Inventory utility functions for Sphinx."""
+
 from __future__ import annotations
 
 import os
 import re
 import zlib
-from typing import IO, TYPE_CHECKING
+from typing import TYPE_CHECKING
 
 from sphinx.locale import __
 from sphinx.util import logging
@@ -17,7 +18,7 @@ if TYPE_CHECKING:
 
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
-    from sphinx.util.typing import Inventory, InventoryItem
+    from sphinx.util.typing import Inventory, InventoryItem, _ReadableStream
 
 
 class InventoryFileReader:
@@ -26,7 +27,7 @@ class InventoryFileReader:
     This reader supports mixture of texts and compressed texts.
     """
 
-    def __init__(self, stream: IO[bytes]) -> None:
+    def __init__(self, stream: _ReadableStream[bytes]) -> None:
         self.stream = stream
         self.buffer = b''
         self.eof = False
@@ -41,7 +42,7 @@ class InventoryFileReader:
         pos = self.buffer.find(b'\n')
         if pos != -1:
             line = self.buffer[:pos].decode()
-            self.buffer = self.buffer[pos + 1:]
+            self.buffer = self.buffer[pos + 1 :]
         elif self.eof:
             line = self.buffer.decode()
             self.buffer = b''
@@ -72,7 +73,7 @@ class InventoryFileReader:
             pos = buf.find(b'\n')
             while pos != -1:
                 yield buf[:pos].decode()
-                buf = buf[pos + 1:]
+                buf = buf[pos + 1 :]
                 pos = buf.find(b'\n')
 
 
@@ -80,7 +81,7 @@ class InventoryFile:
     @classmethod
     def load(
         cls: type[InventoryFile],
-        stream: IO[bytes],
+        stream: _ReadableStream[bytes],
         uri: str,
         joinfunc: Callable[[str, str], str],
     ) -> Inventory:
@@ -135,8 +136,11 @@ class InventoryFile:
 
         for line in stream.read_compressed_lines():
             # be careful to handle names with embedded spaces correctly
-            m = re.match(r'(.+?)\s+(\S+)\s+(-?\d+)\s+?(\S*)\s+(.*)',
-                         line.rstrip(), flags=re.VERBOSE)
+            m = re.match(
+                r'(.+?)\s+(\S+)\s+(-?\d+)\s+?(\S*)\s+(.*)',
+                line.rstrip(),
+                flags=re.VERBOSE,
+            )
             if not m:
                 continue
             name, type, prio, location, dispname = m.groups()
@@ -155,15 +159,20 @@ class InventoryFile:
                 # Some types require case insensitive matches:
                 # * 'term': https://github.com/sphinx-doc/sphinx/issues/9291
                 # * 'label': https://github.com/sphinx-doc/sphinx/issues/12008
-                definition = f"{type}:{name}"
+                definition = f'{type}:{name}'
                 content = prio, location, dispname
                 lowercase_definition = definition.lower()
                 if lowercase_definition in potential_ambiguities:
                     if potential_ambiguities[lowercase_definition] != content:
                         actual_ambiguities.add(definition)
                     else:
-                        logger.debug(__("inventory <%s> contains duplicate definitions of %s"),
-                                     uri, definition, type='intersphinx',  subtype='external')
+                        logger.debug(
+                            __('inventory <%s> contains duplicate definitions of %s'),
+                            uri,
+                            definition,
+                            type='intersphinx',
+                            subtype='external',
+                        )
                 else:
                     potential_ambiguities[lowercase_definition] = content
             if location.endswith('$'):
@@ -172,40 +181,49 @@ class InventoryFile:
             inv_item: InventoryItem = projname, version, location, dispname
             invdata.setdefault(type, {})[name] = inv_item
         for ambiguity in actual_ambiguities:
-            logger.info(__("inventory <%s> contains multiple definitions for %s"),
-                        uri, ambiguity, type='intersphinx',  subtype='external')
+            logger.info(
+                __('inventory <%s> contains multiple definitions for %s'),
+                uri,
+                ambiguity,
+                type='intersphinx',
+                subtype='external',
+            )
         return invdata
 
     @classmethod
     def dump(
-        cls: type[InventoryFile], filename: str, env: BuildEnvironment, builder: Builder,
+        cls: type[InventoryFile],
+        filename: str,
+        env: BuildEnvironment,
+        builder: Builder,
     ) -> None:
         def escape(string: str) -> str:
-            return re.sub("\\s+", " ", string)
+            return re.sub('\\s+', ' ', string)
 
         with open(os.path.join(filename), 'wb') as f:
             # header
-            f.write(('# Sphinx inventory version 2\n'
-                     '# Project: %s\n'
-                     '# Version: %s\n'
-                     '# The remainder of this file is compressed using zlib.\n' %
-                     (escape(env.config.project),
-                      escape(env.config.version))).encode())
+            f.write(
+                (
+                    '# Sphinx inventory version 2\n'
+                    f'# Project: {escape(env.config.project)}\n'
+                    f'# Version: {escape(env.config.version)}\n'
+                    '# The remainder of this file is compressed using zlib.\n'
+                ).encode()
+            )
 
             # body
             compressor = zlib.compressobj(9)
-            for domainname, domain in sorted(env.domains.items()):
-                for name, dispname, typ, docname, anchor, prio in \
-                        sorted(domain.get_objects()):
-                    if anchor.endswith(name):
+            for domain in env.domains.sorted():
+                sorted_objects = sorted(domain.get_objects())
+                for fullname, dispname, type, docname, anchor, prio in sorted_objects:
+                    if anchor.endswith(fullname):
                         # this can shorten the inventory by as much as 25%
-                        anchor = anchor[:-len(name)] + '$'
+                        anchor = anchor.removesuffix(fullname) + '$'
                     uri = builder.get_target_uri(docname)
                     if anchor:
                         uri += '#' + anchor
-                    if dispname == name:
+                    if dispname == fullname:
                         dispname = '-'
-                    entry = ('%s %s:%s %s %s %s\n' %
-                             (name, domainname, typ, prio, uri, dispname))
+                    entry = f'{fullname} {domain.name}:{type} {prio} {uri} {dispname}\n'
                     f.write(compressor.compress(entry.encode()))
             f.write(compressor.flush())

sphinx/util/logging.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import logging
 import logging.handlers
 from collections import defaultdict
-from contextlib import contextmanager
+from contextlib import contextmanager, nullcontext
 from typing import IO, TYPE_CHECKING, Any
 
 from docutils import nodes
@@ -17,6 +17,7 @@ from sphinx.util.osutil import abspath
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Sequence, Set
+    from typing import NoReturn
 
     from docutils.nodes import Node
 
@@ -26,27 +27,36 @@ if TYPE_CHECKING:
 NAMESPACE = 'sphinx'
 VERBOSE = 15
 
-LEVEL_NAMES: defaultdict[str, int] = defaultdict(lambda: logging.WARNING, {
-    'CRITICAL': logging.CRITICAL,
-    'SEVERE': logging.CRITICAL,
-    'ERROR': logging.ERROR,
-    'WARNING': logging.WARNING,
-    'INFO': logging.INFO,
-    'VERBOSE': VERBOSE,
-    'DEBUG': logging.DEBUG,
-})
-
-VERBOSITY_MAP: defaultdict[int, int] = defaultdict(lambda: logging.NOTSET, {
-    0: logging.INFO,
-    1: VERBOSE,
-    2: logging.DEBUG,
-})
-
-COLOR_MAP: defaultdict[int, str] = defaultdict(lambda: 'blue', {
-    logging.ERROR: 'darkred',
-    logging.WARNING: 'red',
-    logging.DEBUG: 'darkgray',
-})
+LEVEL_NAMES: defaultdict[str, int] = defaultdict(
+    lambda: logging.WARNING,
+    {
+        'CRITICAL': logging.CRITICAL,
+        'SEVERE': logging.CRITICAL,
+        'ERROR': logging.ERROR,
+        'WARNING': logging.WARNING,
+        'INFO': logging.INFO,
+        'VERBOSE': VERBOSE,
+        'DEBUG': logging.DEBUG,
+    },
+)
+
+VERBOSITY_MAP: defaultdict[int, int] = defaultdict(
+    lambda: logging.NOTSET,
+    {
+        0: logging.INFO,
+        1: VERBOSE,
+        2: logging.DEBUG,
+    },
+)
+
+COLOR_MAP: defaultdict[int, str] = defaultdict(
+    lambda: 'blue',
+    {
+        logging.ERROR: 'darkred',
+        logging.WARNING: 'red',
+        logging.DEBUG: 'darkgray',
+    },
+)
 
 
 def getLogger(name: str) -> SphinxLoggerAdapter:
@@ -125,7 +135,7 @@ class SphinxLoggerAdapter(logging.LoggerAdapter):
     KEYWORDS = ['type', 'subtype', 'location', 'nonl', 'color', 'once']
 
     def log(  # type: ignore[override]
-        self, level: int | str, msg: str, *args: Any, **kwargs: Any,
+        self, level: int | str, msg: str, *args: Any, **kwargs: Any
     ) -> None:
         if isinstance(level, int):
             super().log(level, msg, *args, **kwargs)
@@ -322,24 +332,7 @@ def pending_logging() -> Iterator[MemoryHandler]:
         memhandler.flushTo(logger)
 
 
-@contextmanager
-def skip_warningiserror(skip: bool = True) -> Iterator[None]:
-    """Context manager to skip WarningIsErrorFilter temporarily."""
-    logger = logging.getLogger(NAMESPACE)
-
-    if skip is False:
-        yield
-    else:
-        try:
-            disabler = DisableWarningIsErrorFilter()
-            for handler in logger.handlers:
-                # use internal method; filters.insert() directly to install disabler
-                # before WarningIsErrorFilter
-                handler.filters.insert(0, disabler)
-            yield
-        finally:
-            for handler in logger.handlers:
-                handler.removeFilter(disabler)
+skip_warningiserror = nullcontext  # Deprecate in Sphinx 10
 
 
 @contextmanager
@@ -407,8 +400,23 @@ class InfoFilter(logging.Filter):
         return record.levelno < logging.WARNING
 
 
+class _RaiseOnWarningFilter(logging.Filter):
+    """Raise exception if a warning is emitted."""
+
+    def filter(self, record: logging.LogRecord) -> NoReturn:
+        try:
+            message = record.msg % record.args
+        except (TypeError, ValueError):
+            message = record.msg  # use record.msg itself
+        if location := getattr(record, 'location', ''):
+            message = f'{location}:{message}'
+        if record.exc_info is not None:
+            raise SphinxWarning(message) from record.exc_info[1]
+        raise SphinxWarning(message)
+
+
 def is_suppressed_warning(
-    warning_type: str, sub_type: str, suppress_warnings: Set[str] | Sequence[str],
+    warning_type: str, sub_type: str, suppress_warnings: Set[str] | Sequence[str]
 ) -> bool:
     """Check whether the warning is suppressed or not."""
     if warning_type is None or len(suppress_warnings) == 0:
@@ -445,44 +453,6 @@ class WarningSuppressor(logging.Filter):
             return True
 
 
-class WarningIsErrorFilter(logging.Filter):
-    """Raise exception if warning emitted."""
-
-    def __init__(self, app: Sphinx) -> None:
-        self.app = app
-        super().__init__()
-
-    def filter(self, record: logging.LogRecord) -> bool:
-        if getattr(record, 'skip_warningsiserror', False):
-            # disabled by DisableWarningIsErrorFilter
-            return True
-        elif self.app.warningiserror:
-            location = getattr(record, 'location', '')
-            try:
-                message = record.msg % record.args
-            except (TypeError, ValueError):
-                message = record.msg  # use record.msg itself
-
-            if location:
-                exc = SphinxWarning(location + ":" + str(message))
-            else:
-                exc = SphinxWarning(message)
-            if record.exc_info is not None:
-                raise exc from record.exc_info[1]
-            else:
-                raise exc
-        else:
-            return True
-
-
-class DisableWarningIsErrorFilter(logging.Filter):
-    """Disable WarningIsErrorFilter if this filter installed."""
-
-    def filter(self, record: logging.LogRecord) -> bool:
-        record.skip_warningsiserror = True
-        return True
-
-
 class MessagePrefixFilter(logging.Filter):
     """Prepend prefix to all log records."""
 
@@ -585,11 +555,11 @@ 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'{abspath(source)}:{line}'
     if source:
-        return f"{abspath(source)}:"
+        return f'{abspath(source)}:'
     if line:
-        return f"<unknown>:{line}"
+        return f'<unknown>:{line}'
     return None
 
 
@@ -619,7 +589,9 @@ class SafeEncodingWriter:
         except UnicodeEncodeError:
             # stream accept only str, not bytes.  So, we encode and replace
             # non-encodable characters, then decode them.
-            self.stream.write(data.encode(self.encoding, 'replace').decode(self.encoding))
+            self.stream.write(
+                data.encode(self.encoding, 'replace').decode(self.encoding)
+            )
 
     def flush(self) -> None:
         if hasattr(self.stream, 'flush'):
@@ -653,9 +625,10 @@ def setup(app: Sphinx, status: IO, warning: IO) -> None:
     info_handler.setFormatter(ColorizeFormatter())
 
     warning_handler = WarningStreamHandler(SafeEncodingWriter(warning))
+    if app._exception_on_warning:
+        warning_handler.addFilter(_RaiseOnWarningFilter())
     warning_handler.addFilter(WarningSuppressor(app))
     warning_handler.addFilter(WarningLogRecordTranslator(app))
-    warning_handler.addFilter(WarningIsErrorFilter(app))
     warning_handler.addFilter(OnceFilter())
     warning_handler.setLevel(logging.WARNING)
     warning_handler.setFormatter(ColorizeFormatter())

sphinx/util/matching.py

@@ -112,7 +112,7 @@ def patfilter(names: Iterable[str], pat: str) -> list[str]:
 
 def get_matching_files(
     dirname: str | os.PathLike[str],
-    include_patterns: Iterable[str] = ("**",),
+    include_patterns: Iterable[str] = ('**',),
     exclude_patterns: Iterable[str] = (),
 ) -> Iterator[str]:
     """Get all file names in a directory, recursively.
@@ -132,8 +132,8 @@ def get_matching_files(
 
     for root, dirs, files in os.walk(dirname, followlinks=True):
         relative_root = os.path.relpath(root, dirname)
-        if relative_root == ".":
-            relative_root = ""  # suppress dirname for files on the target dir
+        if relative_root == '.':
+            relative_root = ''  # suppress dirname for files on the target dir
 
         # Filter files
         included_files = []

sphinx/util/math.py

@@ -14,7 +14,7 @@ def get_node_equation_number(writer: HTML5Translator, node: nodes.math_block) ->
     if writer.builder.config.math_numfig and writer.builder.config.numfig:
         figtype = 'displaymath'
         if writer.builder.name == 'singlehtml':
-            key = f"{writer.docnames[-1]}/{figtype}"  # type: ignore[has-type]
+            key = f'{writer.docnames[-1]}/{figtype}'  # type: ignore[has-type]
         else:
             key = figtype