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

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:

sphinx/util/osutil.py

@@ -13,10 +13,9 @@ from io import StringIO
 from os import path
 from typing import TYPE_CHECKING
 
-from sphinx.deprecation import _deprecation_warning
+from sphinx.locale import __
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
     from pathlib import Path
     from types import TracebackType
     from typing import Any
@@ -51,7 +50,7 @@ def relative_uri(base: str, to: str) -> str:
     b2 = base.split('#')[0].split(SEP)
     t2 = to.split('#')[0].split(SEP)
     # remove common segments (except the last segment)
-    for x, y in zip(b2[:-1], t2[:-1]):
+    for x, y in zip(b2[:-1], t2[:-1], strict=False):
         if x != y:
             break
         b2.pop(0)
@@ -72,27 +71,38 @@ def ensuredir(file: str | os.PathLike[str]) -> None:
     os.makedirs(file, exist_ok=True)
 
 
-def mtimes_of_files(dirnames: list[str], suffix: str) -> Iterator[float]:
-    for dirname in dirnames:
-        for root, _dirs, files in os.walk(dirname):
-            for sfile in files:
-                if sfile.endswith(suffix):
-                    with contextlib.suppress(OSError):
-                        yield path.getmtime(path.join(root, sfile))
+def _last_modified_time(source: str | os.PathLike[str], /) -> int:
+    """Return the last modified time of ``filename``.
 
+    The time is returned as integer microseconds.
+    The lowest common denominator of modern file-systems seems to be
+    microsecond-level precision.
 
-def copytimes(source: str | os.PathLike[str], dest: str | os.PathLike[str]) -> None:
+    We prefer to err on the side of re-rendering a file,
+    so we round up to the nearest microsecond.
+    """
+    st = source.stat() if isinstance(source, os.DirEntry) else os.stat(source)
+    # upside-down floor division to get the ceiling
+    return -(st.st_mtime_ns // -1_000)
+
+
+def _copy_times(source: str | os.PathLike[str], dest: str | os.PathLike[str]) -> None:
     """Copy a file's modification times."""
-    st = os.stat(source)
-    if hasattr(os, 'utime'):
-        os.utime(dest, (st.st_atime, st.st_mtime))
+    st = source.stat() if isinstance(source, os.DirEntry) else os.stat(source)
+    os.utime(dest, ns=(st.st_atime_ns, st.st_mtime_ns))
 
 
-def copyfile(source: str | os.PathLike[str], dest: str | os.PathLike[str]) -> None:
+def copyfile(
+    source: str | os.PathLike[str],
+    dest: str | os.PathLike[str],
+    *,
+    force: bool = False,
+) -> None:
     """Copy a file and its modification times, if possible.
 
     :param source: An existing source to copy.
     :param dest: The destination path.
+    :param bool force: Overwrite the destination file even if it exists.
     :raise FileNotFoundError: The *source* does not exist.
 
     .. note:: :func:`copyfile` is a no-op if *source* and *dest* are identical.
@@ -101,11 +111,28 @@ def copyfile(source: str | os.PathLike[str], dest: str | os.PathLike[str]) -> No
         msg = f'{os.fsdecode(source)} does not exist'
         raise FileNotFoundError(msg)
 
-    if not path.exists(dest) or not filecmp.cmp(source, dest):
+    if (
+        not (dest_exists := path.exists(dest)) or
+        # comparison must be done using shallow=False since
+        # two different files might have the same size
+        not filecmp.cmp(source, dest, shallow=False)
+    ):
+        if not force and dest_exists:
+            # sphinx.util.logging imports sphinx.util.osutil,
+            # so use a local import to avoid circular imports
+            from sphinx.util import logging
+            logger = logging.getLogger(__name__)
+
+            msg = __('Aborted attempted copy from %s to %s '
+                     '(the destination path has existing data).')
+            logger.warning(msg, os.fsdecode(source), os.fsdecode(dest),
+                           type='misc', subtype='copy_overwrite')
+            return
+
         shutil.copyfile(source, dest)
         with contextlib.suppress(OSError):
             # don't do full copystat because the source may be read-only
-            copytimes(source, dest)
+            _copy_times(source, dest)
 
 
 _no_fn_re = re.compile(r'[^a-zA-Z0-9_-]')
@@ -161,12 +188,8 @@ class _chdir:
         os.chdir(self._dirs.pop())
 
 
-@contextlib.contextmanager
-def cd(target_dir: str) -> Iterator[None]:
-    if sys.version_info[:2] >= (3, 11):
-        _deprecation_warning(__name__, 'cd', 'contextlib.chdir', remove=(8, 0))
-    with _chdir(target_dir):
-        yield
+if sys.version_info[:2] < (3, 11):
+    cd = _chdir
 
 
 class FileAvoidWrite:

sphinx/util/parallel.py

@@ -6,7 +6,7 @@ import os
 import time
 import traceback
 from math import sqrt
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 try:
     import multiprocessing
@@ -18,7 +18,7 @@ from sphinx.errors import SphinxParallelError
 from sphinx.util import logging
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
 logger = logging.getLogger(__name__)
 

sphinx/util/requests.py

@@ -19,7 +19,7 @@ def _get_tls_cacert(url: str, certs: str | dict[str, str] | None) -> str | bool:
     """Get additional CA cert for a specific URL."""
     if not certs:
         return True
-    elif isinstance(certs, (str, tuple)):
+    elif isinstance(certs, str | tuple):
         return certs
     else:
         hostname = urlsplit(url).netloc

sphinx/util/template.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import os
 from functools import partial
 from os import path
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 from jinja2 import TemplateNotFound
 from jinja2.loaders import BaseLoader
@@ -17,7 +17,7 @@ from sphinx.locale import get_translator
 from sphinx.util import rst, texescape
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
     from jinja2.environment import Environment
 
@@ -38,7 +38,7 @@ class BaseRenderer:
 
 class FileRenderer(BaseRenderer):
     def __init__(self, search_path: Sequence[str | os.PathLike[str]]) -> None:
-        if isinstance(search_path, (str, os.PathLike)):
+        if isinstance(search_path, str | os.PathLike):
             search_path = [search_path]
         else:
             # filter "None" paths