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

sphinx/ext/inheritance_diagram.py

@@ -31,19 +31,18 @@ LaTeX.
 from __future__ import annotations
 
 import builtins
+import hashlib
 import inspect
 import re
+from collections.abc import Iterable, Sequence
 from importlib import import_module
-from typing import Any, Iterable, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
-from docutils.nodes import Node
 from docutils.parsers.rst import directives
 
 import sphinx
 from sphinx import addnodes
-from sphinx.application import Sphinx
-from sphinx.environment import BuildEnvironment
 from sphinx.ext.graphviz import (
     figure_wrapper,
     graphviz,
@@ -51,12 +50,17 @@ from sphinx.ext.graphviz import (
     render_dot_latex,
     render_dot_texinfo,
 )
-from sphinx.util import md5
 from sphinx.util.docutils import SphinxDirective
-from sphinx.util.typing import OptionSpec
-from sphinx.writers.html import HTML5Translator
-from sphinx.writers.latex import LaTeXTranslator
-from sphinx.writers.texinfo import TexinfoTranslator
+
+if TYPE_CHECKING:
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+    from sphinx.environment import BuildEnvironment
+    from sphinx.util.typing import OptionSpec
+    from sphinx.writers.html import HTML5Translator
+    from sphinx.writers.latex import LaTeXTranslator
+    from sphinx.writers.texinfo import TexinfoTranslator
 
 module_sig_re = re.compile(r'''^(?:([\w.]*)\.)?  # module names
                            (\w+)  \s* $          # class/final module name
@@ -139,7 +143,7 @@ class InheritanceGraph:
     """
     def __init__(self, class_names: list[str], currmodule: str, show_builtins: bool = False,
                  private_bases: bool = False, parts: int = 0,
-                 aliases: dict[str, str] | None = None, top_classes: list[Any] = [],
+                 aliases: dict[str, str] | None = None, top_classes: Sequence[Any] = (),
                  ) -> None:
         """*class_names* is a list of child classes to show bases from.
 
@@ -151,8 +155,8 @@ class InheritanceGraph:
         self.class_info = self._class_info(classes, show_builtins,
                                            private_bases, parts, aliases, top_classes)
         if not self.class_info:
-            raise InheritanceException('No classes found for '
-                                       'inheritance diagram')
+            msg = 'No classes found for inheritance diagram'
+            raise InheritanceException(msg)
 
     def _import_classes(self, class_names: list[str], currmodule: str) -> list[Any]:
         """Import a list of classes."""
@@ -162,7 +166,7 @@ class InheritanceGraph:
         return classes
 
     def _class_info(self, classes: list[Any], show_builtins: bool, private_bases: bool,
-                    parts: int, aliases: dict[str, str], top_classes: list[Any],
+                    parts: int, aliases: dict[str, str] | None, top_classes: Sequence[Any],
                     ) -> list[tuple[str, str, list[str], str]]:
         """Return name and bases for all classes that are ancestors of
         *classes*.
@@ -218,7 +222,7 @@ class InheritanceGraph:
         for cls in classes:
             recurse(cls)
 
-        return list(all_classes.values())
+        return list(all_classes.values())  # type: ignore[arg-type]
 
     def class_name(
         self, cls: Any, parts: int = 0, aliases: dict[str, str] | None = None,
@@ -272,9 +276,11 @@ class InheritanceGraph:
     def _format_graph_attrs(self, attrs: dict[str, Any]) -> str:
         return ''.join(['%s=%s;\n' % x for x in sorted(attrs.items())])
 
-    def generate_dot(self, name: str, urls: dict[str, str] = {},
+    def generate_dot(self, name: str, urls: dict[str, str] | None = None,
                      env: BuildEnvironment | None = None,
-                     graph_attrs: dict = {}, node_attrs: dict = {}, edge_attrs: dict = {},
+                     graph_attrs: dict | None = None,
+                     node_attrs: dict | None = None,
+                     edge_attrs: dict | None = None,
                      ) -> str:
         """Generate a graphviz dot graph from the classes that were passed in
         to __init__.
@@ -286,12 +292,17 @@ class InheritanceGraph:
         *graph_attrs*, *node_attrs*, *edge_attrs* are dictionaries containing
         key/value pairs to pass on as graphviz properties.
         """
+        if urls is None:
+            urls = {}
         g_attrs = self.default_graph_attrs.copy()
         n_attrs = self.default_node_attrs.copy()
         e_attrs = self.default_edge_attrs.copy()
-        g_attrs.update(graph_attrs)
-        n_attrs.update(node_attrs)
-        e_attrs.update(edge_attrs)
+        if graph_attrs is not None:
+            g_attrs.update(graph_attrs)
+        if node_attrs is not None:
+            n_attrs.update(node_attrs)
+        if edge_attrs is not None:
+            e_attrs.update(edge_attrs)
         if env:
             g_attrs.update(env.config.inheritance_graph_attrs)
             n_attrs.update(env.config.inheritance_node_attrs)
@@ -360,7 +371,7 @@ class InheritanceDiagram(SphinxDirective):
         # Create a graph starting with the list of classes
         try:
             graph = InheritanceGraph(
-                class_names, self.env.ref_context.get('py:module'),
+                class_names, self.env.ref_context.get('py:module'),  # type: ignore[arg-type]
                 parts=node['parts'],
                 private_bases='private-bases' in self.options,
                 aliases=self.config.inheritance_alias,
@@ -373,8 +384,8 @@ class InheritanceDiagram(SphinxDirective):
         # references to real URLs later.  These nodes will eventually be
         # removed from the doctree after we're done with them.
         for name in graph.get_all_class_names():
-            refnodes, x = class_role(  # type: ignore
-                'class', ':class:`%s`' % name, name, 0, self.state)  # type: ignore
+            refnodes, x = class_role(  # type: ignore[call-arg,misc]
+                'class', ':class:`%s`' % name, name, 0, self.state)  # type: ignore[arg-type]
             node.extend(refnodes)
         # Store the graph object so we can use it to generate the
         # dot file later
@@ -391,7 +402,7 @@ class InheritanceDiagram(SphinxDirective):
 
 def get_graph_hash(node: inheritance_diagram) -> str:
     encoded = (node['content'] + str(node['parts'])).encode()
-    return md5(encoded).hexdigest()[-10:]
+    return hashlib.md5(encoded, usedforsecurity=False).hexdigest()[-10:]
 
 
 def html_visit_inheritance_diagram(self: HTML5Translator, node: inheritance_diagram) -> None:
@@ -411,13 +422,16 @@ def html_visit_inheritance_diagram(self: HTML5Translator, node: inheritance_diag
     pending_xrefs = cast(Iterable[addnodes.pending_xref], node)
     for child in pending_xrefs:
         if child.get('refuri') is not None:
-            if graphviz_output_format == 'SVG':
-                urls[child['reftitle']] = "../" + child.get('refuri')
+            # Construct the name from the URI if the reference is external via intersphinx
+            if not child.get('internal', True):
+                refname = child['refuri'].rsplit('#', 1)[-1]
             else:
-                urls[child['reftitle']] = child.get('refuri')
+                refname = child['reftitle']
+
+            urls[refname] = child.get('refuri')
         elif child.get('refid') is not None:
             if graphviz_output_format == 'SVG':
-                urls[child['reftitle']] = '../' + current_filename + '#' + child.get('refid')
+                urls[child['reftitle']] = current_filename + '#' + child.get('refid')
             else:
                 urls[child['reftitle']] = '#' + child.get('refid')
 

sphinx/ext/intersphinx.py

@@ -25,7 +25,7 @@ import re
 import sys
 import time
 from os import path
-from typing import IO, TYPE_CHECKING, Any, Iterable, cast
+from typing import TYPE_CHECKING, cast
 from urllib.parse import urlsplit, urlunsplit
 
 from docutils import nodes
@@ -42,8 +42,9 @@ from sphinx.util.docutils import CustomReSTDispatcher, SphinxRole
 from sphinx.util.inventory import InventoryFile
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable
     from types import ModuleType
-    from typing import Tuple, Union
+    from typing import IO, Any, Union
 
     from docutils.nodes import Node, TextElement, system_message
     from docutils.utils import Reporter
@@ -54,7 +55,7 @@ if TYPE_CHECKING:
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import Inventory, InventoryItem, RoleFunction
 
-    InventoryCacheEntry = Tuple[Union[str, None], int, Inventory]
+    InventoryCacheEntry = tuple[Union[str, None], int, Inventory]
 
 logger = logging.getLogger(__name__)
 
@@ -67,10 +68,10 @@ class InventoryAdapter:
 
         if not hasattr(env, 'intersphinx_cache'):
             # initial storage when fetching inventories before processing
-            self.env.intersphinx_cache = {}  # type: ignore
+            self.env.intersphinx_cache = {}  # type: ignore[attr-defined]
 
-            self.env.intersphinx_inventory = {}  # type: ignore
-            self.env.intersphinx_named_inventory = {}  # type: ignore
+            self.env.intersphinx_inventory = {}  # type: ignore[attr-defined]
+            self.env.intersphinx_named_inventory = {}  # type: ignore[attr-defined]
 
     @property
     def cache(self) -> dict[str, InventoryCacheEntry]:
@@ -82,19 +83,19 @@ class InventoryAdapter:
         - Element two is a time value for cache invalidation, a float
         - Element three is the loaded remote inventory, type Inventory
         """
-        return self.env.intersphinx_cache  # type: ignore
+        return self.env.intersphinx_cache  # type: ignore[attr-defined]
 
     @property
     def main_inventory(self) -> Inventory:
-        return self.env.intersphinx_inventory  # type: ignore
+        return self.env.intersphinx_inventory  # type: ignore[attr-defined]
 
     @property
     def named_inventory(self) -> dict[str, Inventory]:
-        return self.env.intersphinx_named_inventory  # type: ignore
+        return self.env.intersphinx_named_inventory  # type: ignore[attr-defined]
 
     def clear(self) -> None:
-        self.env.intersphinx_inventory.clear()  # type: ignore
-        self.env.intersphinx_named_inventory.clear()  # type: ignore
+        self.env.intersphinx_inventory.clear()  # type: ignore[attr-defined]
+        self.env.intersphinx_named_inventory.clear()  # type: ignore[attr-defined]
 
 
 def _strip_basic_auth(url: str) -> str:
@@ -118,7 +119,7 @@ def _strip_basic_auth(url: str) -> str:
     return urlunsplit(frags)
 
 
-def _read_from_url(url: str, config: Config | None = None) -> IO:
+def _read_from_url(url: str, *, config: Config) -> IO:
     """Reads data from *url* with an HTTP *GET*.
 
     This function supports fetching from resources which use basic HTTP auth as
@@ -174,15 +175,14 @@ def fetch_inventory(app: Sphinx, uri: str, inv: str) -> Inventory:
     """Fetch, parse and return an intersphinx inventory file."""
     # both *uri* (base URI of the links to generate) and *inv* (actual
     # location of the inventory file) can be local or remote URIs
-    localuri = '://' not in uri
-    if not localuri:
+    if '://' in uri:
         # case: inv URI points to remote resource; strip any existing auth
         uri = _strip_basic_auth(uri)
     try:
         if '://' in inv:
             f = _read_from_url(inv, config=app.config)
         else:
-            f = open(path.join(app.srcdir, inv), 'rb')
+            f = open(path.join(app.srcdir, inv), 'rb')  # NoQA: SIM115
     except Exception as err:
         err.args = ('intersphinx inventory %r not fetchable due to %s: %s',
                     inv, err.__class__, str(err))
@@ -197,8 +197,7 @@ def fetch_inventory(app: Sphinx, uri: str, inv: str) -> Inventory:
                     uri = path.dirname(newinv)
         with f:
             try:
-                join = path.join if localuri else posixpath.join
-                invdata = InventoryFile.load(f, uri, join)
+                invdata = InventoryFile.load(f, uri, posixpath.join)
             except ValueError as exc:
                 raise ValueError('unknown or unsupported inventory version: %r' % exc) from exc
     except Exception as err:
@@ -298,7 +297,7 @@ def _create_element_from_result(domain: Domain, inv_name: str | None,
     proj, version, uri, dispname = data
     if '://' not in uri and node.get('refdoc'):
         # get correct path in case of subdirectories
-        uri = path.join(relative_path(node['refdoc'], '.'), uri)
+        uri = posixpath.join(relative_path(node['refdoc'], '.'), uri)
     if version:
         reftitle = _('(in %s v%s)') % (proj, version)
     else:
@@ -429,7 +428,7 @@ def _resolve_reference(env: BuildEnvironment, inv_name: str | None, inventory: I
                 and (domain_name + ":*") in env.config.intersphinx_disabled_reftypes:
             return None
         domain = env.get_domain(domain_name)
-        objtypes = domain.objtypes_for_role(typ)
+        objtypes = domain.objtypes_for_role(typ) or ()
         if not objtypes:
             return None
         return _resolve_reference_in_domain(env, inv_name, inventory,
@@ -554,15 +553,21 @@ class IntersphinxRole(SphinxRole):
 
     def get_inventory_and_name_suffix(self, name: str) -> tuple[str | None, str]:
         assert name.startswith('external'), name
-        assert name[8] in ':+', name
         # either we have an explicit inventory name, i.e,
         # :external+inv:role:        or
         # :external+inv:domain:role:
         # or we look in all inventories, i.e.,
         # :external:role:            or
         # :external:domain:role:
-        inv, suffix = IntersphinxRole._re_inv_ref.fullmatch(name, 8).group(2, 3)
-        return inv, suffix
+        suffix = name[9:]
+        if name[8] == '+':
+            inv_name, suffix = suffix.split(':', 1)
+            return inv_name, suffix
+        elif name[8] == ':':
+            return None, suffix
+        else:
+            msg = f'Malformed :external: role name: {name}'
+            raise ValueError(msg)
 
     def get_role_name(self, name: str) -> tuple[str, str] | None:
         names = name.split(':')
@@ -596,6 +601,7 @@ class IntersphinxRole(SphinxRole):
         domain = self.env.get_domain(role[0])
         if domain:
             role_func = domain.role(role[1])
+            assert role_func is not None
 
             return role_func(':'.join(role), self.rawtext, self.text, self.lineno,
                              self.inliner, self.options, self.content)
@@ -692,44 +698,45 @@ def setup(app: Sphinx) -> dict[str, Any]:
     }
 
 
-def inspect_main(argv: list[str]) -> None:
+def inspect_main(argv: list[str], /) -> int:
     """Debug functionality to print out an inventory"""
     if len(argv) < 1:
         print("Print out an inventory file.\n"
               "Error: must specify local path or URL to an inventory file.",
               file=sys.stderr)
-        raise SystemExit(1)
+        return 1
 
     class MockConfig:
         intersphinx_timeout: int | None = None
         tls_verify = False
-        tls_cacerts = None
-        user_agent = None
+        tls_cacerts: str | dict[str, str] | None = None
+        user_agent: str = ''
 
     class MockApp:
         srcdir = ''
         config = MockConfig()
 
-        def warn(self, msg: str) -> None:
-            print(msg, file=sys.stderr)
-
     try:
         filename = argv[0]
-        invdata = fetch_inventory(MockApp(), '', filename)  # type: ignore
-        for key in sorted(invdata or {}):
+        inv_data = fetch_inventory(MockApp(), '', filename)  # type: ignore[arg-type]
+        for key in sorted(inv_data or {}):
             print(key)
-            for entry, einfo in sorted(invdata[key].items()):
-                print('\t%-40s %s%s' % (entry,
-                                        '%-40s: ' % einfo[3] if einfo[3] != '-' else '',
-                                        einfo[2]))
+            inv_entries = sorted(inv_data[key].items())
+            for entry, (_proj, _ver, url_path, display_name) in inv_entries:
+                display_name = display_name * (display_name != '-')
+                print(f'    {entry:<40} {display_name:<40}: {url_path}')
     except ValueError as exc:
-        print(exc.args[0] % exc.args[1:])
+        print(exc.args[0] % exc.args[1:], file=sys.stderr)
+        return 1
     except Exception as exc:
-        print('Unknown error: %r' % exc)
+        print(f'Unknown error: {exc!r}', file=sys.stderr)
+        return 1
+    else:
+        return 0
 
 
 if __name__ == '__main__':
     import logging as _logging
     _logging.basicConfig()
 
-    inspect_main(argv=sys.argv[1:])
+    raise SystemExit(inspect_main(sys.argv[1:]))

sphinx/ext/linkcode.py

@@ -2,17 +2,20 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
-from docutils.nodes import Node
 
 import sphinx
 from sphinx import addnodes
-from sphinx.application import Sphinx
 from sphinx.errors import SphinxError
 from sphinx.locale import _
 
+if TYPE_CHECKING:
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+
 
 class LinkcodeError(SphinxError):
     category = "linkcode error"
@@ -23,8 +26,8 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
 
     resolve_target = getattr(env.config, 'linkcode_resolve', None)
     if not callable(env.config.linkcode_resolve):
-        raise LinkcodeError(
-            "Function `linkcode_resolve` is not given in conf.py")
+        msg = 'Function `linkcode_resolve` is not given in conf.py'
+        raise LinkcodeError(msg)
     assert resolve_target is not None  # for mypy
 
     domain_keys = {

sphinx/ext/mathjax.py

@@ -8,17 +8,20 @@ This requires the MathJax JavaScript library on your webserver/computer.
 from __future__ import annotations
 
 import json
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
 
 import sphinx
-from sphinx.application import Sphinx
+from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.domains.math import MathDomain
 from sphinx.errors import ExtensionError
 from sphinx.locale import _
 from sphinx.util.math import get_node_equation_number
-from sphinx.writers.html import HTML5Translator
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.writers.html import HTML5Translator
 
 # more information for mathjax secure url is here:
 # https://docs.mathjax.org/en/latest/start.html#secure-access-to-the-cdn
@@ -46,7 +49,7 @@ def html_visit_displaymath(self: HTML5Translator, node: nodes.math_block) -> Non
     if node['number']:
         number = get_node_equation_number(self, node)
         self.body.append('<span class="eqno">(%s)' % number)
-        self.add_permalink_ref(node, _('Permalink to this equation'))
+        self.add_permalink_ref(node, _('Link to this equation'))
         self.body.append('</span>')
     self.body.append(self.builder.config.mathjax_display[0])
     parts = [prt for prt in node.astext().split('\n\n') if prt.strip()]
@@ -75,10 +78,11 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: dict
     ):
         return
     if not app.config.mathjax_path:
-        raise ExtensionError('mathjax_path config value must be set for the '
-                             'mathjax extension to work')
+        msg = 'mathjax_path config value must be set for the mathjax extension to work'
+        raise ExtensionError(msg)
 
     domain = cast(MathDomain, app.env.get_domain('math'))
+    builder = cast(StandaloneHTMLBuilder, app.builder)
     if app.registry.html_assets_policy == 'always' or domain.has_equations(pagename):
         # Enable mathjax only if equations exists
         if app.config.mathjax2_config:
@@ -87,10 +91,10 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: dict
                     'mathjax_config/mathjax2_config does not work '
                     'for the current MathJax version, use mathjax3_config instead')
             body = 'MathJax.Hub.Config(%s)' % json.dumps(app.config.mathjax2_config)
-            app.add_js_file(None, type='text/x-mathjax-config', body=body)
+            builder.add_js_file('', type='text/x-mathjax-config', body=body)
         if app.config.mathjax3_config:
             body = 'window.MathJax = %s' % json.dumps(app.config.mathjax3_config)
-            app.add_js_file(None, body=body)
+            builder.add_js_file('', body=body)
 
         options = {}
         if app.config.mathjax_options:
@@ -102,7 +106,7 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: dict
             else:
                 # Load other MathJax via "async" method
                 options['async'] = 'async'
-        app.add_js_file(app.config.mathjax_path, **options)
+        builder.add_js_file(app.config.mathjax_path, **options)
 
 
 def setup(app: Sphinx) -> dict[str, Any]:

sphinx/ext/napoleon/__init__.py

@@ -367,7 +367,7 @@ def _process_docstring(app: Sphinx, what: str, name: str, obj: Any,
         The object to which the docstring belongs.
     options : sphinx.ext.autodoc.Options
         The options given to the directive: an object with attributes
-        inherited_members, undoc_members, show_inheritance and noindex that
+        inherited_members, undoc_members, show_inheritance and no_index that
         are True if the flag option of same name was given to the auto
         directive.
     lines : list of str
@@ -421,7 +421,7 @@ def _skip_member(app: Sphinx, what: str, name: str, obj: Any,
         does not override the decision
     options : sphinx.ext.autodoc.Options
         The options given to the directive: an object with attributes
-        inherited_members, undoc_members, show_inheritance and noindex that
+        inherited_members, undoc_members, show_inheritance and no_index that
         are True if the flag option of same name was given to the auto
         directive.
 
@@ -453,7 +453,7 @@ def _skip_member(app: Sphinx, what: str, name: str, obj: Any,
                 except Exception:
                     cls_is_owner = False
                 else:
-                    cls_is_owner = (cls and hasattr(cls, name) and  # type: ignore
+                    cls_is_owner = (cls and hasattr(cls, name) and  # type: ignore[assignment]
                                     name in cls.__dict__)
             else:
                 cls_is_owner = False