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

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/_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]}'

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,14 +4,17 @@ 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
 
@@ -34,7 +37,8 @@ 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,
-                    *, __overwrite_warning__: bool = True) -> None:
+                    *,
+                    force: bool = False) -> None:
     """Copy an asset file to destination.
 
     On copying, it expands the template variables if context argument is given and
@@ -44,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
@@ -64,45 +69,42 @@ def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLi
         rendered_template = renderer.render_string(template_content, context)
 
         if (
-            __overwrite_warning__
+            not force
             and os.path.exists(destination)
             and template_content != rendered_template
         ):
-            # Consider raising an error in Sphinx 8.
-            # Certainly make overwriting user content opt-in.
-            # xref: RemovedInSphinx80Warning
-            # xref: https://github.com/sphinx-doc/sphinx/issues/12096
-            msg = ('Copying the rendered template %s to %s will overwrite data, '
-                   'as a file already exists at the destination path '
-                   'and the content does not match.')
-            # See https://github.com/sphinx-doc/sphinx/pull/12627#issuecomment-2241144330
-            # for the rationale for logger.info().
-            logger.info(msg, os.fsdecode(source), os.fsdecode(destination),
-                        type='misc', subtype='copy_overwrite')
+            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, __overwrite_warning__=__overwrite_warning__)
+        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,
-               *, __overwrite_warning__: bool = True) -> 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
@@ -113,8 +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,
-                        __overwrite_warning__=__overwrite_warning__)
+        copy_asset_file(source, destination,
+                        context=context,
+                        renderer=renderer,
+                        force=force)
         return
 
     for root, dirs, files in os.walk(source, followlinks=True):
@@ -130,8 +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,
-                                    __overwrite_warning__=__overwrite_warning__)
+                                    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