Sphinx 7.1.1__py3-none-any.whl → 7.2.0__py3-none-any.whl

sphinx/util/i18n.py

@@ -6,7 +6,7 @@ import os
 import re
 from datetime import datetime, timezone
 from os import path
-from typing import TYPE_CHECKING, Callable, Generator, NamedTuple
+from typing import TYPE_CHECKING, Callable, NamedTuple
 
 import babel.dates
 from babel.messages.mofile import write_mo
@@ -18,6 +18,8 @@ from sphinx.util import logging
 from sphinx.util.osutil import SEP, canon_path, relpath
 
 if TYPE_CHECKING:
+    from collections.abc import Generator
+
     from sphinx.environment import BuildEnvironment
 
 
@@ -71,7 +73,7 @@ class CatalogInfo(LocaleFileInfoBase):
 class CatalogRepository:
     """A repository for message catalogs."""
 
-    def __init__(self, basedir: str, locale_dirs: list[str],
+    def __init__(self, basedir: str | os.PathLike[str], locale_dirs: list[str],
                  language: str, encoding: str) -> None:
         self.basedir = basedir
         self._locale_dirs = locale_dirs
@@ -89,7 +91,7 @@ class CatalogRepository:
             if path.exists(locale_path):
                 yield locale_dir
             else:
-                logger.verbose(__('locale_dir %s does not exists'), locale_path)
+                logger.verbose(__('locale_dir %s does not exist'), locale_path)
 
     @property
     def pofiles(self) -> Generator[tuple[str, str], None, None]:
@@ -221,24 +223,25 @@ def format_date(
     return "".join(result)
 
 
-def get_image_filename_for_language(filename: str, env: BuildEnvironment) -> str:
-    filename_format = env.config.figure_language_filename
-    d = {}
-    d['root'], d['ext'] = path.splitext(filename)
-    dirname = path.dirname(d['root'])
-    if dirname and not dirname.endswith(path.sep):
-        dirname += path.sep
+def get_image_filename_for_language(
+    filename: str | os.PathLike[str],
+    env: BuildEnvironment,
+) -> str:
+    root, ext = path.splitext(filename)
+    dirname = path.dirname(root)
     docpath = path.dirname(env.docname)
-    if docpath and not docpath.endswith(path.sep):
-        docpath += path.sep
-    d['path'] = dirname
-    d['basename'] = path.basename(d['root'])
-    d['docpath'] = docpath
-    d['language'] = env.config.language
     try:
-        return filename_format.format(**d)
+        return env.config.figure_language_filename.format(
+            root=root,
+            ext=ext,
+            path=dirname and dirname + SEP,
+            basename=path.basename(root),
+            docpath=docpath and docpath + SEP,
+            language=env.config.language,
+        )
     except KeyError as exc:
-        raise SphinxError('Invalid figure_language_filename: %r' % exc) from exc
+        msg = f'Invalid figure_language_filename: {exc!r}'
+        raise SphinxError(msg) from exc
 
 
 def search_image_for_language(filename: str, env: BuildEnvironment) -> str:

sphinx/util/images.py

@@ -142,4 +142,5 @@ def _image_type_from_file(filename: PathLike[str] | str) -> str:
     if header.startswith(b'RIFF') and header[8:12] == b'WEBP':
         return 'webp'
 
-    raise ValueError('Could not detect image type!')
+    msg = 'Could not detect image type!'
+    raise ValueError(msg)

sphinx/util/index_entries.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+
+def split_index_msg(entry_type: str, value: str) -> list[str]:
+    # new entry types must be listed in util/nodes.py!
+    if entry_type == 'single':
+        try:
+            return _split_into(2, 'single', value)
+        except ValueError:
+            return _split_into(1, 'single', value)
+    if entry_type == 'pair':
+        return _split_into(2, 'pair', value)
+    if entry_type == 'triple':
+        return _split_into(3, 'triple', value)
+    if entry_type in {'see', 'seealso'}:
+        return _split_into(2, 'see', value)
+    msg = f'invalid {entry_type} index entry {value!r}'
+    raise ValueError(msg)
+
+
+def _split_into(n: int, type: str, value: str) -> list[str]:
+    """Split an index entry into a given number of parts at semicolons."""
+    parts = [x.strip() for x in value.split(';', n - 1)]
+    if len(list(filter(None, parts))) < n:
+        msg = f'invalid {type} index entry {value!r}'
+        raise ValueError(msg)
+    return parts

sphinx/util/inspect.py

@@ -11,6 +11,7 @@ import re
 import sys
 import types
 import typing
+from collections.abc import Mapping, Sequence
 from functools import cached_property, partial, partialmethod, singledispatchmethod
 from importlib import import_module
 from inspect import (  # noqa: F401
@@ -29,7 +30,7 @@ from types import (
     ModuleType,
     WrapperDescriptorType,
 )
-from typing import Any, Callable, Dict, Mapping, Sequence, cast
+from typing import Any, Callable, cast
 
 from sphinx.pycode.ast import unparse as ast_unparse
 from sphinx.util import logging
@@ -42,12 +43,11 @@ memory_address_re = re.compile(r' at 0x[0-9a-f]{8,16}(?=>)', re.IGNORECASE)
 
 def unwrap(obj: Any) -> Any:
     """Get an original object from wrapped object (wrapped functions)."""
+    if hasattr(obj, '__sphinx_mock__'):
+        # Skip unwrapping mock object to avoid RecursionError
+        return obj
     try:
-        if hasattr(obj, '__sphinx_mock__'):
-            # Skip unwrapping mock object to avoid RecursionError
-            return obj
-        else:
-            return inspect.unwrap(obj)
+        return inspect.unwrap(obj)
     except ValueError:
         # might be a mock object
         return obj
@@ -80,11 +80,9 @@ def getall(obj: Any) -> Sequence[str] | None:
     __all__ = safe_getattr(obj, '__all__', None)
     if __all__ is None:
         return None
-    else:
-        if (isinstance(__all__, (list, tuple)) and all(isinstance(e, str) for e in __all__)):
-            return __all__
-        else:
-            raise ValueError(__all__)
+    if isinstance(__all__, (list, tuple)) and all(isinstance(e, str) for e in __all__):
+        return __all__
+    raise ValueError(__all__)
 
 
 def getannotations(obj: Any) -> Mapping[str, Any]:
@@ -129,7 +127,7 @@ def getorigbases(obj: Any) -> tuple[Any, ...] | None:
         return None
 
 
-def getslots(obj: Any) -> dict | None:
+def getslots(obj: Any) -> dict[str, Any] | None:
     """Get __slots__ attribute of the class as dict.
 
     Return None if gienv *obj* does not have __slots__.
@@ -147,7 +145,7 @@ def getslots(obj: Any) -> dict | None:
     elif isinstance(__slots__, str):
         return {__slots__: None}
     elif isinstance(__slots__, (list, tuple)):
-        return {e: None for e in __slots__}
+        return dict.fromkeys(__slots__)
     else:
         raise ValueError
 
@@ -156,10 +154,9 @@ def isNewType(obj: Any) -> bool:
     """Check the if object is a kind of NewType."""
     if sys.version_info[:2] >= (3, 10):
         return isinstance(obj, typing.NewType)
-    else:
-        __module__ = safe_getattr(obj, '__module__', None)
-        __qualname__ = safe_getattr(obj, '__qualname__', None)
-        return __module__ == 'typing' and __qualname__ == 'NewType.<locals>.new_type'
+    __module__ = safe_getattr(obj, '__module__', None)
+    __qualname__ = safe_getattr(obj, '__qualname__', None)
+    return __module__ == 'typing' and __qualname__ == 'NewType.<locals>.new_type'
 
 
 def isenumclass(x: Any) -> bool:
@@ -208,7 +205,7 @@ def isstaticmethod(obj: Any, cls: Any = None, name: str | None = None) -> bool:
     """Check if the object is staticmethod."""
     if isinstance(obj, staticmethod):
         return True
-    elif cls and name:
+    if cls and name:
         # trace __mro__ if the method is defined in parent class
         #
         # .. note:: This only works well with new style classes.
@@ -216,7 +213,6 @@ def isstaticmethod(obj: Any, cls: Any = None, name: str | None = None) -> bool:
             meth = basecls.__dict__.get(name)
             if meth:
                 return isinstance(meth, staticmethod)
-
     return False
 
 
@@ -290,17 +286,17 @@ def is_singledispatch_method(obj: Any) -> bool:
 
 def isfunction(obj: Any) -> bool:
     """Check if the object is function."""
-    return inspect.isfunction(unwrap_all(obj))
+    return inspect.isfunction(unpartial(obj))
 
 
 def isbuiltin(obj: Any) -> bool:
-    """Check if the object is builtin."""
-    return inspect.isbuiltin(unwrap_all(obj))
+    """Check if the object is function."""
+    return inspect.isbuiltin(unpartial(obj))
 
 
 def isroutine(obj: Any) -> bool:
     """Check is any kind of function or method."""
-    return inspect.isroutine(unwrap_all(obj))
+    return inspect.isroutine(unpartial(obj))
 
 
 def iscoroutinefunction(obj: Any) -> bool:
@@ -324,15 +320,8 @@ def isproperty(obj: Any) -> bool:
 
 def isgenericalias(obj: Any) -> bool:
     """Check if the object is GenericAlias."""
-    if isinstance(obj, typing._GenericAlias):  # type: ignore
-        return True
-    if (hasattr(types, 'GenericAlias')  # only for py39+
-            and isinstance(obj, types.GenericAlias)):
-        return True
-    if (hasattr(typing, '_SpecialGenericAlias')  # for py39+
-            and isinstance(obj, typing._SpecialGenericAlias)):
-        return True
-    return False
+    return isinstance(
+        obj, (types.GenericAlias, typing._BaseGenericAlias))  # type: ignore[attr-defined]
 
 
 def safe_getattr(obj: Any, name: str, *defargs: Any) -> Any:
@@ -357,38 +346,64 @@ def safe_getattr(obj: Any, name: str, *defargs: Any) -> Any:
         raise AttributeError(name) from exc
 
 
-def object_description(object: Any) -> str:
-    """A repr() implementation that returns text safe to use in reST context."""
-    if isinstance(object, dict):
+def object_description(obj: Any, *, _seen: frozenset = frozenset()) -> str:
+    """A repr() implementation that returns text safe to use in reST context.
+
+    Maintains a set of 'seen' object IDs to detect and avoid infinite recursion.
+    """
+    seen = _seen
+    if isinstance(obj, dict):
+        if id(obj) in seen:
+            return 'dict(...)'
+        seen |= {id(obj)}
         try:
-            sorted_keys = sorted(object)
-        except Exception:
-            pass  # Cannot sort dict keys, fall back to generic repr
-        else:
-            items = ("%s: %s" %
-                     (object_description(key), object_description(object[key]))
-                     for key in sorted_keys)
-            return "{%s}" % ", ".join(items)
-    elif isinstance(object, set):
+            sorted_keys = sorted(obj)
+        except TypeError:
+            # Cannot sort dict keys, fall back to using descriptions as a sort key
+            sorted_keys = sorted(obj, key=lambda k: object_description(k, _seen=seen))
+
+        items = ((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)
+    elif isinstance(obj, set):
+        if id(obj) in seen:
+            return 'set(...)'
+        seen |= {id(obj)}
         try:
-            sorted_values = sorted(object)
+            sorted_values = sorted(obj)
         except TypeError:
-            pass  # Cannot sort set values, fall back to generic repr
-        else:
-            return "{%s}" % ", ".join(object_description(x) for x in sorted_values)
-    elif isinstance(object, frozenset):
+            # 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)
+    elif isinstance(obj, frozenset):
+        if id(obj) in seen:
+            return 'frozenset(...)'
+        seen |= {id(obj)}
         try:
-            sorted_values = sorted(object)
+            sorted_values = sorted(obj)
         except TypeError:
-            pass  # Cannot sort frozenset values, fall back to generic repr
-        else:
-            return "frozenset({%s})" % ", ".join(object_description(x)
-                                                 for x in sorted_values)
-    elif isinstance(object, enum.Enum):
-        return f"{object.__class__.__name__}.{object.name}"
+            # Cannot sort frozenset values, fall back to using descriptions as a sort key
+            sorted_values = sorted(obj, key=lambda x: object_description(x, _seen=seen))
+        return 'frozenset({%s})' % ', '.join(object_description(x, _seen=seen)
+                                             for x in sorted_values)
+    elif isinstance(obj, enum.Enum):
+        return f'{obj.__class__.__name__}.{obj.name}'
+    elif isinstance(obj, tuple):
+        if id(obj) in seen:
+            return 'tuple(...)'
+        seen |= frozenset([id(obj)])
+        return '(%s%s)' % (
+            ', '.join(object_description(x, _seen=seen) for x in obj),
+            ',' * (len(obj) == 1),
+        )
+    elif isinstance(obj, list):
+        if id(obj) in seen:
+            return 'list(...)'
+        seen |= {id(obj)}
+        return '[%s]' % ', '.join(object_description(x, _seen=seen) for x in obj)
 
     try:
-        s = repr(object)
+        s = repr(obj)
     except Exception as exc:
         raise ValueError from exc
     # Strip non-deterministic memory addresses such as
@@ -488,7 +503,7 @@ class TypeAliasModule:
                     return getattr(self.__module, name)
 
 
-class TypeAliasNamespace(Dict[str, Any]):
+class TypeAliasNamespace(dict[str, Any]):
     """Pseudo namespace class for autodoc_type_aliases.
 
     This enables to look up nested modules and classes like `mod1.mod2.Class`.
@@ -522,12 +537,14 @@ def _should_unwrap(subject: Callable) -> bool:
     return False
 
 
-def signature(subject: Callable, bound_method: bool = False, type_aliases: dict = {},
+def signature(subject: Callable, bound_method: bool = False, type_aliases: dict | None = None,
               ) -> inspect.Signature:
     """Return a Signature object for the given *subject*.
 
     :param bound_method: Specify *subject* is a bound method or not
     """
+    if type_aliases is None:
+        type_aliases = {}
 
     try:
         if _should_unwrap(subject):
@@ -584,10 +601,7 @@ def evaluate_signature(sig: inspect.Signature, globalns: dict | None = None,
     """Evaluate unresolved type annotations in a signature object."""
     def evaluate_forwardref(ref: ForwardRef, globalns: dict, localns: dict) -> Any:
         """Evaluate a forward reference."""
-        if sys.version_info[:2] >= (3, 9):
-            return ref._evaluate(globalns, localns, frozenset())
-        else:
-            return ref._evaluate(globalns, localns)
+        return ref._evaluate(globalns, localns, frozenset())
 
     def evaluate(annotation: Any, globalns: dict, localns: dict) -> Any:
         """Evaluate unresolved type annotation."""
@@ -710,14 +724,15 @@ def signature_from_ast(node: ast.FunctionDef, code: str = '') -> inspect.Signatu
         positionals = len(args.args)
 
     for _ in range(len(defaults), positionals):
-        defaults.insert(0, Parameter.empty)  # type: ignore
+        defaults.insert(0, Parameter.empty)  # type: ignore[arg-type]
 
     if hasattr(args, "posonlyargs"):
         for i, arg in enumerate(args.posonlyargs):
             if defaults[i] is Parameter.empty:
                 default = Parameter.empty
             else:
-                default = DefaultValue(ast_unparse(defaults[i], code))  # type: ignore
+                default = DefaultValue(
+                    ast_unparse(defaults[i], code))  # type: ignore[assignment]
 
             annotation = ast_unparse(arg.annotation, code) or Parameter.empty
             params.append(Parameter(arg.arg, Parameter.POSITIONAL_ONLY,
@@ -728,7 +743,7 @@ def signature_from_ast(node: ast.FunctionDef, code: str = '') -> inspect.Signatu
             default = Parameter.empty
         else:
             default = DefaultValue(
-                ast_unparse(defaults[i + posonlyargs], code),  # type: ignore
+                ast_unparse(defaults[i + posonlyargs], code),  # type: ignore[assignment]
             )
 
         annotation = ast_unparse(arg.annotation, code) or Parameter.empty
@@ -744,7 +759,8 @@ def signature_from_ast(node: ast.FunctionDef, code: str = '') -> inspect.Signatu
         if args.kw_defaults[i] is None:
             default = Parameter.empty
         else:
-            default = DefaultValue(ast_unparse(args.kw_defaults[i], code))  # type: ignore
+            default = DefaultValue(
+                ast_unparse(args.kw_defaults[i], code))  # type: ignore[arg-type,assignment]
         annotation = ast_unparse(arg.annotation, code) or Parameter.empty
         params.append(Parameter(arg.arg, Parameter.KEYWORD_ONLY, default=default,
                                 annotation=annotation))

sphinx/util/inventory.py

@@ -4,17 +4,19 @@ from __future__ import annotations
 import os
 import re
 import zlib
-from typing import IO, TYPE_CHECKING, Callable, Iterator
+from typing import IO, TYPE_CHECKING, Callable
 
 from sphinx.util import logging
-from sphinx.util.typing import Inventory, InventoryItem
 
 BUFSIZE = 16 * 1024
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
+    from sphinx.util.typing import Inventory, InventoryItem
 
 
 class InventoryFileReader:

sphinx/util/logging.py

@@ -6,10 +6,9 @@ import logging
 import logging.handlers
 from collections import defaultdict
 from contextlib import contextmanager
-from typing import IO, TYPE_CHECKING, Any, Generator
+from typing import IO, TYPE_CHECKING, Any
 
 from docutils import nodes
-from docutils.nodes import Node
 from docutils.utils import get_source_line
 
 from sphinx.errors import SphinxWarning
@@ -17,6 +16,10 @@ from sphinx.util.console import colorize
 from sphinx.util.osutil import abspath
 
 if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from docutils.nodes import Node
+
     from sphinx.application import Sphinx
 
 
@@ -104,7 +107,7 @@ class SphinxInfoLogRecord(SphinxLogRecord):
 class SphinxWarningLogRecord(SphinxLogRecord):
     """Warning log record class supporting location"""
     @property
-    def prefix(self) -> str:  # type: ignore
+    def prefix(self) -> str:  # type: ignore[override]
         if self.levelno >= logging.CRITICAL:
             return 'CRITICAL: '
         elif self.levelno >= logging.ERROR:
@@ -129,7 +132,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
+    def process(self, msg: str, kwargs: dict) -> tuple[str, dict]:  # type: ignore[override]
         extra = kwargs.setdefault('extra', {})
         for keyword in self.KEYWORDS:
             if keyword in kwargs:
@@ -479,10 +482,10 @@ class SphinxLogRecordTranslator(logging.Filter):
         self.app = app
         super().__init__()
 
-    def filter(self, record: SphinxWarningLogRecord) -> bool:  # type: ignore
+    def filter(self, record: SphinxWarningLogRecord) -> bool:  # type: ignore[override]
         if isinstance(record, logging.LogRecord):
             # force subclassing to handle location
-            record.__class__ = self.LogRecordClass  # type: ignore
+            record.__class__ = self.LogRecordClass  # type: ignore[assignment]
 
         location = getattr(record, 'location', None)
         if isinstance(location, tuple):

sphinx/util/matching.py

@@ -4,10 +4,13 @@ from __future__ import annotations
 
 import os.path
 import re
-from typing import Callable, Iterable, Iterator
+from typing import TYPE_CHECKING, Callable
 
 from sphinx.util.osutil import canon_path, path_stabilize
 
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
 
 def _translate_pattern(pat: str) -> str:
     """Translate a shell-style glob pattern to a regular expression.
@@ -107,7 +110,7 @@ def patfilter(names: Iterable[str], pat: str) -> list[str]:
 
 
 def get_matching_files(
-    dirname: str,
+    dirname: str | os.PathLike[str],
     include_patterns: Iterable[str] = ("**",),
     exclude_patterns: Iterable[str] = (),
 ) -> Iterator[str]:

sphinx/util/math.py

@@ -2,16 +2,19 @@
 
 from __future__ import annotations
 
-from docutils import nodes
+from typing import TYPE_CHECKING
 
-from sphinx.builders.html import HTML5Translator
+if TYPE_CHECKING:
+    from docutils import nodes
+
+    from sphinx.builders.html import HTML5Translator
 
 
 def get_node_equation_number(writer: HTML5Translator, node: nodes.math_block) -> str:
     if writer.builder.config.math_numfig and writer.builder.config.numfig:
         figtype = 'displaymath'
         if writer.builder.name == 'singlehtml':
-            key = f"{writer.docnames[-1]}/{figtype}"
+            key = f"{writer.docnames[-1]}/{figtype}"  # type: ignore[has-type]
         else:
             key = figtype