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

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...