Sphinx 7.3.6__py3-none-any.whl → 7.4.0__py3-none-any.whl

sphinx/util/console.py

@@ -93,7 +93,7 @@ def color_terminal() -> bool:
     if 'NO_COLOR' in os.environ:
         return False
     if sys.platform == 'win32' and colorama is not None:
-        colorama.init()
+        colorama.just_fix_windows_console()
         return True
     if 'FORCE_COLOR' in os.environ:
         return True

sphinx/util/display.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import functools
-from typing import Any, Callable, TypeVar
 
 from sphinx.locale import __
 from sphinx.util import logging
@@ -10,6 +9,13 @@ from sphinx.util.console import bold, color_terminal
 if False:
     from collections.abc import Iterable, Iterator
     from types import TracebackType
+    from typing import Any, Callable, TypeVar
+
+    from typing_extensions import ParamSpec
+
+    T = TypeVar('T')
+    P = ParamSpec('P')
+    R = TypeVar('R')
 
 logger = logging.getLogger(__name__)
 
@@ -22,9 +28,6 @@ def display_chunk(chunk: Any) -> str:
     return str(chunk)
 
 
-T = TypeVar('T')
-
-
 def status_iterator(
     iterable: Iterable[T],
     summary: str,
@@ -62,11 +65,12 @@ class SkipProgressMessage(Exception):
 
 
 class progress_message:
-    def __init__(self, message: str) -> None:
+    def __init__(self, message: str, *, nonl: bool = True) -> None:
         self.message = message
+        self.nonl = nonl
 
     def __enter__(self) -> None:
-        logger.info(bold(self.message + '... '), nonl=True)
+        logger.info(bold(self.message + '... '), nonl=self.nonl)
 
     def __exit__(
         self,
@@ -74,21 +78,22 @@ class progress_message:
         val: BaseException | None,
         tb: TracebackType | None,
     ) -> bool:
+        prefix = "" if self.nonl else bold(self.message + ': ')
         if isinstance(val, SkipProgressMessage):
-            logger.info(__('skipped'))
+            logger.info(prefix + __('skipped'))
             if val.args:
                 logger.info(*val.args)
             return True
         elif val:
-            logger.info(__('failed'))
+            logger.info(prefix + __('failed'))
         else:
-            logger.info(__('done'))
+            logger.info(prefix + __('done'))
 
         return False
 
-    def __call__(self, f: Callable) -> Callable:
+    def __call__(self, f: Callable[P, R]) -> Callable[P, R]:
         @functools.wraps(f)
-        def wrapper(*args: Any, **kwargs: Any) -> Any:
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:  # type: ignore[return]
             with self:
                 return f(*args, **kwargs)
 

sphinx/util/docutils.py

@@ -17,11 +17,11 @@ from docutils.parsers.rst import Directive, directives, roles
 from docutils.parsers.rst.states import Inliner  # NoQA: TCH002
 from docutils.statemachine import State, StateMachine, StringList
 from docutils.utils import Reporter, unescape
-from docutils.writers._html_base import HTMLTranslator
 
 from sphinx.errors import SphinxError
 from sphinx.locale import _, __
 from sphinx.util import logging
+from sphinx.util.parsing import nested_parse_to_nodes
 
 logger = logging.getLogger(__name__)
 report_re = re.compile('^(.+?:(?:\\d+)?): \\((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\\d+)?\\) ')
@@ -180,46 +180,12 @@ def using_user_docutils_conf(confdir: str | None) -> Iterator[None]:
             os.environ['DOCUTILSCONFIG'] = docutilsconfig
 
 
-@contextmanager
-def du19_footnotes() -> Iterator[None]:
-    def visit_footnote(self: HTMLTranslator, node: Element) -> None:
-        label_style = self.settings.footnote_references
-        if not isinstance(node.previous_sibling(), type(node)):
-            self.body.append(f'<aside class="footnote-list {label_style}">\n')
-        self.body.append(self.starttag(node, 'aside',
-                                       classes=[node.tagname, label_style],
-                                       role="note"))
-
-    def depart_footnote(self: HTMLTranslator, node: Element) -> None:
-        self.body.append('</aside>\n')
-        if not isinstance(node.next_node(descend=False, siblings=True),
-                          type(node)):
-            self.body.append('</aside>\n')
-
-    old_visit_footnote = HTMLTranslator.visit_footnote
-    old_depart_footnote = HTMLTranslator.depart_footnote
-
-    # Only apply on Docutils 0.18 or 0.18.1, as 0.17 and earlier used a <dl> based
-    # approach, and 0.19 and later use the fixed approach by default.
-    if docutils.__version_info__[:2] == (0, 18):
-        HTMLTranslator.visit_footnote = visit_footnote  # type: ignore[method-assign]
-        HTMLTranslator.depart_footnote = depart_footnote  # type: ignore[method-assign]
-
-    try:
-        yield
-    finally:
-        if docutils.__version_info__[:2] == (0, 18):
-            HTMLTranslator.visit_footnote = old_visit_footnote  # type: ignore[method-assign]
-            HTMLTranslator.depart_footnote = old_depart_footnote  # type: ignore[method-assign]
-
-
 @contextmanager
 def patch_docutils(confdir: str | None = None) -> Iterator[None]:
     """Patch to docutils temporarily."""
     with patched_get_language(), \
          patched_rst_get_language(), \
-         using_user_docutils_conf(confdir), \
-         du19_footnotes():
+         using_user_docutils_conf(confdir):
         yield
 
 
@@ -329,11 +295,11 @@ class WarningStream:
     def write(self, text: str) -> None:
         matched = report_re.search(text)
         if not matched:
-            logger.warning(text.rstrip("\r\n"))
+            logger.warning(text.rstrip("\r\n"), type="docutils")
         else:
             location, type, level = matched.groups()
             message = report_re.sub('', text).rstrip()
-            logger.log(type, message, location=location)
+            logger.log(type, message, location=location, type="docutils")
 
 
 class LoggingReporter(Reporter):
@@ -424,7 +390,82 @@ class SphinxDirective(Directive):
 
     def get_location(self) -> str:
         """Get current location info for logging."""
-        return ':'.join(str(s) for s in self.get_source_info())
+        source, line = self.get_source_info()
+        if source and line:
+            return f'{source}:{line}'
+        if source:
+            return f'{source}:'
+        if line:
+            return f'<unknown>:{line}'
+        return ''
+
+    def parse_content_to_nodes(self, allow_section_headings: bool = False) -> list[Node]:
+        """Parse the directive's content into nodes.
+
+        :param allow_section_headings:
+            Are titles (sections) allowed in the directive's content?
+            Note that this option bypasses Docutils' usual checks on
+            doctree structure, and misuse of this option can lead to
+            an incoherent doctree. In Docutils, section nodes should
+            only be children of ``Structural`` nodes, which includes
+            ``document``, ``section``, and ``sidebar`` nodes.
+
+        .. versionadded:: 7.4
+        """
+        return nested_parse_to_nodes(
+            self.state,
+            self.content,
+            offset=self.content_offset,
+            allow_section_headings=allow_section_headings,
+        )
+
+    def parse_text_to_nodes(
+        self, text: str = '', /, *, offset: int = -1, allow_section_headings: bool = False,
+    ) -> list[Node]:
+        """Parse *text* into nodes.
+
+        :param text:
+            Text, in string form. ``StringList`` is also accepted.
+        :param allow_section_headings:
+            Are titles (sections) allowed in *text*?
+            Note that this option bypasses Docutils' usual checks on
+            doctree structure, and misuse of this option can lead to
+            an incoherent doctree. In Docutils, section nodes should
+            only be children of ``Structural`` nodes, which includes
+            ``document``, ``section``, and ``sidebar`` nodes.
+        :param offset:
+            The offset of the content.
+
+        .. versionadded:: 7.4
+        """
+        if offset == -1:
+            offset = self.content_offset
+        return nested_parse_to_nodes(
+            self.state,
+            text,
+            offset=offset,
+            allow_section_headings=allow_section_headings,
+        )
+
+    def parse_inline(
+        self, text: str, *, lineno: int = -1,
+    ) -> tuple[list[Node], list[system_message]]:
+        """Parse *text* as inline elements.
+
+        :param text:
+            The text to parse, which should be a single line or paragraph.
+            This cannot contain any structural elements (headings,
+            transitions, directives, etc).
+        :param lineno:
+            The line number where the interpreted text begins.
+        :returns:
+            A list of nodes (text and inline elements) and a list of system_messages.
+
+        .. versionadded:: 7.4
+        """
+        if lineno == -1:
+            lineno = self.lineno
+        return self.state.inline_text(text, lineno)
 
 
 class SphinxRole:
@@ -494,7 +535,14 @@ class SphinxRole:
 
     def get_location(self) -> str:
         """Get current location info for logging."""
-        return ':'.join(str(s) for s in self.get_source_info())
+        source, line = self.get_source_info()
+        if source and line:
+            return f'{source}:{line}'
+        if source:
+            return f'{source}:'
+        if line:
+            return f'<unknown>:{line}'
+        return ''
 
 
 class ReferenceRole(SphinxRole):

sphinx/util/fileutil.py

@@ -15,6 +15,19 @@ if TYPE_CHECKING:
     from sphinx.util.typing import PathMatcher
 
 
+def _template_basename(filename: str | os.PathLike[str]) -> str | None:
+    """Given an input filename:
+    If the input looks like a template, then return the filename output should
+    be written to.  Otherwise, return no result (None).
+    """
+    basename = os.path.basename(filename)
+    if basename.lower().endswith('_t'):
+        return str(filename)[:-2]
+    elif basename.lower().endswith('.jinja'):
+        return str(filename)[:-6]
+    return None
+
+
 def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLike[str],
                     context: dict[str, Any] | None = None,
                     renderer: BaseRenderer | None = None) -> None:
@@ -37,14 +50,13 @@ def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLi
     else:
         destination = str(destination)
 
-    if os.path.basename(source).endswith(('_t', '_T')) and context is not None:
+    if _template_basename(source) and context is not None:
         if renderer is None:
             from sphinx.util.template import SphinxRenderer
             renderer = SphinxRenderer()
 
         with open(source, encoding='utf-8') as fsrc:
-            if destination.endswith(('_t', '_T')):
-                destination = destination[:-2]
+            destination = _template_basename(destination) or destination
             with open(destination, 'w', encoding='utf-8') as fdst:
                 fdst.write(renderer.render_string(fsrc.read(), context))
     else:

sphinx/util/images.py

@@ -24,6 +24,7 @@ mime_suffixes = {
     '.svg': 'image/svg+xml',
     '.svgz': 'image/svg+xml',
     '.ai': 'application/illustrator',
+    '.webp': 'image/webp',
 }
 _suffix_from_mime = {v: k for k, v in reversed(mime_suffixes.items())}
 

sphinx/util/inspect.py

@@ -27,7 +27,36 @@ if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
     from inspect import _ParameterKind
     from types import MethodType, ModuleType
-    from typing import Final
+    from typing import Final, Protocol, Union
+
+    from typing_extensions import TypeAlias, TypeIs
+
+    class _SupportsGet(Protocol):
+        def __get__(self, __instance: Any, __owner: type | None = ...) -> Any: ...  # NoQA: E704
+
+    class _SupportsSet(Protocol):
+        # instance and value are contravariants but we do not need that precision
+        def __set__(self, __instance: Any, __value: Any) -> None: ...  # NoQA: E704
+
+    class _SupportsDelete(Protocol):
+        # instance is contravariant but we do not need that precision
+        def __delete__(self, __instance: Any) -> None: ...  # NoQA: E704
+
+    _RoutineType: TypeAlias = Union[
+        types.FunctionType,
+        types.LambdaType,
+        types.MethodType,
+        types.BuiltinFunctionType,
+        types.BuiltinMethodType,
+        types.WrapperDescriptorType,
+        types.MethodDescriptorType,
+        types.ClassMethodDescriptorType,
+    ]
+    _SignatureType: TypeAlias = Union[
+        Callable[..., Any],
+        staticmethod,
+        classmethod,
+    ]
 
 logger = logging.getLogger(__name__)
 
@@ -90,7 +119,7 @@ def unwrap_all(obj: Any, *, stop: Callable[[Any], bool] | None = None) -> Any:
 
 
 def getall(obj: Any) -> Sequence[str] | None:
-    """Get the ``__all__`` attribute of an object as sequence.
+    """Get the ``__all__`` attribute of an object as a sequence.
 
     This returns ``None`` if the given ``obj.__all__`` does not exist and
     raises :exc:`ValueError` if ``obj.__all__`` is not a list or tuple of
@@ -184,12 +213,12 @@ def isNewType(obj: Any) -> bool:
     return __module__ == 'typing' and __qualname__ == 'NewType.<locals>.new_type'
 
 
-def isenumclass(x: Any) -> bool:
+def isenumclass(x: Any) -> TypeIs[type[enum.Enum]]:
     """Check if the object is an :class:`enumeration class <enum.Enum>`."""
     return isclass(x) and issubclass(x, enum.Enum)
 
 
-def isenumattribute(x: Any) -> bool:
+def isenumattribute(x: Any) -> TypeIs[enum.Enum]:
     """Check if the object is an enumeration attribute."""
     return isinstance(x, enum.Enum)
 
@@ -206,12 +235,16 @@ def unpartial(obj: Any) -> Any:
     return obj
 
 
-def ispartial(obj: Any) -> bool:
+def ispartial(obj: Any) -> TypeIs[partial | partialmethod]:
     """Check if the object is a partial function or method."""
     return isinstance(obj, (partial, partialmethod))
 
 
-def isclassmethod(obj: Any, cls: Any = None, name: str | None = None) -> bool:
+def isclassmethod(
+    obj: Any,
+    cls: Any = None,
+    name: str | None = None,
+) -> TypeIs[classmethod]:
     """Check if the object is a :class:`classmethod`."""
     if isinstance(obj, classmethod):
         return True
@@ -227,7 +260,11 @@ def isclassmethod(obj: Any, cls: Any = None, name: str | None = None) -> bool:
     return False
 
 
-def isstaticmethod(obj: Any, cls: Any = None, name: str | None = None) -> bool:
+def isstaticmethod(
+    obj: Any,
+    cls: Any = None,
+    name: str | None = None,
+) -> TypeIs[staticmethod]:
     """Check if the object is a :class:`staticmethod`."""
     if isinstance(obj, staticmethod):
         return True
@@ -241,7 +278,7 @@ def isstaticmethod(obj: Any, cls: Any = None, name: str | None = None) -> bool:
     return False
 
 
-def isdescriptor(x: Any) -> bool:
+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__')
@@ -308,12 +345,12 @@ def is_singledispatch_function(obj: Any) -> bool:
     )
 
 
-def is_singledispatch_method(obj: Any) -> bool:
+def is_singledispatch_method(obj: Any) -> TypeIs[singledispatchmethod]:
     """Check if the object is a :class:`~functools.singledispatchmethod`."""
     return isinstance(obj, singledispatchmethod)
 
 
-def isfunction(obj: Any) -> bool:
+def isfunction(obj: Any) -> TypeIs[types.FunctionType]:
     """Check if the object is a user-defined function.
 
     Partial objects are unwrapped before checking them.
@@ -323,7 +360,7 @@ def isfunction(obj: Any) -> bool:
     return inspect.isfunction(unpartial(obj))
 
 
-def isbuiltin(obj: Any) -> bool:
+def isbuiltin(obj: Any) -> TypeIs[types.BuiltinFunctionType]:
     """Check if the object is a built-in function or method.
 
     Partial objects are unwrapped before checking them.
@@ -333,7 +370,7 @@ def isbuiltin(obj: Any) -> bool:
     return inspect.isbuiltin(unpartial(obj))
 
 
-def isroutine(obj: Any) -> bool:
+def isroutine(obj: Any) -> TypeIs[_RoutineType]:
     """Check if the object is a kind of function or method.
 
     Partial objects are unwrapped before checking them.
@@ -343,7 +380,7 @@ def isroutine(obj: Any) -> bool:
     return inspect.isroutine(unpartial(obj))
 
 
-def iscoroutinefunction(obj: Any) -> bool:
+def iscoroutinefunction(obj: Any) -> TypeIs[Callable[..., types.CoroutineType]]:
     """Check if the object is a :external+python:term:`coroutine` function."""
     obj = unwrap_all(obj, stop=_is_wrapped_coroutine)
     return inspect.iscoroutinefunction(obj)
@@ -358,12 +395,12 @@ def _is_wrapped_coroutine(obj: Any) -> bool:
     return hasattr(obj, '__wrapped__')
 
 
-def isproperty(obj: Any) -> bool:
+def isproperty(obj: Any) -> TypeIs[property | cached_property]:
     """Check if the object is property (possibly cached)."""
     return isinstance(obj, (property, cached_property))
 
 
-def isgenericalias(obj: Any) -> bool:
+def isgenericalias(obj: Any) -> TypeIs[types.GenericAlias]:
     """Check if the object is a generic alias."""
     return isinstance(obj, (types.GenericAlias, typing._BaseGenericAlias))  # type: ignore[attr-defined]
 
@@ -579,7 +616,7 @@ class TypeAliasNamespace(dict[str, Any]):
                 raise KeyError
 
 
-def _should_unwrap(subject: Callable[..., Any]) -> bool:
+def _should_unwrap(subject: _SignatureType) -> bool:
     """Check the function should be unwrapped on getting signature."""
     __globals__ = getglobals(subject)
     # contextmanger should be unwrapped
@@ -590,7 +627,7 @@ def _should_unwrap(subject: Callable[..., Any]) -> bool:
 
 
 def signature(
-    subject: Callable[..., Any],
+    subject: _SignatureType,
     bound_method: bool = False,
     type_aliases: Mapping[str, str] | None = None,
 ) -> Signature:
@@ -603,12 +640,12 @@ def signature(
 
     try:
         if _should_unwrap(subject):
-            signature = inspect.signature(subject)
+            signature = inspect.signature(subject)  # type: ignore[arg-type]
         else:
-            signature = inspect.signature(subject, follow_wrapped=True)
+            signature = inspect.signature(subject, follow_wrapped=True)  # type: ignore[arg-type]
     except ValueError:
         # follow built-in wrappers up (ex. functools.lru_cache)
-        signature = inspect.signature(subject)
+        signature = inspect.signature(subject)  # type: ignore[arg-type]
     parameters = list(signature.parameters.values())
     return_annotation = signature.return_annotation
 
@@ -681,6 +718,13 @@ def _evaluate_forwardref(
     localns: dict[str, Any] | None,
 ) -> Any:
     """Evaluate a forward reference."""
+    if sys.version_info >= (3, 12, 4):
+        # ``type_params`` were added in 3.13 and the signature of _evaluate()
+        # is not backward-compatible (it was backported to 3.12.4, so anything
+        # before 3.12.4 still has the old signature).
+        #
+        # See: https://github.com/python/cpython/pull/118104.
+        return ref._evaluate(globalns, localns, {}, recursive_guard=frozenset())  # type: ignore[arg-type, misc]
     return ref._evaluate(globalns, localns, frozenset())
 
 
@@ -752,7 +796,7 @@ def stringify_signature(
 
         if show_annotation and param.annotation is not EMPTY:
             arg.write(': ')
-            arg.write(stringify_annotation(param.annotation, mode))
+            arg.write(stringify_annotation(param.annotation, mode))  # type: ignore[arg-type]
         if param.default is not EMPTY:
             if show_annotation and param.annotation is not EMPTY:
                 arg.write(' = ')
@@ -771,7 +815,7 @@ def stringify_signature(
     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)
+        retann = stringify_annotation(sig.return_annotation, mode)  # type: ignore[arg-type]
         return f'({concatenated_args}) -> {retann}'
 
 

sphinx/util/inventory.py

@@ -6,6 +6,7 @@ import re
 import zlib
 from typing import IO, TYPE_CHECKING, Callable
 
+from sphinx.locale import __
 from sphinx.util import logging
 
 BUFSIZE = 16 * 1024
@@ -125,6 +126,8 @@ class InventoryFile:
         invdata: Inventory = {}
         projname = stream.readline().rstrip()[11:]
         version = stream.readline().rstrip()[11:]
+        potential_ambiguities = set()
+        actual_ambiguities = set()
         line = stream.readline()
         if 'zlib' not in line:
             raise ValueError('invalid inventory header (not compressed): %s' % line)
@@ -147,11 +150,23 @@ class InventoryFile:
                 # for Python modules, and the first
                 # one is correct
                 continue
+            if type in {'std:label', 'std:term'}:
+                # 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}"
+                if definition.lower() in potential_ambiguities:
+                    actual_ambiguities.add(definition)
+                else:
+                    potential_ambiguities.add(definition.lower())
             if location.endswith('$'):
                 location = location[:-1] + name
             location = join(uri, location)
             inv_item: InventoryItem = projname, version, location, dispname
             invdata.setdefault(type, {})[name] = inv_item
+        for ambiguity in actual_ambiguities:
+            logger.warning(__("inventory <%s> contains multiple definitions for %s"),
+                           uri, ambiguity, type='intersphinx',  subtype='external')
         return invdata
 
     @classmethod

sphinx/util/logging.py

@@ -16,7 +16,7 @@ from sphinx.util.console import colorize
 from sphinx.util.osutil import abspath
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Sequence, Set
 
     from docutils.nodes import Node
 
@@ -407,23 +407,18 @@ class InfoFilter(logging.Filter):
         return record.levelno < logging.WARNING
 
 
-def is_suppressed_warning(type: str, subtype: str, suppress_warnings: list[str]) -> bool:
+def is_suppressed_warning(
+    warning_type: str, sub_type: str, suppress_warnings: Set[str] | Sequence[str],
+) -> bool:
     """Check whether the warning is suppressed or not."""
-    if type is None:
+    if warning_type is None or len(suppress_warnings) == 0:
         return False
-
-    subtarget: str | None
-
-    for warning_type in suppress_warnings:
-        if '.' in warning_type:
-            target, subtarget = warning_type.split('.', 1)
-        else:
-            target, subtarget = warning_type, None
-
-        if target == type and subtarget in (None, subtype, "*"):
-            return True
-
-    return False
+    suppressed_warnings = frozenset(suppress_warnings)
+    if warning_type in suppressed_warnings:
+        return True
+    if f'{warning_type}.*' in suppressed_warnings:
+        return True
+    return f'{warning_type}.{sub_type}' in suppressed_warnings
 
 
 class WarningSuppressor(logging.Filter):
@@ -441,7 +436,7 @@ class WarningSuppressor(logging.Filter):
             suppress_warnings = self.app.config.suppress_warnings
         except AttributeError:
             # config is not initialized yet (ex. in conf.py)
-            suppress_warnings = []
+            suppress_warnings = ()
 
         if is_suppressed_warning(type, subtype, suppress_warnings):
             return False
@@ -589,12 +584,10 @@ class WarningLogRecordTranslator(SphinxLogRecordTranslator):
 
 def get_node_location(node: Node) -> str | None:
     source, line = get_source_line(node)
-    if source:
-        source = abspath(source)
     if source and line:
-        return f"{source}:{line}"
+        return f"{abspath(source)}:{line}"
     if source:
-        return f"{source}:"
+        return f"{abspath(source)}:"
     if line:
         return f"<unknown>:{line}"
     return None

sphinx/util/math.py

@@ -20,7 +20,9 @@ def get_node_equation_number(writer: HTML5Translator, node: nodes.math_block) ->
 
         id = node['ids'][0]
         number = writer.builder.fignumbers.get(key, {}).get(id, ())
-        return '.'.join(map(str, number))
+        eqno = '.'.join(map(str, number))
+        eqno = writer.builder.config.math_numsep.join(eqno.rsplit('.', 1))
+        return eqno
     else:
         return node['number']