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

sphinx/ext/autodoc/directive.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Callable
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
 from docutils.statemachine import StringList
@@ -31,14 +32,14 @@ AUTODOC_EXTENDABLE_OPTIONS = ['members', 'private-members', 'special-members',
                               'exclude-members']
 
 
-class DummyOptionSpec(dict):
+class DummyOptionSpec(dict[str, Callable[[str], str]]):
     """An option_spec allows any options."""
 
     def __bool__(self) -> bool:
         """Behaves like some options are defined."""
         return True
 
-    def __getitem__(self, key: str) -> Callable[[str], str]:
+    def __getitem__(self, _key: str) -> Callable[[str], str]:
         return lambda x: x
 
 
@@ -56,8 +57,9 @@ class DocumenterBridge:
         self.state = state
 
 
-def process_documenter_options(documenter: type[Documenter], config: Config, options: dict,
-                               ) -> Options:
+def process_documenter_options(
+    documenter: type[Documenter], config: Config, options: dict[str, str],
+) -> Options:
     """Recognize options of Documenter from user input."""
     default_options = config.autodoc_default_options
     for name in AUTODOC_DEFAULT_OPTIONS:

sphinx/ext/autodoc/importer.py

@@ -11,8 +11,9 @@ import typing
 from enum import Enum
 from typing import TYPE_CHECKING, NamedTuple
 
+from sphinx.errors import PycodeError
 from sphinx.ext.autodoc.mock import ismock, undecorate
-from sphinx.pycode import ModuleAnalyzer, PycodeError
+from sphinx.pycode import ModuleAnalyzer
 from sphinx.util import logging
 from sphinx.util.inspect import (
     getannotations,

sphinx/ext/autodoc/preserve_defaults.py

@@ -102,9 +102,9 @@ def _is_lambda(x: Any, /) -> bool:
 
 
 def _get_arguments_inner(x: Any, /) -> ast.arguments | None:
-    if isinstance(x, (ast.AsyncFunctionDef, ast.FunctionDef, ast.Lambda)):
+    if isinstance(x, ast.AsyncFunctionDef | ast.FunctionDef | ast.Lambda):
         return x.args
-    if isinstance(x, (ast.Assign, ast.AnnAssign)):
+    if isinstance(x, ast.Assign | ast.AnnAssign):
         return _get_arguments_inner(x.value)
     return None
 

sphinx/ext/autosummary/__init__.py

@@ -69,13 +69,14 @@ import sphinx
 from sphinx import addnodes
 from sphinx.config import Config
 from sphinx.environment import BuildEnvironment
-from sphinx.ext.autodoc import INSTANCEATTR, Documenter
-from sphinx.ext.autodoc.directive import DocumenterBridge, Options
+from sphinx.errors import PycodeError
+from sphinx.ext.autodoc import INSTANCEATTR, Documenter, Options
+from sphinx.ext.autodoc.directive import DocumenterBridge
 from sphinx.ext.autodoc.importer import import_module
 from sphinx.ext.autodoc.mock import mock
 from sphinx.locale import __
 from sphinx.project import Project
-from sphinx.pycode import ModuleAnalyzer, PycodeError
+from sphinx.pycode import ModuleAnalyzer
 from sphinx.registry import SphinxComponentRegistry
 from sphinx.util import logging, rst
 from sphinx.util.docutils import (
@@ -97,7 +98,7 @@ if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.extension import Extension
     from sphinx.util.typing import ExtensionMetadata, OptionSpec
-    from sphinx.writers.html import HTML5Translator
+    from sphinx.writers.html5 import HTML5Translator
 
 logger = logging.getLogger(__name__)
 
@@ -248,7 +249,7 @@ class Autosummary(SphinxDirective):
                 docname = posixpath.join(tree_prefix, real_name)
                 docname = posixpath.normpath(posixpath.join(dirname, docname))
                 if docname not in self.env.found_docs:
-                    if excluded(self.env.doc2path(docname, False)):
+                    if excluded(str(self.env.doc2path(docname, False))):
                         msg = __('autosummary references excluded document %r. Ignored.')
                     else:
                         msg = __('autosummary: stub file not found %r. '
@@ -765,7 +766,14 @@ class AutoLink(SphinxRole):
         try:
             # try to import object by name
             prefixes = get_import_prefixes_from_env(self.env)
-            import_by_name(pending_xref['reftarget'], prefixes)
+            name = pending_xref['reftarget']
+            prefixes = [
+                prefix
+                for prefix in prefixes
+                if prefix is None
+                or not (name.startswith(f'{prefix}.') or name == prefix)
+            ]
+            import_by_name(name, prefixes)
         except ImportExceptionGroup:
             literal = cast(nodes.literal, pending_xref[0])
             objects[0] = nodes.emphasis(self.rawtext, literal.astext(),
@@ -794,7 +802,7 @@ def process_generate_options(app: Sphinx) -> None:
 
     if genfiles is True:
         env = app.builder.env
-        genfiles = [env.doc2path(x, base=False) for x in env.found_docs
+        genfiles = [str(env.doc2path(x, base=False)) for x in env.found_docs
                     if os.path.isfile(env.doc2path(x))]
     elif genfiles is False:
         pass

sphinx/ext/autosummary/generate.py

@@ -34,6 +34,7 @@ import sphinx.locale
 from sphinx import __display_version__, package_dir
 from sphinx.builders import Builder
 from sphinx.config import Config
+from sphinx.errors import PycodeError
 from sphinx.ext.autodoc.importer import import_module
 from sphinx.ext.autosummary import (
     ImportExceptionGroup,
@@ -42,7 +43,7 @@ from sphinx.ext.autosummary import (
     import_ivar_by_name,
 )
 from sphinx.locale import __
-from sphinx.pycode import ModuleAnalyzer, PycodeError
+from sphinx.pycode import ModuleAnalyzer
 from sphinx.registry import SphinxComponentRegistry
 from sphinx.util import logging, rst
 from sphinx.util.inspect import getall, safe_getattr
@@ -145,7 +146,7 @@ class AutosummaryRenderer:
             # ``install_gettext_translations`` is injected by the ``jinja2.ext.i18n`` extension
             self.env.install_gettext_translations(app.translator)  # type: ignore[attr-defined]
 
-    def render(self, template_name: str, context: dict) -> str:
+    def render(self, template_name: str, context: dict[str, Any]) -> str:
         """Render a template file."""
         try:
             template = self.env.get_template(template_name)
@@ -282,7 +283,7 @@ def generate_autosummary_content(
     imported_members: bool,
     app: Any,
     recursive: bool,
-    context: dict,
+    context: dict[str, Any],
     modname: str | None = None,
     qualname: str | None = None,
 ) -> str:
@@ -392,7 +393,7 @@ def _skip_member(app: Sphinx, obj: Any, name: str, objtype: str) -> bool:
 
 
 def _get_class_members(obj: Any) -> dict[str, Any]:
-    members = sphinx.ext.autodoc.get_class_members(obj, None, safe_getattr)
+    members = sphinx.ext.autodoc.importer.get_class_members(obj, None, safe_getattr)
     return {name: member.object for name, member in members.items()}
 
 

sphinx/ext/doctest.py

@@ -11,7 +11,7 @@ import sys
 import time
 from io import StringIO
 from os import path
-from typing import TYPE_CHECKING, Any, Callable, ClassVar
+from typing import TYPE_CHECKING, Any, ClassVar
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -27,7 +27,7 @@ from sphinx.util.docutils import SphinxDirective
 from sphinx.util.osutil import relpath
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Sequence
+    from collections.abc import Callable, Iterable, Sequence
 
     from docutils.nodes import Element, Node, TextElement
 
@@ -373,7 +373,7 @@ Doctest summary
         try:
             filename = relpath(node.source, self.env.srcdir).rsplit(':docstring of ', maxsplit=1)[0]  # type: ignore[arg-type]  # noqa: E501
         except Exception:
-            filename = self.env.doc2path(docname, False)
+            filename = str(self.env.doc2path(docname, False))
         return filename
 
     @staticmethod
@@ -420,12 +420,12 @@ Doctest summary
 
         if self.config.doctest_test_doctest_blocks:
             def condition(node: Node) -> bool:
-                return (isinstance(node, (nodes.literal_block, nodes.comment)) and
+                return (isinstance(node, nodes.literal_block | nodes.comment) and
                         'testnodetype' in node) or \
                     isinstance(node, nodes.doctest_block)
         else:
             def condition(node: Node) -> bool:
-                return isinstance(node, (nodes.literal_block, nodes.comment)) \
+                return isinstance(node, nodes.literal_block | nodes.comment) \
                     and 'testnodetype' in node
         for node in doctree.findall(condition):
             if self.skipped(node):  # type: ignore[arg-type]

sphinx/ext/graphviz.py

@@ -32,7 +32,7 @@ if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.config import Config
     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
     from sphinx.writers.manpage import ManualPageTranslator
     from sphinx.writers.texinfo import TexinfoTranslator

sphinx/ext/imgmath.py

@@ -36,7 +36,7 @@ if TYPE_CHECKING:
     from sphinx.builders import Builder
     from sphinx.config import Config
     from sphinx.util.typing import ExtensionMetadata
-    from sphinx.writers.html import HTML5Translator
+    from sphinx.writers.html5 import HTML5Translator
 
 logger = logging.getLogger(__name__)
 

sphinx/ext/inheritance_diagram.py

@@ -59,7 +59,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
     from sphinx.writers.texinfo import TexinfoTranslator
 

sphinx/ext/intersphinx/__init__.py

@@ -21,9 +21,8 @@ from __future__ import annotations
 __all__ = (
     'InventoryAdapter',
     'fetch_inventory',
-    'fetch_inventory_group',
     'load_mappings',
-    'normalize_intersphinx_mapping',
+    'validate_intersphinx_mapping',
     'IntersphinxRoleResolver',
     'inventory_exists',
     'install_dispatcher',
@@ -42,9 +41,8 @@ import sphinx
 from sphinx.ext.intersphinx._cli import inspect_main
 from sphinx.ext.intersphinx._load import (
     fetch_inventory,
-    fetch_inventory_group,
     load_mappings,
-    normalize_intersphinx_mapping,
+    validate_intersphinx_mapping,
 )
 from sphinx.ext.intersphinx._resolve import (
     IntersphinxDispatcher,
@@ -69,7 +67,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_config_value('intersphinx_cache_limit', 5, '')
     app.add_config_value('intersphinx_timeout', None, '')
     app.add_config_value('intersphinx_disabled_reftypes', ['std:doc'], 'env')
-    app.connect('config-inited', normalize_intersphinx_mapping, priority=800)
+    app.connect('config-inited', validate_intersphinx_mapping, priority=800)
     app.connect('builder-inited', load_mappings)
     app.connect('source-read', install_dispatcher)
     app.connect('missing-reference', missing_reference)
@@ -79,3 +77,25 @@ def setup(app: Sphinx) -> ExtensionMetadata:
         'env_version': 1,
         'parallel_read_safe': True,
     }
+
+
+# deprecated name -> (object to return, canonical path or empty string, removal version)
+_DEPRECATED_OBJECTS: dict[str, tuple[object, str, tuple[int, int]]] = {
+    'normalize_intersphinx_mapping': (
+        validate_intersphinx_mapping,
+        'sphinx.ext.intersphinx.validate_intersphinx_mapping',
+        (10, 0),
+    ),
+}
+
+
+def __getattr__(name: str) -> object:
+    if name not in _DEPRECATED_OBJECTS:
+        msg = f'module {__name__!r} has no attribute {name!r}'
+        raise AttributeError(msg)
+
+    from sphinx.deprecation import _deprecation_warning
+
+    deprecated_object, canonical_name, remove = _DEPRECATED_OBJECTS[name]
+    _deprecation_warning(__name__, name, canonical_name, remove=remove)
+    return deprecated_object

sphinx/ext/intersphinx/_cli.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import sys
 
-from sphinx.ext.intersphinx._load import fetch_inventory
+from sphinx.ext.intersphinx._load import _fetch_inventory
 
 
 def inspect_main(argv: list[str], /) -> int:
@@ -21,13 +21,14 @@ def inspect_main(argv: list[str], /) -> int:
         tls_cacerts: str | dict[str, str] | None = None
         user_agent: str = ''
 
-    class MockApp:
-        srcdir = ''
-        config = MockConfig()
-
     try:
         filename = argv[0]
-        inv_data = fetch_inventory(MockApp(), '', filename)  # type: ignore[arg-type]
+        inv_data = _fetch_inventory(
+            target_uri='',
+            inv_location=filename,
+            config=MockConfig(),  # type: ignore[arg-type]
+            srcdir=''  # type: ignore[arg-type]
+        )
         for key in sorted(inv_data or {}):
             print(key)
             inv_entries = sorted(inv_data[key].items())