Sphinx 7.4.6__py3-none-any.whl → 8.0.0__py3-none-any.whl

sphinx/util/docfields.py

@@ -356,7 +356,7 @@ class DocFieldTransformer:
             if is_typefield:
                 # filter out only inline nodes; others will result in invalid
                 # markup being written out
-                content = [n for n in content if isinstance(n, (nodes.Inline, nodes.Text))]
+                content = [n for n in content if isinstance(n, nodes.Inline | nodes.Text)]
                 if content:
                     types.setdefault(typename, {})[fieldarg] = content
                 continue

sphinx/util/docutils.py

@@ -8,7 +8,7 @@ from collections.abc import Sequence  # NoQA: TCH003
 from contextlib import contextmanager
 from copy import copy
 from os import path
-from typing import IO, TYPE_CHECKING, Any, Callable, cast
+from typing import IO, TYPE_CHECKING, Any, cast
 
 import docutils
 from docutils import nodes
@@ -27,7 +27,7 @@ logger = logging.getLogger(__name__)
 report_re = re.compile('^(.+?:(?:\\d+)?): \\((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\\d+)?\\) ')
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator  # NoQA: TCH003
     from types import ModuleType
 
     from docutils.frontend import Values
@@ -366,30 +366,47 @@ class SphinxDirective(Directive):
 
     This class provides helper methods for Sphinx directives.
 
+    .. versionadded:: 1.8
+
     .. note:: The subclasses of this class might not work with docutils.
               This class is strongly coupled with Sphinx.
     """
 
     @property
     def env(self) -> BuildEnvironment:
-        """Reference to the :class:`.BuildEnvironment` object."""
+        """Reference to the :class:`.BuildEnvironment` object.
+
+        .. versionadded:: 1.8
+        """
         return self.state.document.settings.env
 
     @property
     def config(self) -> Config:
-        """Reference to the :class:`.Config` object."""
+        """Reference to the :class:`.Config` object.
+
+        .. versionadded:: 1.8
+        """
         return self.env.config
 
     def get_source_info(self) -> tuple[str, int]:
-        """Get source and line number."""
+        """Get source and line number.
+
+        .. versionadded:: 3.0
+        """
         return self.state_machine.get_source_and_line(self.lineno)
 
     def set_source_info(self, node: Node) -> None:
-        """Set source and line number to the node."""
+        """Set source and line number to the node.
+
+        .. versionadded:: 2.1
+        """
         node.source, node.line = self.get_source_info()
 
     def get_location(self) -> str:
-        """Get current location info for logging."""
+        """Get current location info for logging.
+
+        .. versionadded:: 4.2
+        """
         source, line = self.get_source_info()
         if source and line:
             return f'{source}:{line}'
@@ -473,6 +490,8 @@ class SphinxRole:
 
     This class provides helper methods for Sphinx roles.
 
+    .. versionadded:: 2.0
+
     .. note:: The subclasses of this class might not work with docutils.
               This class is strongly coupled with Sphinx.
     """
@@ -517,24 +536,35 @@ class SphinxRole:
 
     @property
     def env(self) -> BuildEnvironment:
-        """Reference to the :class:`.BuildEnvironment` object."""
+        """Reference to the :class:`.BuildEnvironment` object.
+
+        .. versionadded:: 2.0
+        """
         return self.inliner.document.settings.env
 
     @property
     def config(self) -> Config:
-        """Reference to the :class:`.Config` object."""
+        """Reference to the :class:`.Config` object.
+
+        .. versionadded:: 2.0
+        """
         return self.env.config
 
     def get_source_info(self, lineno: int | None = None) -> tuple[str, int]:
+        # .. versionadded:: 3.0
         if lineno is None:
             lineno = self.lineno
         return self.inliner.reporter.get_source_and_line(lineno)  # type: ignore[attr-defined]
 
     def set_source_info(self, node: Node, lineno: int | None = None) -> None:
+        # .. versionadded:: 2.0
         node.source, node.line = self.get_source_info(lineno)
 
     def get_location(self) -> str:
-        """Get current location info for logging."""
+        """Get current location info for logging.
+
+        .. versionadded:: 4.2
+        """
         source, line = self.get_source_info()
         if source and line:
             return f'{source}:{line}'
@@ -551,6 +581,8 @@ class ReferenceRole(SphinxRole):
     The reference roles can accept ``link title <target>`` style as a text for
     the role.  The parsed result; link title and target will be stored to
     ``self.title`` and ``self.target``.
+
+    .. versionadded:: 2.0
     """
 
     has_explicit_title: bool    #: A boolean indicates the role has explicit title or not.
@@ -591,6 +623,8 @@ class SphinxTranslator(nodes.NodeVisitor):
 
     It also provides helper methods for Sphinx translators.
 
+    .. versionadded:: 2.0
+
     .. note:: The subclasses of this class might not work with docutils.
               This class is strongly coupled with Sphinx.
     """

sphinx/util/fileutil.py

@@ -4,16 +4,22 @@ from __future__ import annotations
 
 import os
 import posixpath
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 from docutils.utils import relative_path
 
+from sphinx.locale import __
+from sphinx.util import logging
 from sphinx.util.osutil import copyfile, ensuredir
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from sphinx.util.template import BaseRenderer
     from sphinx.util.typing import PathMatcher
 
+logger = logging.getLogger(__name__)
+
 
 def _template_basename(filename: str | os.PathLike[str]) -> str | None:
     """Given an input filename:
@@ -30,7 +36,9 @@ def _template_basename(filename: str | os.PathLike[str]) -> str | 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:
+                    renderer: BaseRenderer | None = None,
+                    *,
+                    force: bool = False) -> None:
     """Copy an asset file to destination.
 
     On copying, it expands the template variables if context argument is given and
@@ -40,6 +48,7 @@ def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLi
     :param destination: The path to destination file or directory
     :param context: The template variables.  If not given, template files are simply copied
     :param renderer: The template engine.  If not given, SphinxRenderer is used by default
+    :param bool force: Overwrite the destination file even if it exists.
     """
     if not os.path.exists(source):
         return
@@ -56,28 +65,46 @@ def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLi
             renderer = SphinxRenderer()
 
         with open(source, encoding='utf-8') as fsrc:
-            destination = _template_basename(destination) or destination
-            with open(destination, 'w', encoding='utf-8') as fdst:
-                fdst.write(renderer.render_string(fsrc.read(), context))
+            template_content = fsrc.read()
+        rendered_template = renderer.render_string(template_content, context)
+
+        if (
+            not force
+            and os.path.exists(destination)
+            and template_content != rendered_template
+        ):
+            msg = __('Aborted attempted copy from rendered template %s to %s '
+                     '(the destination path has existing data).')
+            logger.warning(msg, os.fsdecode(source), os.fsdecode(destination),
+                           type='misc', subtype='copy_overwrite')
+            return
+
+        destination = _template_basename(destination) or destination
+        with open(destination, 'w', encoding='utf-8') as fdst:
+            fdst.write(rendered_template)
     else:
-        copyfile(source, destination)
+        copyfile(source, destination, force=force)
 
 
 def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[str],
                excluded: PathMatcher = lambda path: False,
                context: dict[str, Any] | None = None, renderer: BaseRenderer | None = None,
-               onerror: Callable[[str, Exception], None] | None = None) -> None:
+               onerror: Callable[[str, Exception], None] | None = None,
+               *, force: bool = False) -> None:
     """Copy asset files to destination recursively.
 
     On copying, it expands the template variables if context argument is given and
     the asset is a template file.
 
+    Use ``copy_asset_file`` instead to copy a single file.
+
     :param source: The path to source file or directory
     :param destination: The path to destination directory
     :param excluded: The matcher to determine the given path should be copied or not
     :param context: The template variables.  If not given, template files are simply copied
     :param renderer: The template engine.  If not given, SphinxRenderer is used by default
     :param onerror: The error handler.
+    :param bool force: Overwrite the destination file even if it exists.
     """
     if not os.path.exists(source):
         return
@@ -88,7 +115,10 @@ def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[st
 
     ensuredir(destination)
     if os.path.isfile(source):
-        copy_asset_file(source, destination, context, renderer)
+        copy_asset_file(source, destination,
+                        context=context,
+                        renderer=renderer,
+                        force=force)
         return
 
     for root, dirs, files in os.walk(source, followlinks=True):
@@ -104,7 +134,9 @@ def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[st
                 try:
                     copy_asset_file(posixpath.join(root, filename),
                                     posixpath.join(destination, reldir),
-                                    context, renderer)
+                                    context=context,
+                                    renderer=renderer,
+                                    force=force)
                 except Exception as exc:
                     if onerror:
                         onerror(posixpath.join(root, filename), exc)

sphinx/util/i18n.py

@@ -15,12 +15,17 @@ from babel.messages.pofile import read_po
 from sphinx.errors import SphinxError
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.osutil import SEP, canon_path, relpath
+from sphinx.util.osutil import (
+    SEP,
+    _last_modified_time,
+    canon_path,
+    relpath,
+)
 
 if TYPE_CHECKING:
     import datetime as dt
     from collections.abc import Iterator
-    from typing import Protocol, Union
+    from typing import Protocol, TypeAlias
 
     from babel.core import Locale
 
@@ -52,7 +57,7 @@ if TYPE_CHECKING:
             locale: str | Locale | None = ...,
         ) -> str: ...
 
-    Formatter = Union[DateFormatter, TimeFormatter, DatetimeFormatter]
+    Formatter: TypeAlias = DateFormatter | TimeFormatter | DatetimeFormatter
 
 logger = logging.getLogger(__name__)
 
@@ -84,7 +89,7 @@ class CatalogInfo(LocaleFileInfoBase):
     def is_outdated(self) -> bool:
         return (
             not path.exists(self.mo_path) or
-            path.getmtime(self.mo_path) < path.getmtime(self.po_path))
+            _last_modified_time(self.mo_path) < _last_modified_time(self.po_path))
 
     def write_mo(self, locale: str, use_fuzzy: bool = False) -> None:
         with open(self.po_path, encoding=self.charset) as file_po:

sphinx/util/images.py

@@ -13,8 +13,9 @@ if TYPE_CHECKING:
 
 try:
     from PIL import Image
+    PILLOW_AVAILABLE = True
 except ImportError:
-    Image = None
+    PILLOW_AVAILABLE = False
 
 mime_suffixes = {
     '.gif': 'image/gif',
@@ -43,7 +44,7 @@ def get_image_size(filename: str) -> tuple[int, int] | None:
         elif isinstance(size[0], float) or isinstance(size[1], float):
             size = (int(size[0]), int(size[1]))
 
-        if size is None and Image:  # fallback to Pillow
+        if size is None and PILLOW_AVAILABLE:  # fallback to Pillow
             with Image.open(filename) as im:
                 size = im.size
 

sphinx/util/inspect.py

@@ -17,19 +17,19 @@ from importlib import import_module
 from inspect import Parameter, Signature
 from io import StringIO
 from types import ClassMethodDescriptorType, MethodDescriptorType, WrapperDescriptorType
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, ForwardRef
 
 from sphinx.pycode.ast import unparse as ast_unparse
 from sphinx.util import logging
-from sphinx.util.typing import ForwardRef, stringify_annotation
+from sphinx.util.typing import stringify_annotation
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
     from inspect import _ParameterKind
     from types import MethodType, ModuleType
-    from typing import Final, Protocol, Union
+    from typing import Final, Protocol, TypeAlias
 
-    from typing_extensions import TypeAlias, TypeIs
+    from typing_extensions import TypeIs
 
     class _SupportsGet(Protocol):
         def __get__(self, __instance: Any, __owner: type | None = ...) -> Any: ...  # NoQA: E704
@@ -42,21 +42,21 @@ if TYPE_CHECKING:
         # 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,
-    ]
+    _RoutineType: TypeAlias = (
+        types.FunctionType
+        | types.LambdaType
+        | types.MethodType
+        | types.BuiltinFunctionType
+        | types.BuiltinMethodType
+        | types.WrapperDescriptorType
+        | types.MethodDescriptorType
+        | types.ClassMethodDescriptorType
+    )
+    _SignatureType: TypeAlias = (
+        Callable[..., Any]
+        | staticmethod
+        | classmethod
+    )
 
 logger = logging.getLogger(__name__)
 
@@ -128,20 +128,14 @@ def getall(obj: Any) -> Sequence[str] | None:
     __all__ = safe_getattr(obj, '__all__', None)
     if __all__ is None:
         return None
-    if isinstance(__all__, (list, tuple)) and all(isinstance(e, str) for e in __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]:
     """Safely get the ``__annotations__`` attribute of an object."""
-    if sys.version_info >= (3, 10, 0) or not isinstance(obj, type):
-        __annotations__ = safe_getattr(obj, '__annotations__', None)
-    else:
-        # Workaround for bugfix not available until python 3.10 as recommended by docs
-        # https://docs.python.org/3.10/howto/annotations.html#accessing-the-annotations-dict-of-an-object-in-python-3-9-and-older
-        __dict__ = safe_getattr(obj, '__dict__', {})
-        __annotations__ = __dict__.get('__annotations__', None)
+    __annotations__ = safe_getattr(obj, '__annotations__', None)
     if isinstance(__annotations__, Mapping):
         return __annotations__
     return {}
@@ -198,21 +192,12 @@ def getslots(obj: Any) -> dict[str, Any] | dict[str, None] | None:
         return __slots__
     elif isinstance(__slots__, str):
         return {__slots__: None}
-    elif isinstance(__slots__, (list, tuple)):
+    elif isinstance(__slots__, list | tuple):
         return dict.fromkeys(__slots__)
     else:
         raise ValueError
 
 
-def isNewType(obj: Any) -> bool:
-    """Check the if object is a kind of :class:`~typing.NewType`."""
-    if sys.version_info[:2] >= (3, 10):
-        return isinstance(obj, typing.NewType)
-    __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) -> TypeIs[type[enum.Enum]]:
     """Check if the object is an :class:`enumeration class <enum.Enum>`."""
     return isclass(x) and issubclass(x, enum.Enum)
@@ -237,7 +222,7 @@ def unpartial(obj: Any) -> Any:
 
 def ispartial(obj: Any) -> TypeIs[partial | partialmethod]:
     """Check if the object is a partial function or method."""
-    return isinstance(obj, (partial, partialmethod))
+    return isinstance(obj, partial | partialmethod)
 
 
 def isclassmethod(
@@ -397,12 +382,12 @@ def _is_wrapped_coroutine(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))
+    return isinstance(obj, property | cached_property)
 
 
 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]
+    return isinstance(obj, types.GenericAlias | typing._BaseGenericAlias)  # type: ignore[attr-defined]
 
 
 def safe_getattr(obj: Any, name: str, *defargs: Any) -> Any:
@@ -652,7 +637,7 @@ def signature(
     try:
         # Resolve annotations using ``get_type_hints()`` and type_aliases.
         localns = TypeAliasNamespace(type_aliases)
-        annotations = typing.get_type_hints(subject, None, localns)
+        annotations = typing.get_type_hints(subject, None, localns, include_extras=True)
         for i, param in enumerate(parameters):
             if param.name in annotations:
                 annotation = annotations[param.name]
@@ -852,11 +837,11 @@ def signature_from_ast(node: ast.FunctionDef, code: str = '') -> Signature:
     params: list[Parameter] = []
 
     # positional-only arguments (introduced in Python 3.8)
-    for arg, defexpr in zip(args.posonlyargs, defaults):
+    for arg, defexpr in zip(args.posonlyargs, defaults, strict=False):
         params.append(_define(Parameter.POSITIONAL_ONLY, arg, code, defexpr=defexpr))
 
     # normal arguments
-    for arg, defexpr in zip(args.args, defaults[pos_only_offset:]):
+    for arg, defexpr in zip(args.args, defaults[pos_only_offset:], strict=False):
         params.append(_define(Parameter.POSITIONAL_OR_KEYWORD, arg, code, defexpr=defexpr))
 
     # variadic positional argument (no possible default expression)
@@ -864,7 +849,7 @@ def signature_from_ast(node: ast.FunctionDef, code: str = '') -> Signature:
         params.append(_define(Parameter.VAR_POSITIONAL, args.vararg, code, defexpr=None))
 
     # keyword-only arguments
-    for arg, defexpr in zip(args.kwonlyargs, args.kw_defaults):
+    for arg, defexpr in zip(args.kwonlyargs, args.kw_defaults, strict=False):
         params.append(_define(Parameter.KEYWORD_ONLY, arg, code, defexpr=defexpr))
 
     # variadic keyword argument (no possible default expression)

sphinx/util/inventory.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import os
 import re
 import zlib
-from typing import IO, TYPE_CHECKING, Callable
+from typing import IO, TYPE_CHECKING
 
 from sphinx.locale import __
 from sphinx.util import logging
@@ -13,7 +13,7 @@ BUFSIZE = 16 * 1024
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
 
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment

sphinx/util/matching.py

@@ -4,12 +4,12 @@ from __future__ import annotations
 
 import os.path
 import re
-from typing import TYPE_CHECKING, Callable
+from typing import TYPE_CHECKING
 
 from sphinx.util.osutil import canon_path, path_stabilize
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator
+    from collections.abc import Callable, Iterable, Iterator
 
 
 def _translate_pattern(pat: str) -> str:

sphinx/util/math.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from docutils import nodes
 
-    from sphinx.builders.html import HTML5Translator
+    from sphinx.writers.html5 import HTML5Translator
 
 
 def get_node_equation_number(writer: HTML5Translator, node: nodes.math_block) -> str:

sphinx/util/nodes.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import contextlib
 import re
 import unicodedata
-from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
 
 from docutils import nodes
 from docutils.nodes import Node
@@ -16,7 +16,7 @@ from sphinx.util import logging
 from sphinx.util.parsing import _fresh_title_style_context
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator
+    from collections.abc import Callable, Iterable, Iterator
 
     from docutils.nodes import Element
     from docutils.parsers.rst import Directive
@@ -178,12 +178,12 @@ def apply_source_workaround(node: Element) -> None:
         return
 
     # workaround: some docutils nodes doesn't have source, line.
-    if (isinstance(node, (
-            nodes.rubric,  # #1305 rubric directive
-            nodes.line,  # #1477 line node
-            nodes.image,  # #3093 image directive in substitution
-            nodes.field_name,  # #3335 field list syntax
-    ))):
+    if isinstance(node, (
+        nodes.rubric  # #1305 rubric directive
+        | nodes.line  # #1477 line node
+        | nodes.image  # #3093 image directive in substitution
+        | nodes.field_name  # #3335 field list syntax
+    )):
         logger.debug('[i18n] PATCH: %r to have source and line: %s',
                      get_full_module_name(node), repr_domxml(node))
         try: