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

sphinx/project.py

@@ -4,13 +4,14 @@ from __future__ import annotations
 
 import contextlib
 import os
-from glob import glob
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 from sphinx.locale import __
 from sphinx.util import logging
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.matching import get_matching_files
-from sphinx.util.osutil import path_stabilize, relpath
+from sphinx.util.osutil import path_stabilize
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
@@ -24,7 +25,7 @@ class Project:
 
     def __init__(self, srcdir: str | os.PathLike[str], source_suffix: Iterable[str]) -> None:
         #: Source directory.
-        self.srcdir = srcdir
+        self.srcdir = _StrPath(srcdir)
 
         #: source_suffix. Same as :confval:`source_suffix`.
         self.source_suffix = tuple(source_suffix)
@@ -34,8 +35,8 @@ class Project:
         self.docnames: set[str] = set()
 
         # Bijective mapping between docnames and (srcdir relative) paths.
-        self._path_to_docname: dict[str, str] = {}
-        self._docname_to_path: dict[str, str] = {}
+        self._path_to_docname: dict[Path, str] = {}
+        self._docname_to_path: dict[str, Path] = {}
 
     def restore(self, other: Project) -> None:
         """Take over a result of last build."""
@@ -60,22 +61,25 @@ class Project:
         ):
             if docname := self.path2doc(filename):
                 if docname in self.docnames:
-                    pattern = os.path.join(self.srcdir, docname) + '.*'
-                    files = [relpath(f, self.srcdir) for f in glob(pattern)]
+                    files = [
+                        str(f.relative_to(self.srcdir))
+                        for f in self.srcdir.glob(f'{docname}.*')
+                    ]
                     logger.warning(
                         __(
-                            'multiple files found for the document "%s": %r\n'
+                            'multiple files found for the document "%s": %s\n'
                             'Use %r for the build.'
                         ),
                         docname,
-                        files,
+                        ', '.join(files),
                         self.doc2path(docname, absolute=True),
                         once=True,
                     )
-                elif os.access(os.path.join(self.srcdir, filename), os.R_OK):
+                elif os.access(self.srcdir / filename, os.R_OK):
                     self.docnames.add(docname)
-                    self._path_to_docname[filename] = docname
-                    self._docname_to_path[docname] = filename
+                    path = Path(filename)
+                    self._path_to_docname[path] = docname
+                    self._docname_to_path[docname] = path
                 else:
                     logger.warning(
                         __('Ignored unreadable document %r.'), filename, location=docname
@@ -91,18 +95,19 @@ class Project:
         try:
             return self._path_to_docname[filename]  # type: ignore[index]
         except KeyError:
-            if os.path.isabs(filename):
+            path = Path(filename)
+            if path.is_absolute():
                 with contextlib.suppress(ValueError):
-                    filename = os.path.relpath(filename, self.srcdir)
+                    path = path.relative_to(self.srcdir)
 
             for suffix in self.source_suffix:
-                if os.path.basename(filename).endswith(suffix):
-                    return path_stabilize(filename).removesuffix(suffix)
+                if path.name.endswith(suffix):
+                    return path_stabilize(path).removesuffix(suffix)
 
             # the file does not have a docname
             return None
 
-    def doc2path(self, docname: str, absolute: bool) -> str:
+    def doc2path(self, docname: str, absolute: bool) -> _StrPath:
         """Return the filename for the document name.
 
         If *absolute* is True, return as an absolute path.
@@ -112,8 +117,8 @@ class Project:
             filename = self._docname_to_path[docname]
         except KeyError:
             # Backwards compatibility: the document does not exist
-            filename = docname + self._first_source_suffix
+            filename = Path(docname + self._first_source_suffix)
 
         if absolute:
-            return os.path.join(self.srcdir, filename)
-        return filename
+            return _StrPath(self.srcdir / filename)
+        return _StrPath(filename)

sphinx/pycode/ast.py

@@ -130,7 +130,7 @@ class _UnparseVisitor(ast.NodeVisitor):
     def visit_Constant(self, node: ast.Constant) -> str:
         if node.value is Ellipsis:
             return "..."
-        elif isinstance(node.value, (int, float, complex)):
+        elif isinstance(node.value, int | float | complex):
             if self.code:
                 return ast.get_source_segment(self.code, node) or repr(node.value)
             else:
@@ -141,7 +141,7 @@ class _UnparseVisitor(ast.NodeVisitor):
     def visit_Dict(self, node: ast.Dict) -> str:
         keys = (self.visit(k) for k in node.keys if k is not None)
         values = (self.visit(v) for v in node.values)
-        items = (k + ": " + v for k, v in zip(keys, values))
+        items = (k + ": " + v for k, v in zip(keys, values, strict=True))
         return "{" + ", ".join(items) + "}"
 
     def visit_Lambda(self, node: ast.Lambda) -> str:

sphinx/pycode/parser.py

@@ -108,7 +108,7 @@ class Token:
             return self.kind == other
         elif isinstance(other, str):
             return self.value == other
-        elif isinstance(other, (list, tuple)):
+        elif isinstance(other, list | tuple):
             return [self.kind, self.value] == list(other)
         elif other is None:
             return False
@@ -404,7 +404,7 @@ class VariableCommentPicker(ast.NodeVisitor):
 
     def visit_Expr(self, node: ast.Expr) -> None:
         """Handles Expr node and pick up a comment if string."""
-        if (isinstance(self.previous, (ast.Assign, ast.AnnAssign)) and
+        if (isinstance(self.previous, ast.Assign | ast.AnnAssign) and
                 isinstance(node.value, ast.Constant) and isinstance(node.value.value, str)):
             try:
                 targets = get_assign_targets(self.previous)

sphinx/pygments_styles.py

@@ -28,12 +28,12 @@ class SphinxStyle(Style):
     background_color = '#eeffcc'
     default_style = ''
 
-    styles = FriendlyStyle.styles
-    styles.update({
+    styles = {
+        **FriendlyStyle.styles,
         Generic.Output: '#333',
         Comment: 'italic #408090',
         Number: '#208050',
-    })
+    }
 
 
 class PyramidStyle(Style):

sphinx/registry.py

@@ -2,16 +2,11 @@
 
 from __future__ import annotations
 
-import sys
 import traceback
 from importlib import import_module
+from importlib.metadata import entry_points
 from types import MethodType
-from typing import TYPE_CHECKING, Any, Callable
-
-if sys.version_info >= (3, 10):
-    from importlib.metadata import entry_points
-else:
-    from importlib_metadata import entry_points
+from typing import TYPE_CHECKING, Any
 
 from sphinx.domains import Domain, Index, ObjType
 from sphinx.domains.std import GenericObject, Target
@@ -25,7 +20,7 @@ from sphinx.util import logging
 from sphinx.util.logging import prefixed_warnings
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Sequence
+    from collections.abc import Callable, Iterator, Sequence
 
     from docutils import nodes
     from docutils.core import Publisher

sphinx/search/__init__.py

@@ -487,7 +487,7 @@ class IndexBuilder:
         self._index_entries[docname] = sorted(_index_entries)
 
     def _word_collector(self, doctree: nodes.document) -> WordStore:
-        def _visit_nodes(node):
+        def _visit_nodes(node: nodes.Node) -> None:
             if isinstance(node, nodes.comment):
                 return
             elif isinstance(node, nodes.raw):

sphinx/testing/path.py

@@ -4,12 +4,13 @@ import os
 import shutil
 import sys
 import warnings
-from typing import IO, TYPE_CHECKING, Any, Callable
+from typing import IO, TYPE_CHECKING, Any
 
 from sphinx.deprecation import RemovedInSphinx90Warning
 
 if TYPE_CHECKING:
     import builtins
+    from collections.abc import Callable
 
 warnings.warn("'sphinx.testing.path' is deprecated. "
               "Use 'os.path' or 'pathlib' instead.",

sphinx/testing/util.py

@@ -43,7 +43,7 @@ def assert_node(node: Node, cls: Any = None, xpath: str = "", **kwargs: Any) ->
                         'The node%s has %d child nodes, not one' % (xpath, len(node))
                     assert_node(node[0], cls[1:], xpath=xpath + "[0]", **kwargs)
         elif isinstance(cls, tuple):
-            assert isinstance(node, (list, nodes.Element)), \
+            assert isinstance(node, list | nodes.Element), \
                 'The node%s does not have any items' % xpath
             assert len(node) == len(cls), \
                 'The node%s has %d child nodes, not %r' % (xpath, len(node), len(cls))

sphinx/texinputs/Makefile.jinja

@@ -77,7 +77,8 @@ tar: all-$(FMT)
 	rm -r $(ARCHIVEPREFIX)docs-$(FMT)
 
 gz: tar
-	gzip -9 < $(ARCHIVEPREFIX)docs-$(FMT).tar > $(ARCHIVEPREFIX)docs-$(FMT).tar.gz
+	# -n to omit mtime from gzip headers
+	gzip -n -9 < $(ARCHIVEPREFIX)docs-$(FMT).tar > $(ARCHIVEPREFIX)docs-$(FMT).tar.gz
 
 bz2: tar
 	bzip2 -9 -k $(ARCHIVEPREFIX)docs-$(FMT).tar

sphinx/texinputs_win/Makefile.jinja

@@ -49,7 +49,8 @@ tar: all-$(FMT)
 	rm -r $(ARCHIVEPREFIX)docs-$(FMT)
 
 gz: tar
-	gzip -9 < $(ARCHIVEPREFIX)docs-$(FMT).tar > $(ARCHIVEPREFIX)docs-$(FMT).tar.gz
+	# -n to omit mtime from gzip headers
+	gzip -n -9 < $(ARCHIVEPREFIX)docs-$(FMT).tar > $(ARCHIVEPREFIX)docs-$(FMT).tar.gz
 
 bz2: tar
 	bzip2 -9 -k $(ARCHIVEPREFIX)docs-$(FMT).tar

sphinx/theming.py

@@ -10,6 +10,7 @@ import os
 import shutil
 import sys
 import tempfile
+from importlib.metadata import entry_points
 from os import path
 from typing import TYPE_CHECKING, Any
 from zipfile import ZipFile
@@ -26,10 +27,6 @@ if sys.version_info >= (3, 11):
 else:
     import tomli as tomllib
 
-if sys.version_info >= (3, 10):
-    from importlib.metadata import entry_points
-else:
-    from importlib_metadata import entry_points
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -121,17 +118,11 @@ class Theme:
         elif section == 'options':
             value = self._options.get(name, default)
         else:
-            # https://github.com/sphinx-doc/sphinx/issues/12305
-            # For backwards compatibility when attempting to read a value
-            # from an unsupported configuration section.
-            # xref: RemovedInSphinx80Warning
             msg = __(
                 'Theme configuration sections other than [theme] and [options] '
-                'are not supported, returning the default value instead '
-                '(tried to get a value from %r)'
+                'are not supported (tried to get a value from %r).'
             )
-            logger.info(msg, section)
-            value = default
+            raise ThemeError(msg)
         if value is _NO_DEFAULT:
             msg = __('setting %s.%s occurs in none of the searched theme configs') % (
                 section,

sphinx/transforms/__init__.py

@@ -22,10 +22,10 @@ from sphinx.util.nodes import apply_source_workaround, is_smartquotable
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
-    from typing import Literal
+    from typing import Literal, TypeAlias
 
     from docutils.nodes import Node, Text
-    from typing_extensions import TypeAlias, TypeIs
+    from typing_extensions import TypeIs
 
     from sphinx.application import Sphinx
     from sphinx.config import Config
@@ -247,7 +247,7 @@ class ApplySourceWorkaround(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         for node in self.document.findall():  # type: Node
-            if isinstance(node, (nodes.TextElement, nodes.image, nodes.topic)):
+            if isinstance(node, nodes.TextElement | nodes.image | nodes.topic):
                 apply_source_workaround(node)
 
 
@@ -364,7 +364,7 @@ class SphinxSmartQuotes(SmartQuotes, SphinxTransform):
         # override default settings with :confval:`smartquotes_action`
         self.smartquotes_action = self.config.smartquotes_action
 
-        super().apply()
+        super().apply()  # type: ignore[no-untyped-call]
 
     def is_available(self) -> bool:
         builders = self.config.smartquotes_excludes.get('builders', [])
@@ -477,7 +477,7 @@ def _reorder_index_target_nodes(start_node: nodes.target) -> None:
     # as we want *consecutive* target & index nodes.
     node: nodes.Node
     for node in start_node.findall(descend=False, siblings=True):
-        if isinstance(node, (nodes.target, addnodes.index)):
+        if isinstance(node, nodes.target | addnodes.index):
             nodes_to_reorder.append(node)
             continue
         break  # must be a consecutive run of target or index nodes

sphinx/transforms/references.py

@@ -23,7 +23,7 @@ class SphinxDanglingReferences(DanglingReferences):
 
             # suppress INFO level messages for a while
             reporter.report_level = max(reporter.WARNING_LEVEL, reporter.report_level)
-            super().apply()
+            super().apply()  # type: ignore[no-untyped-call]
         finally:
             reporter.report_level = report_level
 

sphinx/util/__init__.py

@@ -13,12 +13,8 @@ from urllib.parse import parse_qsl, quote_plus, urlencode, urlsplit, urlunsplit
 
 from sphinx.errors import ExtensionError, FiletypeNotFoundError
 from sphinx.locale import __
-from sphinx.util import display as _display
-from sphinx.util import exceptions as _exceptions
-from sphinx.util import http_date as _http_date
 from sphinx.util import index_entries as _index_entries
 from sphinx.util import logging
-from sphinx.util import osutil as _osutil
 from sphinx.util.console import strip_colors  # NoQA: F401
 from sphinx.util.matching import patfilter  # NoQA: F401
 from sphinx.util.nodes import (  # NoQA: F401
@@ -33,10 +29,8 @@ from sphinx.util.nodes import (  # NoQA: F401
 from sphinx.util.osutil import (  # NoQA: F401
     SEP,
     copyfile,
-    copytimes,
     ensuredir,
     make_filename,
-    mtimes_of_files,
     os_path,
     relative_uri,
 )
@@ -54,9 +48,9 @@ def docname_join(basedocname: str, docname: str) -> str:
     return posixpath.normpath(posixpath.join('/' + basedocname, '..', docname))[1:]
 
 
-def get_filetype(source_suffix: dict[str, str], filename: str) -> str:
+def get_filetype(source_suffix: dict[str, str], filename: str | os.PathLike) -> str:
     for suffix, filetype in source_suffix.items():
-        if filename.endswith(suffix):
+        if os.fspath(filename).endswith(suffix):
             # If default filetype (None), considered as restructuredtext.
             return filetype or 'restructuredtext'
     raise FiletypeNotFoundError
@@ -258,32 +252,16 @@ def isurl(url: str) -> bool:
     return bool(url) and '://' in url
 
 
-def _xml_name_checker() -> re.Pattern[str]:
-    # to prevent import cycles
-    from sphinx.builders.epub3 import _XML_NAME_PATTERN
-
-    return _XML_NAME_PATTERN
-
-
 # deprecated name -> (object to return, canonical path or empty string)
-_DEPRECATED_OBJECTS: dict[str, tuple[Any, str] | tuple[Any, str, tuple[int, int]]] = {
-    'path_stabilize': (_osutil.path_stabilize, 'sphinx.util.osutil.path_stabilize'),
-    'display_chunk': (_display.display_chunk, 'sphinx.util.display.display_chunk'),
-    'status_iterator': (_display.status_iterator, 'sphinx.util.display.status_iterator'),
-    'SkipProgressMessage': (_display.SkipProgressMessage,
-                            'sphinx.util.display.SkipProgressMessage'),
-    'progress_message': (_display.progress_message, 'sphinx.util.display.progress_message'),
-    'epoch_to_rfc1123': (_http_date.epoch_to_rfc1123, 'sphinx.http_date.epoch_to_rfc1123'),
-    'rfc1123_to_epoch': (_http_date.rfc1123_to_epoch, 'sphinx.http_date.rfc1123_to_epoch'),
-    'save_traceback': (_exceptions.save_traceback, 'sphinx.exceptions.save_traceback'),
-    'format_exception_cut_frames': (_exceptions.format_exception_cut_frames,
-                                    'sphinx.exceptions.format_exception_cut_frames'),
-    'xmlname_checker': (_xml_name_checker, 'sphinx.builders.epub3._XML_NAME_PATTERN'),
+_DEPRECATED_OBJECTS: dict[str, tuple[Any, str, tuple[int, int]]] = {
     'split_index_msg': (_index_entries.split_index_msg,
-                        'sphinx.util.index_entries.split_index_msg'),
-    'split_into': (_index_entries.split_index_msg, 'sphinx.util.index_entries.split_into'),
-    'md5': (_md5, ''),
-    'sha1': (_sha1, ''),
+                        'sphinx.util.index_entries.split_index_msg',
+                        (9, 0)),
+    'split_into': (_index_entries.split_index_msg,
+                   'sphinx.util.index_entries.split_into',
+                   (9, 0)),
+    'md5': (_md5, '', (9, 0)),
+    'sha1': (_sha1, '', (9, 0)),
 }
 
 
@@ -294,8 +272,6 @@ def __getattr__(name: str) -> Any:
 
     from sphinx.deprecation import _deprecation_warning
 
-    info = _DEPRECATED_OBJECTS[name]
-    deprecated_object, canonical_name = info[:2]
-    remove = info[2] if len(info) == 3 else (8, 0)
+    deprecated_object, canonical_name, remove = _DEPRECATED_OBJECTS[name]
     _deprecation_warning(__name__, name, canonical_name, remove=remove)
     return deprecated_object

sphinx/util/_pathlib.py

@@ -1,4 +1,16 @@
-"""What follows is awful and will be gone in Sphinx 8"""
+"""What follows is awful and will be gone in Sphinx 9.
+
+Instances of _StrPath should not be constructed except in Sphinx itself.
+Consumers of Sphinx APIs should prefer using ``pathlib.Path`` objects
+where possible. _StrPath objects can be treated as equivalent to ``Path``,
+save that ``_StrPath.replace`` is overriden with ``str.replace``.
+
+To continue treating path-like objects as strings, use ``os.fspath``,
+or explicit string coercion.
+
+In Sphinx 9, ``Path`` objects will be expected and returned in all instances
+that ``_StrPath`` is currently used.
+"""
 
 from __future__ import annotations
 
@@ -7,13 +19,13 @@ import warnings
 from pathlib import Path, PosixPath, PurePath, WindowsPath
 from typing import Any
 
-from sphinx.deprecation import RemovedInSphinx80Warning
+from sphinx.deprecation import RemovedInSphinx90Warning
 
 _STR_METHODS = frozenset(str.__dict__)
 _PATH_NAME = Path().__class__.__name__
 
 _MSG = (
-    'Sphinx 8 will drop support for representing paths as strings. '
+    'Sphinx 9 will drop support for representing paths as strings. '
     'Use "pathlib.Path" or "os.fspath" instead.'
 )
 
@@ -27,35 +39,35 @@ if sys.platform == 'win32':
         ) -> str:
             # replace exists in both Path and str;
             # in Path it makes filesystem changes, so we use the safer str version
-            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return self.__str__().replace(old, new, count)  # NoQA:  PLC2801
 
         def __getattr__(self, item: str) -> Any:
             if item in _STR_METHODS:
-                warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
                 return getattr(self.__str__(), item)
             msg = f'{_PATH_NAME!r} has no attribute {item!r}'
             raise AttributeError(msg)
 
         def __add__(self, other: str) -> str:
-            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return self.__str__() + other
 
         def __bool__(self) -> bool:
             if not self.__str__():
-                warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
                 return False
             return True
 
         def __contains__(self, item: str) -> bool:
-            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return item in self.__str__()
 
         def __eq__(self, other: object) -> bool:
             if isinstance(other, PurePath):
                 return super().__eq__(other)
             if isinstance(other, str):
-                warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
                 return self.__str__() == other
             return NotImplemented
 
@@ -63,11 +75,11 @@ if sys.platform == 'win32':
             return super().__hash__()
 
         def __getitem__(self, item: int | slice) -> str:
-            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return self.__str__()[item]
 
         def __len__(self) -> int:
-            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return len(self.__str__())
 else:
     class _StrPath(PosixPath):
@@ -76,35 +88,35 @@ else:
         ) -> str:
             # replace exists in both Path and str;
             # in Path it makes filesystem changes, so we use the safer str version
-            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return self.__str__().replace(old, new, count)  # NoQA:  PLC2801
 
         def __getattr__(self, item: str) -> Any:
             if item in _STR_METHODS:
-                warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
                 return getattr(self.__str__(), item)
             msg = f'{_PATH_NAME!r} has no attribute {item!r}'
             raise AttributeError(msg)
 
         def __add__(self, other: str) -> str:
-            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return self.__str__() + other
 
         def __bool__(self) -> bool:
             if not self.__str__():
-                warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
                 return False
             return True
 
         def __contains__(self, item: str) -> bool:
-            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return item in self.__str__()
 
         def __eq__(self, other: object) -> bool:
             if isinstance(other, PurePath):
                 return super().__eq__(other)
             if isinstance(other, str):
-                warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
                 return self.__str__() == other
             return NotImplemented
 
@@ -112,9 +124,9 @@ else:
             return super().__hash__()
 
         def __getitem__(self, item: int | slice) -> str:
-            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return self.__str__()[item]
 
         def __len__(self) -> int:
-            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return len(self.__str__())

sphinx/util/_timestamps.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import time
+
+
+def _format_rfc3339_microseconds(timestamp: int, /) -> str:
+    """Return an RFC 3339 formatted string representing the given timestamp.
+
+    :param timestamp: The timestamp to format, in microseconds.
+    """
+    seconds, fraction = divmod(timestamp, 10**6)
+    return time.strftime('%Y-%m-%d %H:%M:%S', time.gmtime(seconds)) + f'.{fraction // 1_000}'

sphinx/util/cfamily.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import re
 from copy import deepcopy
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 
@@ -12,16 +12,16 @@ from sphinx import addnodes
 from sphinx.util import logging
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
+    from typing import Any, TypeAlias
 
     from docutils.nodes import TextElement
 
     from sphinx.config import Config
 
-logger = logging.getLogger(__name__)
-
-StringifyTransform = Callable[[Any], str]
+    StringifyTransform: TypeAlias = Callable[[Any], str]
 
+logger = logging.getLogger(__name__)
 
 _whitespace_re = re.compile(r'\s+')
 anon_identifier_re = re.compile(r'(@[a-zA-Z0-9_])[a-zA-Z0-9_]*\b')

sphinx/util/console.py

@@ -41,8 +41,9 @@ if TYPE_CHECKING:
 try:
     # check if colorama is installed to support color on Windows
     import colorama
+    COLORAMA_AVAILABLE = True
 except ImportError:
-    colorama = None
+    COLORAMA_AVAILABLE = False
 
 _CSI: Final[str] = re.escape('\x1b[')  # 'ESC [': Control Sequence Introducer
 
@@ -92,7 +93,7 @@ def term_width_line(text: str) -> str:
 def color_terminal() -> bool:
     if 'NO_COLOR' in os.environ:
         return False
-    if sys.platform == 'win32' and colorama is not None:
+    if sys.platform == 'win32' and COLORAMA_AVAILABLE:
         colorama.just_fix_windows_console()
         return True
     if 'FORCE_COLOR' in os.environ:
@@ -108,7 +109,7 @@ def color_terminal() -> bool:
 
 
 def nocolor() -> None:
-    if sys.platform == 'win32' and colorama is not None:
+    if sys.platform == 'win32' and COLORAMA_AVAILABLE:
         colorama.deinit()
     codes.clear()
 

sphinx/util/display.py

@@ -7,9 +7,9 @@ from sphinx.util import logging
 from sphinx.util.console import bold, color_terminal
 
 if False:
-    from collections.abc import Iterable, Iterator
+    from collections.abc import Callable, Iterable, Iterator
     from types import TracebackType
-    from typing import Any, Callable, TypeVar
+    from typing import Any, TypeVar
 
     from typing_extensions import ParamSpec
 
@@ -21,7 +21,7 @@ logger = logging.getLogger(__name__)
 
 
 def display_chunk(chunk: Any) -> str:
-    if isinstance(chunk, (list, tuple)):
+    if isinstance(chunk, list | tuple):
         if len(chunk) == 1:
             return str(chunk[0])
         return f'{chunk[0]} .. {chunk[-1]}'