Sphinx 7.4.7__py3-none-any.whl → 8.0.0__py3-none-any.whl

sphinx/ext/intersphinx/_shared.py

@@ -2,19 +2,113 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Final, Union
+from typing import TYPE_CHECKING, Any, Final, NoReturn
 
 from sphinx.util import logging
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from typing import TypeAlias
+
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import Inventory
 
-    InventoryCacheEntry = tuple[Union[str, None], int, Inventory]
+    #: The inventory project URL to which links are resolved.
+    #:
+    #: This value is unique in :confval:`intersphinx_mapping`.
+    InventoryURI = str
+
+    #: The inventory (non-empty) name.
+    #:
+    #: It is unique and in bijection with an inventory remote URL.
+    InventoryName = str
+
+    #: A target (local or remote) containing the inventory data to fetch.
+    #:
+    #: Empty strings are not expected and ``None`` indicates the default
+    #: inventory file name :data:`~sphinx.builder.html.INVENTORY_FILENAME`.
+    InventoryLocation = str | None
+
+    #: Inventory cache entry. The integer field is the cache expiration time.
+    InventoryCacheEntry: TypeAlias = tuple[InventoryName, int, Inventory]
+
+    #: The type of :confval:`intersphinx_mapping` *after* normalisation.
+    IntersphinxMapping = dict[
+        InventoryName,
+        tuple[InventoryName, tuple[InventoryURI, tuple[InventoryLocation, ...]]],
+    ]
 
 LOGGER: Final[logging.SphinxLoggerAdapter] = logging.getLogger('sphinx.ext.intersphinx')
 
 
+class _IntersphinxProject:
+    name: InventoryName
+    target_uri: InventoryURI
+    locations: tuple[InventoryLocation, ...]
+
+    __slots__ = {
+        'name':       'The inventory name. '
+                      'It is unique and in bijection with an remote inventory URL.',
+        'target_uri': 'The inventory project URL to which links are resolved. '
+                      'It is unique and in bijection with an inventory name.',
+        'locations':  'A tuple of local or remote targets containing '
+                      'the inventory data to fetch. '
+                      'None indicates the default inventory file name.',
+    }
+
+    def __init__(
+        self,
+        *,
+        name: InventoryName,
+        target_uri: InventoryURI,
+        locations: Sequence[InventoryLocation],
+    ) -> None:
+        if not name or not isinstance(name, str):
+            msg = 'name must be a non-empty string'
+            raise ValueError(msg)
+        if not target_uri or not isinstance(target_uri, str):
+            msg = 'target_uri must be a non-empty string'
+            raise ValueError(msg)
+        if not locations or not isinstance(locations, tuple):
+            msg = 'locations must be a non-empty tuple'
+            raise ValueError(msg)
+        if any(
+            location is not None and (not location or not isinstance(location, str))
+            for location in locations
+        ):
+            msg = 'locations must be a tuple of strings or None'
+            raise ValueError(msg)
+        object.__setattr__(self, 'name', name)
+        object.__setattr__(self, 'target_uri', target_uri)
+        object.__setattr__(self, 'locations', tuple(locations))
+
+    def __repr__(self) -> str:
+        return (f'{self.__class__.__name__}('
+                f'name={self.name!r}, '
+                f'target_uri={self.target_uri!r}, '
+                f'locations={self.locations!r})')
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _IntersphinxProject):
+            return NotImplemented
+        return (
+            self.name == other.name
+            and self.target_uri == other.target_uri
+            and self.locations == other.locations
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.name, self.target_uri, self.locations))
+
+    def __setattr__(self, key: str, value: Any) -> NoReturn:
+        msg = f'{self.__class__.__name__} is immutable'
+        raise AttributeError(msg)
+
+    def __delattr__(self, key: str) -> NoReturn:
+        msg = f'{self.__class__.__name__} is immutable'
+        raise AttributeError(msg)
+
+
 class InventoryAdapter:
     """Inventory adapter for environment"""
 
@@ -29,14 +123,13 @@ class InventoryAdapter:
             self.env.intersphinx_named_inventory = {}  # type: ignore[attr-defined]
 
     @property
-    def cache(self) -> dict[str, InventoryCacheEntry]:
+    def cache(self) -> dict[InventoryURI, InventoryCacheEntry]:
         """Intersphinx cache.
 
-        - Key is the URI of the remote inventory
-        - Element one is the key given in the Sphinx intersphinx_mapping
-          configuration value
-        - Element two is a time value for cache invalidation, a float
-        - Element three is the loaded remote inventory, type Inventory
+        - Key is the URI of the remote inventory.
+        - Element one is the key given in the Sphinx :confval:`intersphinx_mapping`.
+        - Element two is a time value for cache invalidation, an integer.
+        - Element three is the loaded remote inventory of type :class:`!Inventory`.
         """
         return self.env.intersphinx_cache  # type: ignore[attr-defined]
 
@@ -45,7 +138,7 @@ class InventoryAdapter:
         return self.env.intersphinx_inventory  # type: ignore[attr-defined]
 
     @property
-    def named_inventory(self) -> dict[str, Inventory]:
+    def named_inventory(self) -> dict[InventoryName, Inventory]:
         return self.env.intersphinx_named_inventory  # type: ignore[attr-defined]
 
     def clear(self) -> None:

sphinx/ext/mathjax.py

@@ -22,7 +22,7 @@ from sphinx.util.math import get_node_equation_number
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
-    from sphinx.writers.html import HTML5Translator
+    from sphinx.writers.html5 import HTML5Translator
 
 # more information for mathjax secure url is here:
 # https://docs.mathjax.org/en/latest/web/start.html#using-mathjax-from-a-content-delivery-network-cdn

sphinx/ext/napoleon/docstring.py

@@ -8,14 +8,14 @@ import inspect
 import re
 from functools import partial
 from itertools import starmap
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 from sphinx.locale import _, __
 from sphinx.util import logging
 from sphinx.util.typing import get_type_hints, stringify_annotation
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
 
     from sphinx.application import Sphinx
     from sphinx.config import Config as SphinxConfig

sphinx/ext/todo.py

@@ -29,7 +29,7 @@ if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import ExtensionMetadata, OptionSpec
-    from sphinx.writers.html import HTML5Translator
+    from sphinx.writers.html5 import HTML5Translator
     from sphinx.writers.latex import LaTeXTranslator
 
 logger = logging.getLogger(__name__)
@@ -43,7 +43,7 @@ class todolist(nodes.General, nodes.Element):
     pass
 
 
-class Todo(BaseAdmonition, SphinxDirective):
+class Todo(BaseAdmonition, SphinxDirective):  # type: ignore[misc]
     """
     A todo entry, displayed (if configured) in the form of an admonition.
     """

sphinx/ext/viewcode.py

@@ -21,6 +21,7 @@ from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util import logging
 from sphinx.util.display import status_iterator
 from sphinx.util.nodes import make_refnode
+from sphinx.util.osutil import _last_modified_time
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator
@@ -231,7 +232,7 @@ def should_generate_module_page(app: Sphinx, modname: str) -> bool:
     page_filename = path.join(app.outdir, '_modules/', basename)
 
     try:
-        if path.getmtime(module_filename) <= path.getmtime(page_filename):
+        if _last_modified_time(module_filename) <= _last_modified_time(page_filename):
             # generation is not needed if the HTML page is newer than module file.
             return False
     except OSError:

sphinx/highlighting.py

@@ -86,8 +86,8 @@ _LATEX_ADD_STYLES = r"""
 class PygmentsBridge:
     # Set these attributes if you want to have different Pygments formatters
     # than the default ones.
-    html_formatter = HtmlFormatter
-    latex_formatter = LatexFormatter
+    html_formatter = HtmlFormatter[str]
+    latex_formatter = LatexFormatter[str]
 
     def __init__(
         self, dest: str = 'html', stylename: str = 'sphinx', latex_engine: str | None = None
@@ -98,7 +98,7 @@ class PygmentsBridge:
         style = self.get_style(stylename)
         self.formatter_args: dict[str, Any] = {'style': style}
         if dest == 'html':
-            self.formatter = self.html_formatter
+            self.formatter: type[Formatter[str]] = self.html_formatter
         else:
             self.formatter = self.latex_formatter
             self.formatter_args['commandprefix'] = 'PYG'

sphinx/io.py

@@ -35,7 +35,7 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class SphinxBaseReader(standalone.Reader):
+class SphinxBaseReader(standalone.Reader):  # type: ignore[misc]
     """
     A base class of readers for Sphinx.
 
@@ -143,7 +143,7 @@ class SphinxI18nReader(SphinxBaseReader):
                 self.transforms.remove(transform)
 
 
-class SphinxDummyWriter(UnfilteredWriter):
+class SphinxDummyWriter(UnfilteredWriter):  # type: ignore[misc]
     """Dummy writer module used for generating doctree."""
 
     supported = ('html',)  # needed to keep "meta" nodes

sphinx/jinja2glue.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
+import os
 from os import path
 from pprint import pformat
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 from jinja2 import BaseLoader, FileSystemLoader, TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -12,10 +13,10 @@ from jinja2.utils import open_if_exists, pass_context
 
 from sphinx.application import TemplateBridge
 from sphinx.util import logging
-from sphinx.util.osutil import mtimes_of_files
+from sphinx.util.osutil import _last_modified_time
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
 
     from jinja2.environment import Environment
 
@@ -127,11 +128,11 @@ class SphinxFileSystemLoader(FileSystemLoader):
         with f:
             contents = f.read().decode(self.encoding)
 
-        mtime = path.getmtime(filename)
+        mtime = _last_modified_time(filename)
 
         def uptodate() -> bool:
             try:
-                return path.getmtime(filename) == mtime
+                return _last_modified_time(filename) == mtime
             except OSError:
                 return False
 
@@ -203,7 +204,13 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
         return self.environment.from_string(source).render(context)
 
     def newest_template_mtime(self) -> float:
-        return max(mtimes_of_files(self.pathchain, '.html'))
+        return max(
+            os.stat(os.path.join(root, sfile)).st_mtime_ns / 10**9
+            for dirname in self.pathchain
+            for root, _dirs, files in os.walk(dirname)
+            for sfile in files
+            if sfile.endswith('.html')
+        )
 
     # Loader interface
 

sphinx/locale/__init__.py

@@ -9,8 +9,9 @@ from os import path
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
-    from typing import Any, Callable
+    import os
+    from collections.abc import Callable, Iterable
+    from typing import Any
 
 
 class _TranslationProxy:
@@ -98,7 +99,7 @@ translators: dict[tuple[str, str], NullTranslations] = {}
 
 
 def init(
-    locale_dirs: Iterable[str | None],
+    locale_dirs: Iterable[str | os.PathLike[str] | None],
     language: str | None,
     catalog: str = 'sphinx',
     namespace: str = 'general',