Sphinx 7.4.6__py3-none-any.whl → 8.0.0rc1__py3-none-any.whl

sphinx/domains/c/__init__.py

@@ -19,7 +19,7 @@ from sphinx.domains.c._ids import _macroKeywords, _max_id
 from sphinx.domains.c._parser import DefinitionParser
 from sphinx.domains.c._symbol import Symbol, _DuplicateSymbolError
 from sphinx.locale import _, __
-from sphinx.roles import SphinxRole, XRefRole
+from sphinx.roles import XRefRole
 from sphinx.transforms import SphinxTransform
 from sphinx.transforms.post_transforms import ReferencesResolver
 from sphinx.util import logging
@@ -29,7 +29,7 @@ from sphinx.util.cfamily import (
     anon_identifier_re,
 )
 from sphinx.util.docfields import Field, GroupedField, TypedField
-from sphinx.util.docutils import SphinxDirective
+from sphinx.util.docutils import SphinxDirective, SphinxRole
 from sphinx.util.nodes import make_refnode
 
 if TYPE_CHECKING:

sphinx/domains/c/_ast.py

@@ -12,19 +12,20 @@ from sphinx.util.cfamily import (
     ASTAttributeList,
     ASTBaseBase,
     ASTBaseParenExprList,
-    StringifyTransform,
     UnsupportedMultiCharacterCharLiteral,
     verify_description_mode,
 )
 
 if TYPE_CHECKING:
+    from typing import TypeAlias
 
     from docutils.nodes import Element, Node, TextElement
 
     from sphinx.domains.c._symbol import Symbol
     from sphinx.environment import BuildEnvironment
+    from sphinx.util.cfamily import StringifyTransform
 
-DeclarationType = Union[
+DeclarationType: TypeAlias = Union[  # NoQA: UP007
     "ASTStruct", "ASTUnion", "ASTEnum", "ASTEnumerator",
     "ASTType", "ASTTypeWithInit", "ASTMacro",
 ]

sphinx/domains/c/_parser.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 from sphinx.domains.c._ast import (
     ASTAlignofExpr,
@@ -53,7 +53,6 @@ from sphinx.domains.c._ast import (
     ASTTypeWithInit,
     ASTUnaryOpExpr,
     ASTUnion,
-    DeclarationType,
 )
 from sphinx.domains.c._ids import (
     _expression_assignment_ops,
@@ -80,7 +79,9 @@ from sphinx.util.cfamily import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
+
+    from sphinx.domains.c._ast import DeclarationType
 
 
 class DefinitionParser(BaseParser):

sphinx/domains/cpp/__init__.py

@@ -23,7 +23,7 @@ from sphinx.domains.cpp._parser import DefinitionParser
 from sphinx.domains.cpp._symbol import Symbol, _DuplicateSymbolError
 from sphinx.errors import NoUri
 from sphinx.locale import _, __
-from sphinx.roles import SphinxRole, XRefRole
+from sphinx.roles import XRefRole
 from sphinx.transforms import SphinxTransform
 from sphinx.transforms.post_transforms import ReferencesResolver
 from sphinx.util import logging
@@ -33,7 +33,7 @@ from sphinx.util.cfamily import (
     anon_identifier_re,
 )
 from sphinx.util.docfields import Field, GroupedField
-from sphinx.util.docutils import SphinxDirective
+from sphinx.util.docutils import SphinxDirective, SphinxRole
 from sphinx.util.nodes import make_refnode
 
 if TYPE_CHECKING:

sphinx/domains/cpp/_ast.py

@@ -24,18 +24,17 @@ from sphinx.util.cfamily import (
     ASTBaseBase,
     ASTBaseParenExprList,
     NoOldIdError,
-    StringifyTransform,
     UnsupportedMultiCharacterCharLiteral,
     verify_description_mode,
 )
 
 if TYPE_CHECKING:
-
     from docutils.nodes import Element, TextElement
 
     from sphinx.addnodes import desc_signature
     from sphinx.domains.cpp._symbol import Symbol
     from sphinx.environment import BuildEnvironment
+    from sphinx.util.cfamily import StringifyTransform
 
 
 class ASTBase(ASTBaseBase):

sphinx/domains/cpp/_parser.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 from sphinx.domains.cpp._ast import (
     ASTAlignofExpr,
@@ -127,7 +127,7 @@ from sphinx.util.cfamily import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
 logger = logging.getLogger(__name__)
 

sphinx/domains/cpp/_symbol.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Callable, NoReturn
+from typing import TYPE_CHECKING, Any, NoReturn
 
 from sphinx.domains.cpp._ast import (
     ASTDeclaration,
@@ -17,7 +17,7 @@ from sphinx.locale import __
 from sphinx.util import logging
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
 
     from sphinx.environment import BuildEnvironment
 

sphinx/domains/javascript.py

@@ -309,7 +309,7 @@ class JSModule(SphinxDirective):
     def run(self) -> list[Node]:
         mod_name = self.arguments[0].strip()
         self.env.ref_context['js:module'] = mod_name
-        no_index = 'no-index' in self.options or 'noindex' in self.options
+        no_index = 'no-index' in self.options
 
         content_nodes = self.parse_content_to_nodes(allow_section_headings=True)
 

sphinx/domains/math.py

@@ -74,7 +74,7 @@ class MathDomain(Domain):
     def process_doc(self, env: BuildEnvironment, docname: str,
                     document: nodes.document) -> None:
         def math_node(node: Node) -> bool:
-            return isinstance(node, (nodes.math, nodes.math_block))
+            return isinstance(node, nodes.math | nodes.math_block)
 
         self.data['has_equations'][docname] = any(document.findall(math_node))
 

sphinx/domains/python/__init__.py

@@ -452,7 +452,7 @@ class PyModule(SphinxDirective):
         domain = cast(PythonDomain, self.env.get_domain('py'))
 
         modname = self.arguments[0].strip()
-        no_index = 'no-index' in self.options or 'noindex' in self.options
+        no_index = 'no-index' in self.options
         self.env.ref_context['py:module'] = modname
 
         content_nodes = self.parse_content_to_nodes(allow_section_headings=True)

sphinx/domains/python/_annotations.py

@@ -161,7 +161,29 @@ def _parse_annotation(annotation: str, env: BuildEnvironment) -> list[Node]:
                           addnodes.desc_sig_punctuation('', ')')]
 
             return result
-        raise SyntaxError  # unsupported syntax
+        if isinstance(node, ast.Call):
+            # Call nodes can be used in Annotated type metadata,
+            # for example Annotated[str, ArbitraryTypeValidator(str, len=10)]
+            args = []
+            for arg in node.args:
+                args += unparse(arg)
+                args.append(addnodes.desc_sig_punctuation('', ','))
+                args.append(addnodes.desc_sig_space())
+            for kwd in node.keywords:
+                args.append(addnodes.desc_sig_name(kwd.arg, kwd.arg))  # type: ignore[arg-type]
+                args.append(addnodes.desc_sig_operator('', '='))
+                args += unparse(kwd.value)
+                args.append(addnodes.desc_sig_punctuation('', ','))
+                args.append(addnodes.desc_sig_space())
+            result = [
+                *unparse(node.func),
+                addnodes.desc_sig_punctuation('', '('),
+                *args[:-2],  # skip the final comma and space
+                addnodes.desc_sig_punctuation('', ')'),
+            ]
+            return result
+        msg = f'unsupported syntax: {node}'
+        raise SyntaxError(msg)  # unsupported syntax
 
     def _unparse_pep_604_annotation(node: ast.Subscript) -> list[Node]:
         subscript = node.slice

sphinx/domains/python/_object.py

@@ -25,7 +25,6 @@ from sphinx.util.nodes import (
 )
 
 if TYPE_CHECKING:
-
     from docutils.nodes import Node
     from docutils.parsers.rst.states import Inliner
 

sphinx/domains/std/__init__.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import re
 from copy import copy
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Final, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Final, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node, system_message
@@ -23,7 +23,7 @@ from sphinx.util.nodes import clean_astext, make_id, make_refnode
 from sphinx.util.parsing import nested_parse_to_nodes
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator
+    from collections.abc import Callable, Iterable, Iterator
 
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
@@ -402,7 +402,7 @@ class Glossary(SphinxDirective):
         in_comment = False
         was_empty = True
         messages: list[Node] = []
-        for line, (source, lineno) in zip(self.content, self.content.items):
+        for line, (source, lineno) in zip(self.content, self.content.items, strict=True):
             # empty line -> add to last definition
             if not line:
                 if in_definition and entries:
@@ -814,13 +814,12 @@ class StandardDomain(Domain):
                 if not sectname:
                     continue
             else:
-                if (isinstance(node, (nodes.definition_list,
-                                      nodes.field_list)) and
+                if (isinstance(node, nodes.definition_list | nodes.field_list) and
                         node.children):
                     node = cast(nodes.Element, node.children[0])
-                if isinstance(node, (nodes.field, nodes.definition_list_item)):
+                if isinstance(node, nodes.field | nodes.definition_list_item):
                     node = cast(nodes.Element, node.children[0])
-                if isinstance(node, (nodes.term, nodes.field_name)):
+                if isinstance(node, nodes.term | nodes.field_name):
                     sectname = clean_astext(node)
                 else:
                     toctree = next(node.findall(addnodes.toctree), None)
@@ -1114,7 +1113,7 @@ class StandardDomain(Domain):
                 return title_getter(elem)
             else:
                 for subnode in elem:
-                    if isinstance(subnode, (nodes.caption, nodes.title)):
+                    if isinstance(subnode, nodes.caption | nodes.title):
                         return clean_astext(subnode)
 
         return None

sphinx/environment/__init__.py

@@ -5,11 +5,10 @@ from __future__ import annotations
 import functools
 import os
 import pickle
-import time
 from collections import defaultdict
 from copy import copy
 from os import path
-from typing import TYPE_CHECKING, Any, Callable, NoReturn
+from typing import TYPE_CHECKING, Any, NoReturn
 
 from sphinx import addnodes
 from sphinx.environment.adapters import toctree as toctree_adapters
@@ -17,13 +16,14 @@ from sphinx.errors import BuildEnvironmentError, DocumentError, ExtensionError,
 from sphinx.locale import __
 from sphinx.transforms import SphinxTransformer
 from sphinx.util import DownloadFiles, FilenameUniqDict, logging
+from sphinx.util._timestamps import _format_rfc3339_microseconds
 from sphinx.util.docutils import LoggingReporter
 from sphinx.util.i18n import CatalogRepository, docname_to_domain
 from sphinx.util.nodes import is_translatable
-from sphinx.util.osutil import canon_path, os_path
+from sphinx.util.osutil import _last_modified_time, canon_path, os_path
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
     from pathlib import Path
 
     from docutils import nodes
@@ -59,7 +59,7 @@ default_settings: dict[str, Any] = {
 
 # This is increased every time an environment attribute is added
 # or changed to properly invalidate pickle files.
-ENV_VERSION = 62
+ENV_VERSION = 63
 
 # config status
 CONFIG_UNSET = -1
@@ -124,7 +124,7 @@ if TYPE_CHECKING:
         def __getitem__(self, key: Literal["todo"]) -> TodoDomain: ...  # NoQA: E704
         @overload
         def __getitem__(self, key: str) -> Domain: ...  # NoQA: E704
-        def __getitem__(self, key): raise NotImplementedError  # NoQA: E704
+        def __getitem__(self, _key: str) -> Domain: raise NotImplementedError  # NoQA: E704
         def __setitem__(  # NoQA: E301,E704
             self, key: str, value: Domain,
         ) -> NoReturn: raise NotImplementedError
@@ -413,13 +413,13 @@ class BuildEnvironment:
         """
         return self.project.path2doc(filename)
 
-    def doc2path(self, docname: str, base: bool = True) -> str:
+    def doc2path(self, docname: str, base: bool = True) -> Path:
         """Return the filename for the document name.
 
         If *base* is True, return absolute path under self.srcdir.
         If *base* is False, return relative path to self.srcdir.
         """
-        return self.project.doc2path(docname, base)
+        return self.project.doc2path(docname, absolute=base)
 
     def relfn2path(self, filename: str, docname: str | None = None) -> tuple[str, str]:
         """Return paths to a file referenced from a document, relative to
@@ -508,7 +508,8 @@ class BuildEnvironment:
                 if newmtime > mtime:
                     logger.debug('[build target] outdated %r: %s -> %s',
                                  docname,
-                                 _format_modified_time(mtime), _format_modified_time(newmtime))
+                                 _format_rfc3339_microseconds(mtime),
+                                 _format_rfc3339_microseconds(newmtime))
                     changed.add(docname)
                     continue
                 # finally, check the mtime of dependencies
@@ -528,7 +529,8 @@ class BuildEnvironment:
                             logger.debug(
                                 '[build target] outdated %r from dependency %r: %s -> %s',
                                 docname, deppath,
-                                _format_modified_time(mtime), _format_modified_time(depmtime),
+                                _format_rfc3339_microseconds(mtime),
+                                _format_rfc3339_microseconds(depmtime),
                             )
                             changed.add(docname)
                             break
@@ -628,7 +630,7 @@ class BuildEnvironment:
 
         doctree = pickle.loads(serialised)
         doctree.settings.env = self
-        doctree.reporter = LoggingReporter(self.doc2path(docname))
+        doctree.reporter = LoggingReporter(str(self.doc2path(docname)))
         return doctree
 
     @functools.cached_property
@@ -650,7 +652,7 @@ class BuildEnvironment:
             try:
                 doctree = self._write_doc_doctree_cache.pop(docname)
                 doctree.settings.env = self
-                doctree.reporter = LoggingReporter(self.doc2path(docname))
+                doctree.reporter = LoggingReporter(str(self.doc2path(docname)))
             except KeyError:
                 doctree = self.get_doctree(docname)
 
@@ -756,26 +758,6 @@ class BuildEnvironment:
         self.events.emit('env-check-consistency', self)
 
 
-def _last_modified_time(filename: str | os.PathLike[str]) -> int:
-    """Return the last modified time of ``filename``.
-
-    The time is returned as integer microseconds.
-    The lowest common denominator of modern file-systems seems to be
-    microsecond-level precision.
-
-    We prefer to err on the side of re-rendering a file,
-    so we round up to the nearest microsecond.
-    """
-    # upside-down floor division to get the ceiling
-    return -(os.stat(filename).st_mtime_ns // -1_000)
-
-
-def _format_modified_time(timestamp: int) -> str:
-    """Return an RFC 3339 formatted string representing the given timestamp."""
-    seconds, fraction = divmod(timestamp, 10**6)
-    return time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime(seconds)) + f'.{fraction // 1_000}'
-
-
 def _traverse_toctree(
     traversed: set[str],
     parent: str | None,

sphinx/environment/adapters/indexentries.py

@@ -13,16 +13,14 @@ from sphinx.util import logging
 from sphinx.util.index_entries import _split_into
 
 if TYPE_CHECKING:
-    from typing import Literal, Optional, Union
-
-    from typing_extensions import TypeAlias
+    from typing import Literal, TypeAlias
 
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
 
-    _IndexEntryTarget: TypeAlias = tuple[Optional[str], Union[str, Literal[False]]]
+    _IndexEntryTarget: TypeAlias = tuple[str | None, str | Literal[False]]
     _IndexEntryTargets: TypeAlias = list[_IndexEntryTarget]
-    _IndexEntryCategoryKey: TypeAlias = Optional[str]
+    _IndexEntryCategoryKey: TypeAlias = str | None
     _IndexEntrySubItems: TypeAlias = dict[
         str,
         tuple[_IndexEntryTargets, _IndexEntryCategoryKey],
@@ -32,7 +30,7 @@ if TYPE_CHECKING:
         _IndexEntrySubItems,
         _IndexEntryCategoryKey,
     ]
-    _IndexEntryMap = dict[str, _IndexEntry]
+    _IndexEntryMap: TypeAlias = dict[str, _IndexEntry]
     _Index: TypeAlias = list[
         tuple[
             str,

sphinx/environment/adapters/toctree.py

@@ -319,7 +319,7 @@ def _toctree_entry(
                            ref, location=toctreenode, type='toc', subtype='no_title')
     except KeyError:
         # this is raised if the included file does not exist
-        ref_path = env.doc2path(ref, False)
+        ref_path = str(env.doc2path(ref, False))
         if excluded(ref_path):
             message = __('toctree contains reference to excluded document %r')
         elif not included(ref_path):
@@ -404,7 +404,7 @@ def _toctree_standard_entry(
 def _toctree_add_classes(node: Element, depth: int, docname: str) -> None:
     """Add 'toctree-l%d' and 'current' classes to the toctree."""
     for subnode in node.children:
-        if isinstance(subnode, (addnodes.compact_paragraph, nodes.list_item)):
+        if isinstance(subnode, addnodes.compact_paragraph | nodes.list_item):
             # for <p> and <li>, indicate the depth level and recurse
             subnode['classes'].append(f'toctree-l{depth - 1}')
             _toctree_add_classes(subnode, depth, docname)
@@ -442,7 +442,7 @@ def _toctree_copy(node: ET, depth: int, maxdepth: int, collapse: bool, tags: Tag
 
     copy = node.copy()
     for subnode in node.children:
-        if isinstance(subnode, (addnodes.compact_paragraph, nodes.list_item)):
+        if isinstance(subnode, addnodes.compact_paragraph | nodes.list_item):
             # for <p> and <li>, just recurse
             copy.append(_toctree_copy(subnode, depth, maxdepth, collapse, tags))
         elif isinstance(subnode, nodes.bullet_list):
@@ -462,7 +462,7 @@ def _toctree_copy(node: ET, depth: int, maxdepth: int, collapse: bool, tags: Tag
                     copy.append(_toctree_copy(
                         child, depth, maxdepth, collapse, tags,  # type: ignore[type-var]
                     ))
-        elif isinstance(subnode, (nodes.reference, nodes.title)):
+        elif isinstance(subnode, nodes.reference | nodes.title):
             # deep copy references and captions
             sub_node_copy = subnode.copy()
             sub_node_copy.children = [child.deepcopy() for child in subnode.children]

sphinx/environment/collectors/title.py

@@ -43,7 +43,7 @@ class TitleCollector(EnvironmentCollector):
         for node in doctree.findall(nodes.section):
             visitor = SphinxContentsFilter(doctree)
             node[0].walkabout(visitor)
-            titlenode += visitor.get_entry_text()
+            titlenode += visitor.get_entry_text()  # type: ignore[no-untyped-call]
             break
         else:
             # document has no title

sphinx/environment/collectors/toctree.py

@@ -78,7 +78,7 @@ class TocTreeCollector(EnvironmentCollector):
                     # and unnecessary stuff
                     visitor = SphinxContentsFilter(doctree)
                     title.walkabout(visitor)
-                    nodetext = visitor.get_entry_text()
+                    nodetext = visitor.get_entry_text()  # type: ignore[no-untyped-call]
                     anchorname = _make_anchor_name(sectionnode['ids'], numentries)
                     # make these nodes:
                     # list_item -> compact_paragraph -> reference

sphinx/events.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 import contextlib
 from collections import defaultdict
 from operator import attrgetter
-from typing import TYPE_CHECKING, Any, Callable, NamedTuple
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 from sphinx.errors import ExtensionError, SphinxError
 from sphinx.locale import __
@@ -16,6 +16,8 @@ from sphinx.util import logging
 from sphinx.util.inspect import safe_getattr
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from sphinx.application import Sphinx