Sphinx 8.1.3__py3-none-any.whl → 8.2.0rc1__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)

sphinx/parsers.py

@@ -6,7 +6,6 @@ from typing import TYPE_CHECKING
 
 import docutils.parsers
 import docutils.parsers.rst
-from docutils import nodes
 from docutils.parsers.rst import states
 from docutils.statemachine import StringList
 from docutils.transforms.universal import SmartQuotes
@@ -14,6 +13,7 @@ from docutils.transforms.universal import SmartQuotes
 from sphinx.util.rst import append_epilog, prepend_prolog
 
 if TYPE_CHECKING:
+    from docutils import nodes
     from docutils.transforms import Transform
 
     from sphinx.application import Sphinx
@@ -23,10 +23,12 @@ if TYPE_CHECKING:
 
 
 class Parser(docutils.parsers.Parser):
-    """
-    A base class of source parsers.  The additional parsers should inherit this class instead
-    of ``docutils.parsers.Parser``.  Compared with ``docutils.parsers.Parser``, this class
-    improves accessibility to Sphinx APIs.
+    """A base class of source parsers.
+
+    The additional parsers should inherit this class
+    instead of ``docutils.parsers.Parser``.
+    Compared with ``docutils.parsers.Parser``,
+    this class improves accessibility to Sphinx APIs.
 
     The subclasses can access sphinx core runtime objects (app, config and env).
     """
@@ -51,8 +53,7 @@ class RSTParser(docutils.parsers.rst.Parser, Parser):
     """A reST parser for Sphinx."""
 
     def get_transforms(self) -> list[type[Transform]]:
-        """
-        Sphinx's reST parser replaces a transform class for smart-quotes by its own
+        """Sphinx's reST parser replaces a transform class for smart-quotes by its own
 
         refs: sphinx.io.SphinxStandaloneReader
         """

sphinx/project.py

@@ -96,10 +96,10 @@ class Project:
 
         *filename* should be absolute or relative to the source directory.
         """
+        path = Path(filename)
         try:
-            return self._path_to_docname[filename]  # type: ignore[index]
+            return self._path_to_docname[path]
         except KeyError:
-            path = Path(filename)
             if path.is_absolute():
                 with contextlib.suppress(ValueError):
                     path = path.relative_to(self.srcdir)

sphinx/pycode/__init__.py

@@ -4,14 +4,16 @@ from __future__ import annotations
 
 import tokenize
 from importlib import import_module
-from os import path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from sphinx.errors import PycodeError
 from sphinx.pycode.parser import Parser
+from sphinx.util._pathlib import _StrPath
 
 if TYPE_CHECKING:
+    import os
     from inspect import Signature
+    from typing import Any, Literal
 
 
 class ModuleAnalyzer:
@@ -23,10 +25,10 @@ class ModuleAnalyzer:
     tags: dict[str, tuple[str, int, int]]
 
     # cache for analyzer objects -- caches both by module and file name
-    cache: dict[tuple[str, str], Any] = {}
+    cache: dict[tuple[Literal['file', 'module'], str | _StrPath], Any] = {}
 
     @staticmethod
-    def get_module_source(modname: str) -> tuple[str | None, str | None]:
+    def get_module_source(modname: str) -> tuple[_StrPath | None, str | None]:
         """Try to find the source code for a module.
 
         Returns ('filename', 'source'). One of it can be None if
@@ -37,14 +39,15 @@ class ModuleAnalyzer:
         except Exception as err:
             raise PycodeError('error importing %r' % modname, err) from err
         loader = getattr(mod, '__loader__', None)
-        filename = getattr(mod, '__file__', None)
+        filename: str | None = getattr(mod, '__file__', None)
         if loader and getattr(loader, 'get_source', None):
             # prefer Native loader, as it respects #coding directive
             try:
                 source = loader.get_source(modname)
                 if source:
+                    mod_path = None if filename is None else _StrPath(filename)
                     # no exception and not None - it must be module source
-                    return filename, source
+                    return mod_path, source
             except ImportError:
                 pass  # Try other "source-mining" methods
         if filename is None and loader and getattr(loader, 'get_filename', None):
@@ -58,31 +61,36 @@ class ModuleAnalyzer:
         if filename is None:
             # all methods for getting filename failed, so raise...
             raise PycodeError('no source found for module %r' % modname)
-        filename = path.normpath(path.abspath(filename))
-        if filename.lower().endswith(('.pyo', '.pyc')):
-            filename = filename[:-1]
-            if not path.isfile(filename) and path.isfile(filename + 'w'):
-                filename += 'w'
-        elif not filename.lower().endswith(('.py', '.pyw')):
-            raise PycodeError('source is not a .py file: %r' % filename)
-
-        if not path.isfile(filename):
-            raise PycodeError('source file is not present: %r' % filename)
-        return filename, None
+        mod_path = _StrPath(filename).resolve()
+        if mod_path.suffix in {'.pyo', '.pyc'}:
+            mod_path_pyw = mod_path.with_suffix('.pyw')
+            if not mod_path.is_file() and mod_path_pyw.is_file():
+                mod_path = mod_path_pyw
+            else:
+                mod_path = mod_path.with_suffix('.py')
+        elif mod_path.suffix not in {'.py', '.pyw'}:
+            msg = f'source is not a .py file: {mod_path!r}'
+            raise PycodeError(msg)
+
+        if not mod_path.is_file():
+            msg = f'source file is not present: {mod_path!r}'
+            raise PycodeError(msg)
+        return mod_path, None
 
     @classmethod
     def for_string(
         cls: type[ModuleAnalyzer],
         string: str,
         modname: str,
-        srcname: str = '<string>',
+        srcname: str | os.PathLike[str] = '<string>',
     ) -> ModuleAnalyzer:
         return cls(string, modname, srcname)
 
     @classmethod
     def for_file(
-        cls: type[ModuleAnalyzer], filename: str, modname: str
+        cls: type[ModuleAnalyzer], filename: str | os.PathLike[str], modname: str
     ) -> ModuleAnalyzer:
+        filename = _StrPath(filename)
         if ('file', filename) in cls.cache:
             return cls.cache['file', filename]
         try:
@@ -114,9 +122,11 @@ class ModuleAnalyzer:
         cls.cache['module', modname] = obj
         return obj
 
-    def __init__(self, source: str, modname: str, srcname: str) -> None:
+    def __init__(
+        self, source: str, modname: str, srcname: str | os.PathLike[str]
+    ) -> None:
         self.modname = modname  # name of the module
-        self.srcname = srcname  # name of the source file
+        self.srcname = str(srcname)  # name of the source file
 
         # cache the source code as well
         self.code = source

sphinx/pycode/ast.py

@@ -3,7 +3,10 @@
 from __future__ import annotations
 
 import ast
-from typing import NoReturn, overload
+from typing import TYPE_CHECKING, overload
+
+if TYPE_CHECKING:
+    from typing import NoReturn
 
 OPERATORS: dict[type[ast.AST], str] = {
     ast.Add: '+',
@@ -29,11 +32,11 @@ OPERATORS: dict[type[ast.AST], str] = {
 
 
 @overload
-def unparse(node: None, code: str = '') -> None: ...  # NoQA: E704
+def unparse(node: None, code: str = '') -> None: ...
 
 
 @overload
-def unparse(node: ast.AST, code: str = '') -> str: ...  # NoQA: E704
+def unparse(node: ast.AST, code: str = '') -> str: ...
 
 
 def unparse(node: ast.AST | None, code: str = '') -> str | None:

sphinx/pycode/parser.py

@@ -10,13 +10,16 @@ import itertools
 import operator
 import re
 import tokenize
-from inspect import Signature
 from token import DEDENT, INDENT, NAME, NEWLINE, NUMBER, OP, STRING
 from tokenize import COMMENT, NL
-from typing import Any
+from typing import TYPE_CHECKING
 
 from sphinx.pycode.ast import unparse as ast_unparse
 
+if TYPE_CHECKING:
+    from inspect import Signature
+    from typing import Any
+
 comment_re = re.compile('^\\s*#: ?(.*)\r?\n?$')
 indent_re = re.compile('^\\s*$')
 emptyline_re = re.compile('^\\s*(#.*)?$')
@@ -40,21 +43,21 @@ def get_lvar_names(node: ast.AST, self: ast.arg | None = None) -> list[str]:
     This raises `TypeError` if the assignment does not create new variable::
 
         ary[0] = 'foo'
-        dic["bar"] = 'baz'
+        dic['bar'] = 'baz'
         # => TypeError
     """
     if self:
         self_id = self.arg
 
     node_name = node.__class__.__name__
-    if node_name in ('Constant', 'Index', 'Slice', 'Subscript'):
+    if node_name in {'Constant', 'Index', 'Slice', 'Subscript'}:
         raise TypeError('%r does not create new variable' % node)
     if node_name == 'Name':
         if self is None or node.id == self_id:  # type: ignore[attr-defined]
             return [node.id]  # type: ignore[attr-defined]
         else:
             raise TypeError('The assignment %r is not instance variable' % node)
-    elif node_name in ('Tuple', 'List'):
+    elif node_name in {'Tuple', 'List'}:
         members = []
         for elt in node.elts:  # type: ignore[attr-defined]
             with contextlib.suppress(TypeError):
@@ -111,7 +114,7 @@ class Token:
         self.end = end
         self.source = source
 
-    def __eq__(self, other: Any) -> bool:
+    def __eq__(self, other: object) -> bool:
         if isinstance(other, int):
             return self.kind == other
         elif isinstance(other, str):
@@ -123,6 +126,9 @@ class Token:
         else:
             raise ValueError('Unknown value: %r' % other)
 
+    def __hash__(self) -> int:
+        return hash((self.kind, self.value, self.start, self.end, self.source))
+
     def match(self, *conditions: Any) -> bool:
         return any(self == candidate for candidate in conditions)
 
@@ -280,13 +286,13 @@ class VariableCommentPicker(ast.NodeVisitor):
         qualname = self.get_qualname_for(name)
         if qualname:
             basename = '.'.join(qualname[:-1])
-            self.comments[(basename, name)] = comment
+            self.comments[basename, name] = comment
 
     def add_variable_annotation(self, name: str, annotation: ast.AST) -> None:
         qualname = self.get_qualname_for(name)
         if qualname:
             basename = '.'.join(qualname[:-1])
-            self.annotations[(basename, name)] = ast_unparse(annotation)
+            self.annotations[basename, name] = ast_unparse(annotation)
 
     def is_final(self, decorators: list[ast.expr]) -> bool:
         final = []

sphinx/pygments_styles.py

@@ -1,5 +1,7 @@
 """Sphinx theme specific highlighting styles."""
 
+from __future__ import annotations
+
 from pygments.style import Style
 from pygments.styles.friendly import FriendlyStyle
 from pygments.token import (
@@ -20,8 +22,7 @@ class NoneStyle(Style):
 
 
 class SphinxStyle(Style):
-    """
-    Like friendly, but a bit darker to enhance contrast on the green
+    """Like friendly, but a bit darker to enhance contrast on the green
     background.
     """
 
@@ -37,9 +38,7 @@ class SphinxStyle(Style):
 
 
 class PyramidStyle(Style):
-    """
-    Pylons/pyramid pygments style based on friendly style, by Blaise Laflamme.
-    """
+    """Pylons/pyramid pygments style based on friendly style, by Blaise Laflamme."""
 
     # work in progress...