Sphinx 8.0.2__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/builders/html/_assets.py

@@ -19,7 +19,9 @@ class _CascadingStyleSheet:
 
     def __init__(
         self,
-        filename: str | os.PathLike[str], /, *,
+        filename: str | os.PathLike[str],
+        /,
+        *,
         priority: int = 500,
         rel: str = 'stylesheet',
         type: str = 'text/css',
@@ -31,20 +33,28 @@ class _CascadingStyleSheet:
 
     def __str__(self) -> str:
         attr = ', '.join(f'{k}={v!r}' for k, v in self.attributes.items())
-        return (f'{self.__class__.__name__}({self.filename!r}, '
-                f'priority={self.priority}, '
-                f'{attr})')
+        return (
+            f'{self.__class__.__name__}({self.filename!r}, '
+            f'priority={self.priority}, '
+            f'{attr})'
+        )
 
     def __eq__(self, other: object) -> bool:
         if isinstance(other, str):
-            warnings.warn('The str interface for _CascadingStyleSheet objects is deprecated. '
-                          'Use css.filename instead.', RemovedInSphinx90Warning, stacklevel=2)
+            warnings.warn(
+                'The str interface for _CascadingStyleSheet objects is deprecated. '
+                'Use css.filename instead.',
+                RemovedInSphinx90Warning,
+                stacklevel=2,
+            )
             return self.filename == other
         if not isinstance(other, _CascadingStyleSheet):
             return NotImplemented
-        return (self.filename == other.filename
-                and self.priority == other.priority
-                and self.attributes == other.attributes)
+        return (
+            self.filename == other.filename
+            and self.priority == other.priority
+            and self.attributes == other.attributes
+        )
 
     def __hash__(self) -> int:
         return hash((self.filename, self.priority, *sorted(self.attributes.items())))
@@ -58,13 +68,21 @@ class _CascadingStyleSheet:
         raise AttributeError(msg)
 
     def __getattr__(self, key: str) -> str:
-        warnings.warn('The str interface for _CascadingStyleSheet objects is deprecated. '
-                      'Use css.filename instead.', RemovedInSphinx90Warning, stacklevel=2)
+        warnings.warn(
+            'The str interface for _CascadingStyleSheet objects is deprecated. '
+            'Use css.filename instead.',
+            RemovedInSphinx90Warning,
+            stacklevel=2,
+        )
         return getattr(os.fspath(self.filename), key)
 
     def __getitem__(self, key: int | slice) -> str:
-        warnings.warn('The str interface for _CascadingStyleSheet objects is deprecated. '
-                      'Use css.filename instead.', RemovedInSphinx90Warning, stacklevel=2)
+        warnings.warn(
+            'The str interface for _CascadingStyleSheet objects is deprecated. '
+            'Use css.filename instead.',
+            RemovedInSphinx90Warning,
+            stacklevel=2,
+        )
         return os.fspath(self.filename)[key]
 
 
@@ -75,7 +93,9 @@ class _JavaScript:
 
     def __init__(
         self,
-        filename: str | os.PathLike[str], /, *,
+        filename: str | os.PathLike[str],
+        /,
+        *,
         priority: int = 500,
         **attributes: str,
     ) -> None:
@@ -87,20 +107,28 @@ class _JavaScript:
         attr = ''
         if self.attributes:
             attr = ', ' + ', '.join(f'{k}={v!r}' for k, v in self.attributes.items())
-        return (f'{self.__class__.__name__}({self.filename!r}, '
-                f'priority={self.priority}'
-                f'{attr})')
+        return (
+            f'{self.__class__.__name__}({self.filename!r}, '
+            f'priority={self.priority}'
+            f'{attr})'
+        )
 
     def __eq__(self, other: object) -> bool:
         if isinstance(other, str):
-            warnings.warn('The str interface for _JavaScript objects is deprecated. '
-                          'Use js.filename instead.', RemovedInSphinx90Warning, stacklevel=2)
+            warnings.warn(
+                'The str interface for _JavaScript objects is deprecated. '
+                'Use js.filename instead.',
+                RemovedInSphinx90Warning,
+                stacklevel=2,
+            )
             return self.filename == other
         if not isinstance(other, _JavaScript):
             return NotImplemented
-        return (self.filename == other.filename
-                and self.priority == other.priority
-                and self.attributes == other.attributes)
+        return (
+            self.filename == other.filename
+            and self.priority == other.priority
+            and self.attributes == other.attributes
+        )
 
     def __hash__(self) -> int:
         return hash((self.filename, self.priority, *sorted(self.attributes.items())))
@@ -114,13 +142,21 @@ class _JavaScript:
         raise AttributeError(msg)
 
     def __getattr__(self, key: str) -> str:
-        warnings.warn('The str interface for _JavaScript objects is deprecated. '
-                      'Use js.filename instead.', RemovedInSphinx90Warning, stacklevel=2)
+        warnings.warn(
+            'The str interface for _JavaScript objects is deprecated. '
+            'Use js.filename instead.',
+            RemovedInSphinx90Warning,
+            stacklevel=2,
+        )
         return getattr(os.fspath(self.filename), key)
 
     def __getitem__(self, key: int | slice) -> str:
-        warnings.warn('The str interface for _JavaScript objects is deprecated. '
-                      'Use js.filename instead.', RemovedInSphinx90Warning, stacklevel=2)
+        warnings.warn(
+            'The str interface for _JavaScript objects is deprecated. '
+            'Use js.filename instead.',
+            RemovedInSphinx90Warning,
+            stacklevel=2,
+        )
         return os.fspath(self.filename)[key]
 
 

sphinx/builders/html/_build_info.py

@@ -0,0 +1,76 @@
+"""Record metadata for the build process."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sphinx.locale import __
+from sphinx.util._serialise import stable_hash
+
+if TYPE_CHECKING:
+    from collections.abc import Set
+    from pathlib import Path
+
+    from sphinx.config import Config, _ConfigRebuild
+    from sphinx.util.tags import Tags
+
+
+class BuildInfo:
+    """buildinfo file manipulator.
+
+    HTMLBuilder and its family are storing their own envdata to ``.buildinfo``.
+    This class is a manipulator for the file.
+    """
+
+    @classmethod
+    def load(cls: type[BuildInfo], filename: Path, /) -> BuildInfo:
+        content = filename.read_text(encoding='utf-8')
+        lines = content.splitlines()
+
+        version = lines[0].rstrip()
+        if version != '# Sphinx build info version 1':
+            msg = __('failed to read broken build info file (unknown version)')
+            raise ValueError(msg)
+
+        if not lines[2].startswith('config: '):
+            msg = __('failed to read broken build info file (missing config entry)')
+            raise ValueError(msg)
+        if not lines[3].startswith('tags: '):
+            msg = __('failed to read broken build info file (missing tags entry)')
+            raise ValueError(msg)
+
+        build_info = BuildInfo()
+        build_info.config_hash = lines[2].removeprefix('config: ').strip()
+        build_info.tags_hash = lines[3].removeprefix('tags: ').strip()
+        return build_info
+
+    def __init__(
+        self,
+        config: Config | None = None,
+        tags: Tags | None = None,
+        config_categories: Set[_ConfigRebuild] = frozenset(),
+    ) -> None:
+        self.config_hash = ''
+        self.tags_hash = ''
+
+        if config:
+            values = {c.name: c.value for c in config.filter(config_categories)}
+            self.config_hash = stable_hash(values)
+
+        if tags:
+            self.tags_hash = stable_hash(sorted(tags))
+
+    def __eq__(self, other: BuildInfo) -> bool:  # type: ignore[override]
+        return (
+            self.config_hash == other.config_hash and self.tags_hash == other.tags_hash
+        )
+
+    def dump(self, filename: Path, /) -> None:
+        build_info = (
+            '# Sphinx build info version 1\n'
+            '# This file records the configuration used when building these files. '
+            'When it is not found, a full rebuild will be done.\n'
+            f'config: {self.config_hash}\n'
+            f'tags: {self.tags_hash}\n'
+        )
+        filename.write_text(build_info, encoding='utf-8')

sphinx/builders/html/transforms.py

@@ -36,16 +36,18 @@ class KeyboardTransform(SphinxPostTransform):
     default_priority = 400
     formats = ('html',)
     pattern = re.compile(r'(?<=.)(-|\+|\^|\s+)(?=.)')
-    multiwords_keys = (('caps', 'lock'),
-                       ('page', 'down'),
-                       ('page', 'up'),
-                       ('scroll', 'lock'),
-                       ('num', 'lock'),
-                       ('sys', 'rq'),
-                       ('back', 'space'))
+    multiwords_keys = (
+        ('caps', 'lock'),
+        ('page', 'down'),
+        ('page', 'up'),
+        ('scroll', 'lock'),
+        ('num', 'lock'),
+        ('sys', 'rq'),
+        ('back', 'space'),
+    )
 
     def run(self, **kwargs: Any) -> None:
-        matcher = NodeMatcher(nodes.literal, classes=["kbd"])
+        matcher = NodeMatcher(nodes.literal, classes=['kbd'])
         # this list must be pre-created as during iteration new nodes
         # are added which match the condition in the NodeMatcher.
         for node in list(matcher.findall(self.document)):
@@ -61,7 +63,7 @@ class KeyboardTransform(SphinxPostTransform):
                     parts[:3] = []
                 else:
                     key = parts.pop(0)
-                node += nodes.literal('', key, classes=["kbd"])
+                node += nodes.literal('', key, classes=['kbd'])
 
                 try:
                     # key separator (ex. -, +, ^)