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

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:
@@ -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,32 +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],
     *,
-    __overwrite_warning__: bool = True,
+    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.
@@ -112,22 +117,22 @@ def copyfile(
         # two different files might have the same size
         not filecmp.cmp(source, dest, shallow=False)
     ):
-        if __overwrite_warning__ and dest_exists:
+        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 = ('Copying the source path %s to %s will overwrite data, '
-                   'as a file already exists at the destination path '
-                   'and the content does not match.')
-            logger.info(msg, os.fsdecode(source), os.fsdecode(dest),
-                        type='misc', subtype='copy_overwrite')
+            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_-]')
@@ -183,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