Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/jinja2glue.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 import os
-from os import path
+import os.path
+from pathlib import Path
 from pprint import pformat
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from jinja2 import BaseLoader, FileSystemLoader, TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -13,20 +14,26 @@ from jinja2.utils import open_if_exists, pass_context
 
 from sphinx.application import TemplateBridge
 from sphinx.util import logging
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.osutil import _last_modified_time
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator
+    from typing import Any
 
     from jinja2.environment import Environment
 
     from sphinx.builders import Builder
+    from sphinx.environment.adapters.indexentries import (
+        _RealIndexEntries,
+        _RealIndexEntry,
+    )
     from sphinx.theming import Theme
 
 
 def _tobool(val: str) -> bool:
     if isinstance(val, str):
-        return val.lower() in ('true', '1', 'yes', 'on')
+        return val.lower() in {'true', '1', 'yes', 'on'}
     return bool(val)
 
 
@@ -38,8 +45,7 @@ def _toint(val: str) -> int:
 
 
 def _todim(val: int | str) -> str:
-    """
-    Make val a css dimension. In particular the following transformations
+    """Make val a css dimension. In particular the following transformations
     are performed:
 
     - None -> 'initial' (default CSS value)
@@ -55,7 +61,9 @@ def _todim(val: int | str) -> str:
     return val  # type: ignore[return-value]
 
 
-def _slice_index(values: list, slices: int) -> Iterator[list]:
+def _slice_index(
+    values: _RealIndexEntries, slices: int
+) -> Iterator[list[_RealIndexEntry]]:
     seq = values.copy()
     length = 0
     for value in values:
@@ -111,8 +119,7 @@ def warning(context: dict[str, Any], message: str, *args: Any, **kwargs: Any) ->
 
 
 class SphinxFileSystemLoader(FileSystemLoader):
-    """
-    FileSystemLoader subclass that is not so strict about '..'  entries in
+    """FileSystemLoader subclass that is not so strict about '..'  entries in
     template names.
     """
 
@@ -125,14 +132,14 @@ class SphinxFileSystemLoader(FileSystemLoader):
         else:
             legacy_template = None
 
-        for searchpath in self.searchpath:
-            filename = path.join(searchpath, template)
-            f = open_if_exists(filename)
+        for search_path in map(Path, self.searchpath):
+            filename = search_path / template
+            f = open_if_exists(str(filename))
             if f is not None:
                 break
             if legacy_template is not None:
-                filename = path.join(searchpath, legacy_template)
-                f = open_if_exists(filename)
+                filename = search_path / legacy_template
+                f = open_if_exists(str(filename))
                 if f is not None:
                     break
         else:
@@ -149,13 +156,11 @@ class SphinxFileSystemLoader(FileSystemLoader):
             except OSError:
                 return False
 
-        return contents, filename, uptodate
+        return contents, str(filename), uptodate
 
 
 class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
-    """
-    Interfaces the rendering environment of jinja2 for use in Sphinx.
-    """
+    """Interfaces the rendering environment of jinja2 for use in Sphinx."""
 
     # TemplateBridge interface
 
@@ -170,10 +175,10 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
             # the theme's own dir and its bases' dirs
             pathchain = theme.get_theme_dirs()
             # the loader dirs: pathchain + the parent directories for all themes
-            loaderchain = pathchain + [path.join(p, '..') for p in pathchain]
+            loaderchain = pathchain + [p.parent for p in pathchain]
         elif dirs:
-            pathchain = list(dirs)
-            loaderchain = list(dirs)
+            pathchain = list(map(_StrPath, dirs))
+            loaderchain = list(map(_StrPath, dirs))
         else:
             pathchain = []
             loaderchain = []
@@ -182,7 +187,7 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
         self.templatepathlen = len(builder.config.templates_path)
         if builder.config.templates_path:
             cfg_templates_path = [
-                path.join(builder.confdir, tp) for tp in builder.config.templates_path
+                builder.confdir / tp for tp in builder.config.templates_path
             ]
             pathchain[0:0] = cfg_templates_path
             loaderchain[0:0] = cfg_templates_path
@@ -193,7 +198,7 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
         # make the paths into loaders
         self.loaders = [SphinxFileSystemLoader(x) for x in loaderchain]
 
-        use_i18n = builder.app.translator is not None
+        use_i18n = builder._translator is not None
         extensions = ['jinja2.ext.i18n'] if use_i18n else []
         self.environment = SandboxedEnvironment(loader=self, extensions=extensions)
         self.environment.filters['tobool'] = _tobool
@@ -206,9 +211,7 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
         self.environment.globals['idgen'] = idgen
         if use_i18n:
             # ``install_gettext_translations`` is injected by the ``jinja2.ext.i18n`` extension
-            self.environment.install_gettext_translations(  # type: ignore[attr-defined]
-                builder.app.translator
-            )
+            self.environment.install_gettext_translations(builder._translator)  # type: ignore[attr-defined]
 
     def render(self, template: str, context: dict[str, Any]) -> str:  # type: ignore[override]
         return self.environment.get_template(template).render(context)
@@ -224,7 +227,7 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
 
     def _newest_template_mtime_name(self) -> tuple[float, str]:
         return max(
-            (os.stat(os.path.join(root, sfile)).st_mtime_ns / 10**9, sfile)
+            (Path(root, sfile).stat().st_mtime_ns / 10**9, sfile)
             for dirname in self.pathchain
             for root, _dirs, files in os.walk(dirname)
             for sfile in files

sphinx/locale/__init__.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import locale
 import sys
 from gettext import NullTranslations, translation
-from os import path
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -15,8 +15,7 @@ if TYPE_CHECKING:
 
 
 class _TranslationProxy:
-    """
-    The proxy implementation attempts to be as complete as possible, so that
+    """The proxy implementation attempts to be as complete as possible, so that
     the lazy objects should mostly work as expected, for example for sorting.
     """
 
@@ -141,11 +140,11 @@ def init(
     return translator, has_translation
 
 
-_LOCALE_DIR = path.abspath(path.dirname(__file__))
+_LOCALE_DIR = Path(__file__).resolve().parent
 
 
 def init_console(
-    locale_dir: str | None = None,
+    locale_dir: str | os.PathLike[str] | None = None,
     catalog: str = 'sphinx',
 ) -> tuple[NullTranslations, bool]:
     """Initialize locale for console.
@@ -184,7 +183,7 @@ def get_translation(catalog: str, namespace: str = 'general') -> Callable[[str],
     The extension can use this API to translate the messages on the
     extension::
 
-        import os
+        from pathlib import Path
         from sphinx.locale import get_translation
 
         MESSAGE_CATALOG_NAME = 'myextension'  # name of *.pot, *.po and *.mo files
@@ -193,8 +192,8 @@ def get_translation(catalog: str, namespace: str = 'general') -> Callable[[str],
 
 
         def setup(app):
-            package_dir = os.path.abspath(os.path.dirname(__file__))
-            locale_dir = os.path.join(package_dir, 'locales')
+            package_dir = Path(__file__).resolve().parent
+            locale_dir = package_dir / 'locales'
             app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
 
     With this code, sphinx searches a message catalog from
@@ -207,7 +206,7 @@ def get_translation(catalog: str, namespace: str = 'general') -> Callable[[str],
     def gettext(message: str) -> str:
         if not is_translator_registered(catalog, namespace):
             # not initialized yet
-            return _TranslationProxy(catalog, namespace, message)  # type: ignore[return-value]  # NoQA: E501
+            return _TranslationProxy(catalog, namespace, message)  # type: ignore[return-value]
         else:
             translator = get_translator(catalog, namespace)
             return translator.gettext(message)