Sphinx 7.1.2__py3-none-any.whl → 7.2.0__py3-none-any.whl

sphinx/domains/std.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import re
 from copy import copy
-from typing import TYPE_CHECKING, Any, Callable, Final, Iterable, Iterator, cast
+from typing import TYPE_CHECKING, Any, Callable, Final, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node, system_message
@@ -20,12 +20,14 @@ from sphinx.roles import EmphasizedLiteral, XRefRole
 from sphinx.util import docname_join, logging, ws_re
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import clean_astext, make_id, make_refnode
-from sphinx.util.typing import OptionSpec, RoleFunction
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
+    from sphinx.util.typing import OptionSpec, RoleFunction
 
 logger = logging.getLogger(__name__)
 
@@ -214,7 +216,7 @@ class Cmdoption(ObjectDescription[str]):
 
         self.state.document.note_explicit_target(signode)
 
-        domain = cast(StandardDomain, self.env.get_domain('std'))
+        domain = self.env.domains['std']
         for optname in signode.get('allnames', []):
             domain.add_program_option(currprogram, optname,
                                       self.env.docname, signode['ids'][0])
@@ -381,10 +383,12 @@ class Glossary(SphinxDirective):
                 parts = split_term_classifiers(line)
                 # parse the term with inline markup
                 # classifiers (parts[1:]) will not be shown on doctree
-                textnodes, sysmsg = self.state.inline_text(parts[0], lineno)
+                textnodes, sysmsg = self.state.inline_text(parts[0],  # type: ignore[arg-type]
+                                                           lineno)
 
                 # use first classifier as a index key
-                term = make_glossary_term(self.env, textnodes, parts[1], source, lineno,
+                term = make_glossary_term(self.env, textnodes,
+                                          parts[1], source, lineno,  # type: ignore[arg-type]
                                           node_id=None, document=self.state.document)
                 term.rawsource = line
                 system_messages.extend(sysmsg)
@@ -645,7 +649,7 @@ class StandardDomain(Domain):
         self._terms[term.lower()] = (self.env.docname, labelid)
 
     @property
-    def progoptions(self) -> dict[tuple[str, str], tuple[str, str]]:
+    def progoptions(self) -> dict[tuple[str | None, str], tuple[str, str]]:
         return self.data.setdefault('progoptions', {})  # (program, name) -> docname, labelid
 
     @property
@@ -704,7 +708,7 @@ class StandardDomain(Domain):
             node = document.ids[labelid]
             if isinstance(node, nodes.target) and 'refid' in node:
                 # indirect hyperlink targets
-                node = document.ids.get(node['refid'])
+                node = document.ids.get(node['refid'])  # type: ignore[assignment]
                 labelid = node['names'][0]
             if (node.tagname == 'footnote' or
                     'refuri' in node or
@@ -719,11 +723,11 @@ class StandardDomain(Domain):
             self.anonlabels[name] = docname, labelid
             if node.tagname == 'section':
                 title = cast(nodes.title, node[0])
-                sectname: str | None = clean_astext(title)
+                sectname = clean_astext(title)
             elif node.tagname == 'rubric':
                 sectname = clean_astext(node)
             elif self.is_enumerable_node(node):
-                sectname = self.get_numfig_title(node)
+                sectname = self.get_numfig_title(node) or ''
                 if not sectname:
                     continue
             else:
@@ -738,13 +742,14 @@ class StandardDomain(Domain):
                 else:
                     toctree = next(node.findall(addnodes.toctree), None)
                     if toctree and toctree.get('caption'):
-                        sectname = toctree.get('caption')
+                        sectname = toctree['caption']
                     else:
                         # anonymous-only labels
                         continue
             self.labels[name] = docname, labelid, sectname
 
-    def add_program_option(self, program: str, name: str, docname: str, labelid: str) -> None:
+    def add_program_option(self, program: str | None, name: str,
+                           docname: str, labelid: str) -> None:
         # prefer first command option entry
         if (program, name) not in self.progoptions:
             self.progoptions[program, name] = (docname, labelid)
@@ -825,6 +830,7 @@ class StandardDomain(Domain):
             return None
 
         target_node = env.get_doctree(docname).ids.get(labelid)
+        assert target_node is not None
         figtype = self.get_enumerable_node_type(target_node)
         if figtype is None:
             return None
@@ -983,9 +989,9 @@ class StandardDomain(Domain):
                 key = (objtype, ltarget)
             if key in self.objects:
                 docname, labelid = self.objects[key]
-                results.append(('std:' + self.role_for_objtype(objtype),
-                                make_refnode(builder, fromdocname, docname,
-                                             labelid, contnode)))
+                role = 'std:' + self.role_for_objtype(objtype)  # type: ignore[operator]
+                results.append((role, make_refnode(builder, fromdocname, docname,
+                                                   labelid, contnode)))
         return results
 
     def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]:
@@ -1096,7 +1102,7 @@ def warn_missing_reference(app: Sphinx, domain: Domain, node: pending_xref,
         return None
     else:
         target = node['reftarget']
-        if target not in domain.anonlabels:  # type: ignore
+        if target not in domain.anonlabels:  # type: ignore[attr-defined]
             msg = __('undefined label: %r')
         else:
             msg = __('Failed to create a cross reference. A title or caption not found: %r')

sphinx/environment/__init__.py

@@ -5,23 +5,16 @@ from __future__ import annotations
 import functools
 import os
 import pickle
+import time
 from collections import defaultdict
 from copy import copy
-from datetime import datetime, timezone
 from os import path
-from typing import TYPE_CHECKING, Any, Callable, Generator, Iterator
-
-from docutils import nodes
-from docutils.nodes import Node
+from typing import TYPE_CHECKING, Any, Callable
 
 from sphinx import addnodes
-from sphinx.config import Config
-from sphinx.domains import Domain
-from sphinx.environment.adapters.toctree import TocTree
+from sphinx.environment.adapters import toctree as toctree_adapters
 from sphinx.errors import BuildEnvironmentError, DocumentError, ExtensionError, SphinxError
-from sphinx.events import EventManager
 from sphinx.locale import __
-from sphinx.project import Project
 from sphinx.transforms import SphinxTransformer
 from sphinx.util import DownloadFiles, FilenameUniqDict, logging
 from sphinx.util.docutils import LoggingReporter
@@ -30,8 +23,18 @@ from sphinx.util.nodes import is_translatable
 from sphinx.util.osutil import canon_path, os_path
 
 if TYPE_CHECKING:
+    from collections.abc import Generator, Iterator
+    from pathlib import Path
+
+    from docutils import nodes
+    from docutils.nodes import Node
+
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
+    from sphinx.config import Config
+    from sphinx.domains import Domain
+    from sphinx.events import EventManager
+    from sphinx.project import Project
 
 logger = logging.getLogger(__name__)
 
@@ -55,9 +58,10 @@ default_settings: dict[str, Any] = {
 
 # This is increased every time an environment attribute is added
 # or changed to properly invalidate pickle files.
-ENV_VERSION = 58
+ENV_VERSION = 60
 
 # config status
+CONFIG_UNSET = -1
 CONFIG_OK = 1
 CONFIG_NEW = 2
 CONFIG_CHANGED = 3
@@ -76,7 +80,8 @@ versioning_conditions: dict[str, bool | Callable] = {
 }
 
 if TYPE_CHECKING:
-    from typing import Literal, MutableMapping
+    from collections.abc import MutableMapping
+    from typing import Literal
 
     from typing_extensions import overload
 
@@ -142,25 +147,25 @@ class BuildEnvironment:
     # --------- ENVIRONMENT INITIALIZATION -------------------------------------
 
     def __init__(self, app: Sphinx):
-        self.app: Sphinx = None
-        self.doctreedir: str = None
-        self.srcdir: str = None
-        self.config: Config = None
-        self.config_status: int = None
-        self.config_status_extra: str = None
-        self.events: EventManager = None
-        self.project: Project = None
-        self.version: dict[str, str] = None
+        self.app: Sphinx = app
+        self.doctreedir: Path = app.doctreedir
+        self.srcdir: Path = app.srcdir
+        self.config: Config = None  # type: ignore[assignment]
+        self.config_status: int = CONFIG_UNSET
+        self.config_status_extra: str = ''
+        self.events: EventManager = app.events
+        self.project: Project = app.project
+        self.version: dict[str, str] = app.registry.get_envversion(app)
 
         # the method of doctree versioning; see set_versioning_method
-        self.versioning_condition: bool | Callable = None
-        self.versioning_compare: bool = None
+        self.versioning_condition: bool | Callable | None = None
+        self.versioning_compare: bool | None = None
 
         # all the registered domains, set by the application
         self.domains = _DomainsType()
 
         # the docutils settings for building
-        self.settings = default_settings.copy()
+        self.settings: dict[str, Any] = default_settings.copy()
         self.settings['env'] = self
 
         # All "docnames" here are /-separated and relative and exclude
@@ -372,7 +377,7 @@ class BuildEnvironment:
 
         This possibly comes from a parallel build process.
         """
-        docnames = set(docnames)  # type: ignore
+        docnames = set(docnames)  # type: ignore[assignment]
         for docname in docnames:
             self.all_docs[docname] = other.all_docs[docname]
             self.included[docname] = other.included[docname]
@@ -383,7 +388,7 @@ class BuildEnvironment:
             domain.merge_domaindata(docnames, other.domaindata[domainname])
         self.events.emit('env-merge-info', self, docnames, other)
 
-    def path2doc(self, filename: str) -> str | None:
+    def path2doc(self, filename: str | os.PathLike[str]) -> str | None:
         """Return the docname for the filename if the file is document.
 
         *filename* should be absolute or relative to the source directory.
@@ -483,12 +488,9 @@ class BuildEnvironment:
                 mtime = self.all_docs[docname]
                 newmtime = _last_modified_time(self.doc2path(docname))
                 if newmtime > mtime:
-                    # convert integer microseconds to floating-point seconds,
-                    # and then to timezone-aware datetime objects.
-                    mtime_dt = datetime.fromtimestamp(mtime / 1_000_000, tz=timezone.utc)
-                    newmtime_dt = datetime.fromtimestamp(mtime / 1_000_000, tz=timezone.utc)
                     logger.debug('[build target] outdated %r: %s -> %s',
-                                 docname, mtime_dt, newmtime_dt)
+                                 docname,
+                                 _format_modified_time(mtime), _format_modified_time(newmtime))
                     changed.add(docname)
                     continue
                 # finally, check the mtime of dependencies
@@ -497,10 +499,19 @@ class BuildEnvironment:
                         # this will do the right thing when dep is absolute too
                         deppath = path.join(self.srcdir, dep)
                         if not path.isfile(deppath):
+                            logger.debug(
+                                '[build target] changed %r missing dependency %r',
+                                docname, deppath,
+                            )
                             changed.add(docname)
                             break
                         depmtime = _last_modified_time(deppath)
                         if depmtime > mtime:
+                            logger.debug(
+                                '[build target] outdated %r from dependency %r: %s -> %s',
+                                docname, deppath,
+                                _format_modified_time(mtime), _format_modified_time(depmtime),
+                            )
                             changed.add(docname)
                             break
                     except OSError:
@@ -625,9 +636,11 @@ class BuildEnvironment:
 
         # now, resolve all toctree nodes
         for toctreenode in doctree.findall(addnodes.toctree):
-            result = TocTree(self).resolve(docname, builder, toctreenode,
-                                           prune=prune_toctrees,
-                                           includehidden=includehidden)
+            result = toctree_adapters._resolve_toctree(
+                self, docname, builder, toctreenode,
+                prune=prune_toctrees,
+                includehidden=includehidden,
+            )
             if result is None:
                 toctreenode.parent.replace(toctreenode, [])
             else:
@@ -649,9 +662,14 @@ class BuildEnvironment:
         If *collapse* is True, all branches not containing docname will
         be collapsed.
         """
-        return TocTree(self).resolve(docname, builder, toctree, prune,
-                                     maxdepth, titles_only, collapse,
-                                     includehidden)
+        return toctree_adapters._resolve_toctree(
+            self, docname, builder, toctree,
+            prune=prune,
+            maxdepth=maxdepth,
+            titles_only=titles_only,
+            collapse=collapse,
+            includehidden=includehidden,
+        )
 
     def resolve_references(self, doctree: nodes.document, fromdocname: str,
                            builder: Builder) -> None:
@@ -675,38 +693,21 @@ class BuildEnvironment:
         self.events.emit('doctree-resolved', doctree, docname)
 
     def collect_relations(self) -> dict[str, list[str | None]]:
-        traversed = set()
-
-        def traverse_toctree(
-            parent: str | None, docname: str,
-        ) -> Iterator[tuple[str | None, str]]:
-            if parent == docname:
-                logger.warning(__('self referenced toctree found. Ignored.'),
-                               location=docname, type='toc',
-                               subtype='circular')
-                return
-
-            # traverse toctree by pre-order
-            yield parent, docname
-            traversed.add(docname)
-
-            for child in (self.toctree_includes.get(docname) or []):
-                for subparent, subdocname in traverse_toctree(docname, child):
-                    if subdocname not in traversed:
-                        yield subparent, subdocname
-                        traversed.add(subdocname)
+        traversed: set[str] = set()
 
         relations = {}
-        docnames = traverse_toctree(None, self.config.root_doc)
-        prevdoc = None
+        docnames = _traverse_toctree(
+            traversed, None, self.config.root_doc, self.toctree_includes,
+        )
+        prev_doc = None
         parent, docname = next(docnames)
-        for nextparent, nextdoc in docnames:
-            relations[docname] = [parent, prevdoc, nextdoc]
-            prevdoc = docname
-            docname = nextdoc
-            parent = nextparent
+        for next_parent, next_doc in docnames:
+            relations[docname] = [parent, prev_doc, next_doc]
+            prev_doc = docname
+            docname = next_doc
+            parent = next_parent
 
-        relations[docname] = [parent, prevdoc, None]
+        relations[docname] = [parent, prev_doc, None]
 
         return relations
 
@@ -745,3 +746,34 @@ def _last_modified_time(filename: str | os.PathLike[str]) -> int:
 
     # 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,
+    docname: str,
+    toctree_includes: dict[str, list[str]],
+) -> Iterator[tuple[str | None, str]]:
+    if parent == docname:
+        logger.warning(__('self referenced toctree found. Ignored.'),
+                       location=docname, type='toc',
+                       subtype='circular')
+        return
+
+    # traverse toctree by pre-order
+    yield parent, docname
+    traversed.add(docname)
+
+    for child in toctree_includes.get(docname, ()):
+        for sub_parent, sub_docname in _traverse_toctree(
+            traversed, docname, child, toctree_includes,
+        ):
+            if sub_docname not in traversed:
+                yield sub_parent, sub_docname
+                traversed.add(sub_docname)

sphinx/environment/adapters/indexentries.py

@@ -5,13 +5,16 @@ from __future__ import annotations
 import re
 import unicodedata
 from itertools import groupby
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
-from sphinx.builders import Builder
-from sphinx.environment import BuildEnvironment
 from sphinx.errors import NoUri
 from sphinx.locale import _, __
-from sphinx.util import logging, split_into
+from sphinx.util import logging
+from sphinx.util.index_entries import _split_into
+
+if TYPE_CHECKING:
+    from sphinx.builders import Builder
+    from sphinx.environment import BuildEnvironment
 
 logger = logging.getLogger(__name__)
 
@@ -41,20 +44,20 @@ class IndexEntries:
                 try:
                     if entry_type == 'single':
                         try:
-                            entry, sub_entry = split_into(2, 'single', value)
+                            entry, sub_entry = _split_into(2, 'single', value)
                         except ValueError:
-                            entry, = split_into(1, 'single', value)
+                            entry, = _split_into(1, 'single', value)
                             sub_entry = ''
                         _add_entry(entry, sub_entry, main,
                                    dic=new, link=uri, key=category_key)
                     elif entry_type == 'pair':
-                        first, second = split_into(2, 'pair', value)
+                        first, second = _split_into(2, 'pair', value)
                         _add_entry(first, second, main,
                                    dic=new, link=uri, key=category_key)
                         _add_entry(second, first, main,
                                    dic=new, link=uri, key=category_key)
                     elif entry_type == 'triple':
-                        first, second, third = split_into(3, 'triple', value)
+                        first, second, third = _split_into(3, 'triple', value)
                         _add_entry(first, second + ' ' + third, main,
                                    dic=new, link=uri, key=category_key)
                         _add_entry(second, third + ', ' + first, main,
@@ -62,11 +65,11 @@ class IndexEntries:
                         _add_entry(third, first + ' ' + second, main,
                                    dic=new, link=uri, key=category_key)
                     elif entry_type == 'see':
-                        first, second = split_into(2, 'see', value)
+                        first, second = _split_into(2, 'see', value)
                         _add_entry(first, _('see %s') % second, None,
                                    dic=new, link=False, key=category_key)
                     elif entry_type == 'seealso':
-                        first, second = split_into(2, 'see', value)
+                        first, second = _split_into(2, 'see', value)
                         _add_entry(first, _('see also %s') % second, None,
                                    dic=new, link=False, key=category_key)
                     else: