Sphinx 8.1.3__py3-none-any.whl → 8.2.0rc1__py3-none-any.whl

sphinx/theming.py

@@ -6,13 +6,13 @@ __all__ = ('Theme', 'HTMLThemeFactory')
 
 import configparser
 import contextlib
-import os
 import shutil
 import sys
 import tempfile
+import tomllib
 from importlib.metadata import entry_points
-from os import path
-from typing import TYPE_CHECKING, Any
+from pathlib import Path
+from typing import TYPE_CHECKING
 from zipfile import ZipFile
 
 from sphinx import package_dir
@@ -20,19 +20,12 @@ from sphinx.config import check_confval_types as _config_post_init
 from sphinx.errors import ThemeError
 from sphinx.locale import __
 from sphinx.util import logging
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.osutil import ensuredir
 
-if sys.version_info >= (3, 11):
-    import tomllib
-else:
-    import tomli as tomllib
-
-
 if TYPE_CHECKING:
     from collections.abc import Callable
-    from typing import TypedDict
-
-    from typing_extensions import Required
+    from typing import Any, Required, TypedDict
 
     from sphinx.application import Sphinx
 
@@ -69,8 +62,8 @@ class Theme:
         name: str,
         *,
         configs: dict[str, _ConfigFile],
-        paths: list[str],
-        tmp_dirs: list[str],
+        paths: list[Path],
+        tmp_dirs: list[Path],
     ) -> None:
         self.name = name
         self._dirs = tuple(paths)
@@ -94,11 +87,11 @@ class Theme:
 
         self._options = options
 
-    def get_theme_dirs(self) -> list[str]:
+    def get_theme_dirs(self) -> list[_StrPath]:
         """Return a list of theme directories, beginning with this theme's,
         then the base theme's, then that one's base theme's, etc.
         """
-        return list(self._dirs)
+        return list(map(_StrPath, self._dirs))
 
     def get_config(self, section: str, name: str, default: Any = _NO_DEFAULT) -> Any:
         """Return the value for a theme configuration setting, searching the
@@ -166,17 +159,17 @@ class HTMLThemeFactory:
 
     def _load_builtin_themes(self) -> None:
         """Load built-in themes."""
-        themes = self._find_themes(path.join(package_dir, 'themes'))
+        themes = self._find_themes(package_dir / 'themes')
         for name, theme in themes.items():
-            self._themes[name] = theme
+            self._themes[name] = _StrPath(theme)
 
     def _load_additional_themes(self, theme_paths: list[str]) -> None:
         """Load additional themes placed at specified directories."""
         for theme_path in theme_paths:
-            abs_theme_path = path.abspath(path.join(self._app.confdir, theme_path))
+            abs_theme_path = (self._app.confdir / theme_path).resolve()
             themes = self._find_themes(abs_theme_path)
             for name, theme in themes.items():
-                self._themes[name] = theme
+                self._themes[name] = _StrPath(theme)
 
     def _load_entry_point_themes(self) -> None:
         """Try to load a theme with the specified name.
@@ -198,18 +191,17 @@ class HTMLThemeFactory:
             self._entry_point_themes[entry_point.name] = _load_theme_closure
 
     @staticmethod
-    def _find_themes(theme_path: str) -> dict[str, str]:
+    def _find_themes(theme_path: Path) -> dict[str, Path]:
         """Search themes from specified directory."""
-        themes: dict[str, str] = {}
-        if not path.isdir(theme_path):
+        themes: dict[str, Path] = {}
+        if not theme_path.is_dir():
             return themes
 
-        for entry in os.listdir(theme_path):
-            pathname = path.join(theme_path, entry)
-            if path.isfile(pathname) and entry.lower().endswith('.zip'):
+        for pathname in theme_path.iterdir():
+            entry = pathname.name
+            if pathname.is_file() and pathname.suffix.lower() == '.zip':
                 if _is_archived_theme(pathname):
-                    name = entry[:-4]
-                    themes[name] = pathname
+                    themes[pathname.stem] = pathname
                 else:
                     logger.warning(
                         __(
@@ -219,9 +211,9 @@ class HTMLThemeFactory:
                         entry,
                     )
             else:
-                toml_path = path.join(pathname, _THEME_TOML)
-                conf_path = path.join(pathname, _THEME_CONF)
-                if path.isfile(toml_path) or path.isfile(conf_path):
+                toml_path = pathname / _THEME_TOML
+                conf_path = pathname / _THEME_CONF
+                if toml_path.is_file() or conf_path.is_file():
                     themes[entry] = pathname
 
         return themes
@@ -243,7 +235,7 @@ class HTMLThemeFactory:
         return Theme(name, configs=themes, paths=theme_dirs, tmp_dirs=tmp_dirs)
 
 
-def _is_archived_theme(filename: str, /) -> bool:
+def _is_archived_theme(filename: Path, /) -> bool:
     """Check whether the specified file is an archived theme file or not."""
     try:
         with ZipFile(filename) as f:
@@ -255,13 +247,13 @@ def _is_archived_theme(filename: str, /) -> bool:
 
 def _load_theme_with_ancestors(
     name: str,
-    theme_paths: dict[str, str],
+    theme_paths: dict[str, _StrPath],
     entry_point_themes: dict[str, Callable[[], None]],
     /,
-) -> tuple[dict[str, _ConfigFile], list[str], list[str]]:
+) -> tuple[dict[str, _ConfigFile], list[Path], list[Path]]:
     themes: dict[str, _ConfigFile] = {}
-    theme_dirs: list[str] = []
-    tmp_dirs: list[str] = []
+    theme_dirs: list[Path] = []
+    tmp_dirs: list[Path] = []
 
     # having 10+ theme ancestors is ludicrous
     for _ in range(10):
@@ -294,23 +286,23 @@ def _load_theme_with_ancestors(
 
 
 def _load_theme(
-    name: str, theme_path: str, /
-) -> tuple[str, str, str | None, _ConfigFile]:
-    if path.isdir(theme_path):
+    name: str, theme_path: Path, /
+) -> tuple[str, Path, Path | None, _ConfigFile]:
+    if theme_path.is_dir():
         # already a directory, do nothing
         tmp_dir = None
         theme_dir = theme_path
     else:
         # extract the theme to a temp directory
-        tmp_dir = tempfile.mkdtemp('sxt')
-        theme_dir = path.join(tmp_dir, name)
+        tmp_dir = Path(tempfile.mkdtemp('sxt'))
+        theme_dir = tmp_dir / name
         _extract_zip(theme_path, theme_dir)
 
-    if path.isfile(toml_path := path.join(theme_dir, _THEME_TOML)):
+    if (toml_path := theme_dir / _THEME_TOML).is_file():
         _cfg_table = _load_theme_toml(toml_path)
         inherit = _validate_theme_toml(_cfg_table, name)
         config = _convert_theme_toml(_cfg_table)
-    elif path.isfile(conf_path := path.join(theme_dir, _THEME_CONF)):
+    elif (conf_path := theme_dir / _THEME_CONF).is_file():
         _cfg_parser = _load_theme_conf(conf_path)
         inherit = _validate_theme_conf(_cfg_parser, name)
         config = _convert_theme_conf(_cfg_parser)
@@ -320,7 +312,7 @@ def _load_theme(
     return inherit, theme_dir, tmp_dir, config
 
 
-def _extract_zip(filename: str, target_dir: str, /) -> None:
+def _extract_zip(filename: Path, target_dir: Path, /) -> None:
     """Extract zip file to target directory."""
     ensuredir(target_dir)
 
@@ -328,16 +320,13 @@ def _extract_zip(filename: str, target_dir: str, /) -> None:
         for name in archive.namelist():
             if name.endswith('/'):
                 continue
-            entry = path.join(target_dir, name)
-            ensuredir(path.dirname(entry))
-            with open(path.join(entry), 'wb') as fp:
-                fp.write(archive.read(name))
+            entry = target_dir / name
+            ensuredir(entry.parent)
+            entry.write_bytes(archive.read(name))
 
 
-def _load_theme_toml(config_file_path: str, /) -> _ThemeToml:
-    with open(config_file_path, encoding='utf-8') as f:
-        config_text = f.read()
-    c = tomllib.loads(config_text)
+def _load_theme_toml(config_file_path: Path, /) -> _ThemeToml:
+    c = tomllib.loads(config_file_path.read_text(encoding='utf-8'))
     return {s: c[s] for s in ('theme', 'options') if s in c}  # type: ignore[return-value]
 
 
@@ -388,7 +377,7 @@ def _convert_theme_toml(cfg: _ThemeToml, /) -> _ConfigFile:
     )
 
 
-def _load_theme_conf(config_file_path: str, /) -> configparser.RawConfigParser:
+def _load_theme_conf(config_file_path: Path, /) -> configparser.RawConfigParser:
     c = configparser.RawConfigParser()
     c.read(config_file_path, encoding='utf-8')
     return c
@@ -494,9 +483,9 @@ def _migrate_conf_to_toml(argv: list[str]) -> int:
     if len(argv) != 1:
         print('Usage: python -m sphinx.theming conf_to_toml <theme path>')  # NoQA: T201
         raise SystemExit(1)
-    theme_dir = path.realpath(argv[0])
-    conf_path = path.join(theme_dir, _THEME_CONF)
-    if not path.isdir(theme_dir) or not path.isfile(conf_path):
+    theme_dir = Path(argv[0]).resolve()
+    conf_path = theme_dir / _THEME_CONF
+    if not theme_dir.is_dir() or not conf_path.is_file():
         print(  # NoQA: T201
             f'{theme_dir!r} must be a path to a theme directory containing a "theme.conf" file'
         )
@@ -516,7 +505,7 @@ def _migrate_conf_to_toml(argv: list[str]) -> int:
     ]
 
     stylesheet = _cfg_parser.get('theme', 'stylesheet', fallback=...)
-    if stylesheet == '':
+    if not stylesheet:
         toml_lines.append('stylesheets = []')
     elif stylesheet is not ...:
         toml_lines.append('stylesheets = [')
@@ -524,7 +513,7 @@ def _migrate_conf_to_toml(argv: list[str]) -> int:
         toml_lines.append(']')
 
     sidebar = _cfg_parser.get('theme', 'sidebars', fallback=...)
-    if sidebar == '':
+    if not sidebar:
         toml_lines.append('sidebars = []')
     elif sidebar is not ...:
         toml_lines.append('sidebars = [')
@@ -550,9 +539,8 @@ def _migrate_conf_to_toml(argv: list[str]) -> int:
             if (d := default.replace('"', r'\"')) or True
         ]
 
-    toml_path = path.join(theme_dir, _THEME_TOML)
-    with open(toml_path, 'w', encoding='utf-8') as f:
-        f.write('\n'.join(toml_lines) + '\n')
+    toml_path = theme_dir / _THEME_TOML
+    toml_path.write_text('\n'.join(toml_lines) + '\n', encoding='utf-8')
     print(f'Written converted settings to {toml_path!r}')  # NoQA: T201
     return 0
 

sphinx/transforms/__init__.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import re
 import unicodedata
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
 from docutils.transforms import Transform, Transformer
@@ -23,7 +23,7 @@ from sphinx.util.nodes import apply_source_workaround, is_smartquotable
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
-    from typing import Literal, TypeAlias
+    from typing import Any, Literal, TypeAlias
 
     from docutils.nodes import Node, Text
     from typing_extensions import TypeIs
@@ -76,9 +76,7 @@ class SphinxTransform(Transform):
 
 
 class SphinxTransformer(Transformer):
-    """
-    A transformer for Sphinx.
-    """
+    """A transformer for Sphinx."""
 
     document: nodes.document
     env: BuildEnvironment | None = None
@@ -106,9 +104,7 @@ class SphinxTransformer(Transformer):
 
 
 class DefaultSubstitutions(SphinxTransform):
-    """
-    Replace some substitutions if they aren't defined in the document.
-    """
+    """Replace some substitutions if they aren't defined in the document."""
 
     # run before the default Substitutions
     default_priority = 210
@@ -150,8 +146,7 @@ def _calculate_translation_progress(document: nodes.document) -> str:
 
 
 class MoveModuleTargets(SphinxTransform):
-    """
-    Move module targets that are the first thing in a section to the section
+    """Move module targets that are the first thing in a section to the section
     title.
 
     XXX Python specific
@@ -176,9 +171,7 @@ class MoveModuleTargets(SphinxTransform):
 
 
 class HandleCodeBlocks(SphinxTransform):
-    """
-    Several code block related transformations.
-    """
+    """Several code block related transformations."""
 
     default_priority = 210
 
@@ -200,9 +193,7 @@ class HandleCodeBlocks(SphinxTransform):
 
 
 class AutoNumbering(SphinxTransform):
-    """
-    Register IDs of tables, figures and literal_blocks to assign numbers.
-    """
+    """Register IDs of tables, figures and literal_blocks to assign numbers."""
 
     default_priority = 210
 
@@ -219,9 +210,7 @@ class AutoNumbering(SphinxTransform):
 
 
 class SortIds(SphinxTransform):
-    """
-    Sort section IDs so that the "id[0-9]+" one comes last.
-    """
+    """Sort section IDs so that the "id[0-9]+" one comes last."""
 
     default_priority = 261
 
@@ -241,9 +230,7 @@ TRANSLATABLE_NODES = {
 
 
 class ApplySourceWorkaround(SphinxTransform):
-    """
-    Update source and rawsource attributes
-    """
+    """Update source and rawsource attributes"""
 
     default_priority = 10
 
@@ -254,9 +241,7 @@ class ApplySourceWorkaround(SphinxTransform):
 
 
 class AutoIndexUpgrader(SphinxTransform):
-    """
-    Detect old style (4 column based indices) and automatically upgrade to new style.
-    """
+    """Detect old style (4 column based indices) and automatically upgrade to new style."""
 
     default_priority = 210
 
@@ -277,9 +262,7 @@ class AutoIndexUpgrader(SphinxTransform):
 
 
 class ExtraTranslatableNodes(SphinxTransform):
-    """
-    Make nodes translatable
-    """
+    """Make nodes translatable"""
 
     default_priority = 10
 
@@ -297,9 +280,7 @@ class ExtraTranslatableNodes(SphinxTransform):
 
 
 class UnreferencedFootnotesDetector(SphinxTransform):
-    """
-    Detect unreferenced footnotes and emit warnings
-    """
+    """Detect unreferenced footnotes and emit warnings"""
 
     default_priority = Footnotes.default_priority + 2
 
@@ -361,8 +342,7 @@ class FilterSystemMessages(SphinxTransform):
 
 
 class SphinxContentsFilter(ContentsFilter):
-    """
-    Used with BuildEnvironment.add_toc_from() to discard cross-file links
+    """Used with BuildEnvironment.add_toc_from() to discard cross-file links
     within table-of-contents link nodes.
     """
 
@@ -373,8 +353,7 @@ class SphinxContentsFilter(ContentsFilter):
 
 
 class SphinxSmartQuotes(SmartQuotes, SphinxTransform):
-    """
-    Customized SmartQuotes to avoid transform for some extra node types.
+    """Customized SmartQuotes to avoid transform for some extra node types.
 
     refs: sphinx.parsers.RSTParser
     """
@@ -430,7 +409,7 @@ class DoctreeReadEvent(SphinxTransform):
     default_priority = 880
 
     def apply(self, **kwargs: Any) -> None:
-        self.app.emit('doctree-read', self.document)
+        self.app.events.emit('doctree-read', self.document)
 
 
 class GlossarySorter(SphinxTransform):
@@ -443,11 +422,11 @@ class GlossarySorter(SphinxTransform):
     def apply(self, **kwargs: Any) -> None:
         for glossary in self.document.findall(addnodes.glossary):
             if glossary['sorted']:
-                definition_list = cast(nodes.definition_list, glossary[0])
+                definition_list = cast('nodes.definition_list', glossary[0])
                 definition_list[:] = sorted(
                     definition_list,
                     key=lambda item: unicodedata.normalize(
-                        'NFD', cast(nodes.term, item)[0].astext().lower()
+                        'NFD', cast('nodes.term', item)[0].astext().lower()
                     ),
                 )
 

sphinx/transforms/compact_bullet_list.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
 
@@ -10,6 +10,8 @@ from sphinx import addnodes
 from sphinx.transforms import SphinxTransform
 
 if TYPE_CHECKING:
+    from typing import Any
+
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
@@ -75,8 +77,8 @@ class RefOnlyBulletListTransform(SphinxTransform):
         for node in self.document.findall(nodes.bullet_list):
             if check_refonly_list(node):
                 for item in node.findall(nodes.list_item):
-                    para = cast(nodes.paragraph, item[0])
-                    ref = cast(nodes.reference, para[0])
+                    para = cast('nodes.paragraph', item[0])
+                    ref = cast('nodes.reference', para[0])
                     compact_para = addnodes.compact_paragraph()
                     compact_para += ref
                     item.replace(para, compact_para)

sphinx/transforms/i18n.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import contextlib
-from os import path
 from re import DOTALL, match
 from textwrap import indent
 from typing import TYPE_CHECKING, Any, TypeVar
@@ -101,9 +100,7 @@ def parse_noqa(source: str) -> tuple[str, bool]:
 
 
 class PreserveTranslatableMessages(SphinxTransform):
-    """
-    Preserve original translatable messages before translation
-    """
+    """Preserve original translatable messages before translation"""
 
     default_priority = 10  # this MUST be invoked before Locale transform
 
@@ -381,9 +378,7 @@ class _NodeUpdater:
 
 
 class Locale(SphinxTransform):
-    """
-    Replace translatable nodes with their translated doctree.
-    """
+    """Replace translatable nodes with their translated doctree."""
 
     default_priority = 20
 
@@ -394,10 +389,8 @@ class Locale(SphinxTransform):
         textdomain = docname_to_domain(self.env.docname, self.config.gettext_compact)
 
         # fetch translations
-        dirs = [
-            path.join(self.env.srcdir, directory)
-            for directory in self.config.locale_dirs
-        ]
+        srcdir = self.env.srcdir
+        dirs = [srcdir / directory for directory in self.config.locale_dirs]
         catalog, has_catalog = init_locale(dirs, self.config.language, textdomain)
         if not has_catalog:
             return
@@ -420,7 +413,7 @@ class Locale(SphinxTransform):
             if not isinstance(node, LITERAL_TYPE_NODES):
                 msgstr, _ = parse_noqa(msgstr)
 
-            if msgstr.strip() == '':
+            if not msgstr.strip():
                 # as-of-yet untranslated
                 node['translated'] = False
                 continue
@@ -612,9 +605,7 @@ class Locale(SphinxTransform):
 
 
 class TranslationProgressTotaliser(SphinxTransform):
-    """
-    Calculate the number of translated and untranslated nodes.
-    """
+    """Calculate the number of translated and untranslated nodes."""
 
     default_priority = 25  # MUST happen after Locale
 
@@ -637,9 +628,7 @@ class TranslationProgressTotaliser(SphinxTransform):
 
 
 class AddTranslationClasses(SphinxTransform):
-    """
-    Add ``translated`` or ``untranslated`` classes to indicate translation status.
-    """
+    """Add ``translated`` or ``untranslated`` classes to indicate translation status."""
 
     default_priority = 950
 
@@ -677,9 +666,7 @@ class AddTranslationClasses(SphinxTransform):
 
 
 class RemoveTranslatableInline(SphinxTransform):
-    """
-    Remove inline nodes used for translation as placeholders.
-    """
+    """Remove inline nodes used for translation as placeholders."""
 
     default_priority = 999