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

sphinx/util/typing.py

@@ -4,22 +4,26 @@ from __future__ import annotations
 
 import sys
 import typing
+from collections.abc import Sequence
 from struct import Struct
 from types import TracebackType
-from typing import Any, Callable, Dict, ForwardRef, List, Tuple, TypeVar, Union
+from typing import TYPE_CHECKING, Any, Callable, ForwardRef, TypeVar, Union
 
 from docutils import nodes
 from docutils.parsers.rst.states import Inliner
 
+if TYPE_CHECKING:
+    import enum
+
 try:
-    from types import UnionType  # type: ignore  # python 3.10 or above
+    from types import UnionType  # type: ignore[attr-defined] # python 3.10 or above
 except ImportError:
     UnionType = None
 
-# builtin classes that have incorrect __module__
+# classes that have incorrect __module__
 INVALID_BUILTIN_CLASSES = {
-    Struct: 'struct.Struct',  # Before Python 3.9
-    TracebackType: 'types.TracebackType',
+    Struct: 'struct.Struct',  # Struct.__module__ == '_struct'
+    TracebackType: 'types.TracebackType',  # TracebackType.__module__ == 'builtins'
 }
 
 
@@ -41,23 +45,23 @@ NoneType = type(None)
 PathMatcher = Callable[[str], bool]
 
 # common role functions
-RoleFunction = Callable[[str, str, str, int, Inliner, Dict[str, Any], List[str]],
-                        Tuple[List[nodes.Node], List[nodes.system_message]]]
+RoleFunction = Callable[[str, str, str, int, Inliner, dict[str, Any], Sequence[str]],
+                        tuple[list[nodes.Node], list[nodes.system_message]]]
 
 # A option spec for directive
-OptionSpec = Dict[str, Callable[[str], Any]]
+OptionSpec = dict[str, Callable[[str], Any]]
 
 # title getter functions for enumerable nodes (see sphinx.domains.std)
 TitleGetter = Callable[[nodes.Node], str]
 
 # inventory data on memory
-InventoryItem = Tuple[
+InventoryItem = tuple[
     str,  # project name
     str,  # project version
     str,  # URL
     str,  # display name
 ]
-Inventory = Dict[str, Dict[str, InventoryItem]]
+Inventory = dict[str, dict[str, InventoryItem]]
 
 
 def get_type_hints(
@@ -80,8 +84,7 @@ def get_type_hints(
         # Failed to evaluate ForwardRef (maybe not runtime checkable)
         return safe_getattr(obj, '__annotations__', {})
     except TypeError:
-        # Invalid object is given. But try to get __annotations__ as a fallback for
-        # the code using type union operator (PEP 604) in python 3.9 or below.
+        # Invalid object is given. But try to get __annotations__ as a fallback.
         return safe_getattr(obj, '__annotations__', {})
     except KeyError:
         # a broken class found (refs: https://github.com/sphinx-doc/sphinx/issues/8084)
@@ -140,6 +143,9 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
                 return ' | '.join(restify(a, mode) for a in cls.__args__)
         elif cls.__module__ in ('__builtin__', 'builtins'):
             if hasattr(cls, '__args__'):
+                if not cls.__args__:  # Empty tuple, list, ...
+                    return fr':py:class:`{cls.__name__}`\ [{cls.__args__!r}]'
+
                 concatenated_args = ', '.join(restify(arg, mode) for arg in cls.__args__)
                 return fr':py:class:`{cls.__name__}`\ [{concatenated_args}]'
             else:
@@ -162,7 +168,7 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
                 return ':py:obj:`~typing.Union`\\ [%s]' % args
         elif inspect.isgenericalias(cls):
             if isinstance(cls.__origin__, typing._SpecialForm):  # type: ignore[attr-defined]
-                text = restify(cls.__origin__, mode)  # type: ignore
+                text = restify(cls.__origin__, mode)  # type: ignore[attr-defined,arg-type]
             elif getattr(cls, '_name', None):
                 cls_name = cls._name  # type: ignore[attr-defined]
                 if cls.__module__ == 'typing':
@@ -183,7 +189,14 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
                 args = ', '.join(restify(a, mode) for a in cls.__args__[:-1])
                 text += fr"\ [[{args}], {restify(cls.__args__[-1], mode)}]"
             elif cls.__module__ == 'typing' and getattr(origin, '_name', None) == 'Literal':
-                text += r"\ [%s]" % ', '.join(repr(a) for a in cls.__args__)
+                literal_args = []
+                for a in cls.__args__:
+                    if inspect.isenumattribute(a):
+                        literal_args.append(_format_literal_enum_arg(a, mode=mode))
+                    else:
+                        literal_args.append(repr(a))
+                text += r"\ [%s]" % ', '.join(literal_args)
+                del literal_args
             elif cls.__args__:
                 text += r"\ [%s]" % ", ".join(restify(a, mode) for a in cls.__args__)
 
@@ -232,8 +245,9 @@ def stringify_annotation(
     from sphinx.util.inspect import isNewType  # lazy loading
 
     if mode not in {'fully-qualified-except-typing', 'fully-qualified', 'smart'}:
-        raise ValueError("'mode' must be one of 'fully-qualified-except-typing', "
-                         f"'fully-qualified', or 'smart'; got {mode!r}.")
+        msg = ("'mode' must be one of 'fully-qualified-except-typing', "
+               f"'fully-qualified', or 'smart'; got {mode!r}.")
+        raise ValueError(msg)
 
     if mode == 'smart':
         module_prefix = '~'
@@ -275,8 +289,12 @@ def stringify_annotation(
     elif str(annotation).startswith('typing.Annotated'):  # for py310+
         pass
     elif annotation_module == 'builtins' and annotation_qualname:
-        if hasattr(annotation, '__args__'):  # PEP 585 generic
-            return repr(annotation)
+        if (args := getattr(annotation, '__args__', None)) is not None:  # PEP 585 generic
+            if not args:  # Empty tuple, list, ...
+                return repr(annotation)
+
+            concatenated_args = ', '.join(stringify_annotation(arg, mode) for arg in args)
+            return f'{annotation_qualname}[{concatenated_args}]'
         else:
             return annotation_qualname
     elif annotation is Ellipsis:
@@ -330,7 +348,21 @@ def stringify_annotation(
             returns = stringify_annotation(annotation_args[-1], mode)
             return f'{module_prefix}Callable[[{args}], {returns}]'
         elif qualname == 'Literal':
-            args = ', '.join(repr(a) for a in annotation_args)
+            from sphinx.util.inspect import isenumattribute  # lazy loading
+
+            def format_literal_arg(arg):
+                if isenumattribute(arg):
+                    enumcls = arg.__class__
+
+                    if mode == 'smart':
+                        # MyEnum.member
+                        return f'{enumcls.__qualname__}.{arg.name}'
+
+                    # module.MyEnum.member
+                    return f'{enumcls.__module__}.{enumcls.__qualname__}.{arg.name}'
+                return repr(arg)
+
+            args = ', '.join(map(format_literal_arg, annotation_args))
             return f'{module_prefix}Literal[{args}]'
         elif str(annotation).startswith('typing.Annotated'):  # for py39+
             return stringify_annotation(annotation_args[0], mode)
@@ -344,6 +376,14 @@ def stringify_annotation(
     return module_prefix + qualname
 
 
+def _format_literal_enum_arg(arg: enum.Enum, /, *, mode: str) -> str:
+    enum_cls = arg.__class__
+    if mode == 'smart' or enum_cls.__module__ == 'typing':
+        return f':py:attr:`~{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
+    else:
+        return f':py:attr:`{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
+
+
 # deprecated name -> (object to return, canonical path or empty string)
 _DEPRECATED_OBJECTS = {
     'stringify': (stringify_annotation, 'sphinx.util.typing.stringify_annotation'),
@@ -352,7 +392,8 @@ _DEPRECATED_OBJECTS = {
 
 def __getattr__(name):
     if name not in _DEPRECATED_OBJECTS:
-        raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+        msg = f'module {__name__!r} has no attribute {name!r}'
+        raise AttributeError(msg)
 
     from sphinx.deprecation import _deprecation_warning
 

sphinx/versioning.py

@@ -5,14 +5,16 @@ import pickle
 from itertools import product, zip_longest
 from operator import itemgetter
 from os import path
-from typing import TYPE_CHECKING, Any, Iterator
+from typing import TYPE_CHECKING, Any
 from uuid import uuid4
 
-from docutils.nodes import Node
-
 from sphinx.transforms import SphinxTransform
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from docutils.nodes import Node
+
     from sphinx.application import Sphinx
 
 try:
@@ -89,7 +91,7 @@ def merge_doctrees(old: Node, new: Node, condition: Any) -> Iterator[Node]:
     # choose the old node with the best ratio for each new node and set the uid
     # as long as the ratio is under a certain value, in which case we consider
     # them not changed but different
-    ratios = sorted(ratios.items(), key=itemgetter(1))  # type: ignore
+    ratios = sorted(ratios.items(), key=itemgetter(1))  # type: ignore[assignment]
     for (old_node, new_node), ratio in ratios:
         if new_node in seen:
             continue

sphinx/writers/html.py

@@ -39,6 +39,6 @@ class HTMLWriter(Writer):
                      'body_pre_docinfo', 'docinfo', 'body', 'fragment',
                      'body_suffix', 'meta', 'title', 'subtitle', 'header',
                      'footer', 'html_prolog', 'html_head', 'html_title',
-                     'html_subtitle', 'html_body', ):
+                     'html_subtitle', 'html_body'):
             setattr(self, attr, getattr(visitor, attr, None))
         self.clean_meta = ''.join(self.visitor.meta[2:])

sphinx/writers/html5.py

@@ -6,20 +6,22 @@ import os
 import posixpath
 import re
 import urllib.parse
-from typing import TYPE_CHECKING, Iterable, cast
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
-from docutils.nodes import Element, Node, Text
 from docutils.writers.html5_polyglot import HTMLTranslator as BaseTranslator
 
 from sphinx import addnodes
-from sphinx.builders import Builder
 from sphinx.locale import _, __, admonitionlabels
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxTranslator
 from sphinx.util.images import get_image_size
 
 if TYPE_CHECKING:
+    from docutils.nodes import Element, Node, Text
+
+    from sphinx.builders import Builder
     from sphinx.builders.html import StandaloneHTMLBuilder
 
 
@@ -95,7 +97,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
     def depart_desc_signature(self, node: Element) -> None:
         self.protect_literal_text -= 1
         if not node.get('is_multiline'):
-            self.add_permalink_ref(node, _('Permalink to this definition'))
+            self.add_permalink_ref(node, _('Link to this definition'))
         self.body.append('</dt>\n')
 
     def visit_desc_signature_line(self, node: Element) -> None:
@@ -104,7 +106,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
     def depart_desc_signature_line(self, node: Element) -> None:
         if node.get('add_permalink'):
             # the permalink info is on the parent desc_signature node
-            self.add_permalink_ref(node.parent, _('Permalink to this definition'))
+            self.add_permalink_ref(node.parent, _('Link to this definition'))
         self.body.append('<br />')
 
     def visit_desc_content(self, node: Element) -> None:
@@ -336,7 +338,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
         self.depart_reference(node)
 
     # overwritten -- we don't want source comments to show up in the HTML
-    def visit_comment(self, node: Element) -> None:  # type: ignore
+    def visit_comment(self, node: Element) -> None:  # type: ignore[override]
         raise nodes.SkipNode
 
     # overwritten
@@ -408,10 +410,11 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
                 append_fignumber(figtype, node['ids'][0])
 
     def add_permalink_ref(self, node: Element, title: str) -> None:
+        icon = self.config.html_permalinks_icon
         if node['ids'] and self.config.html_permalinks and self.builder.add_permalinks:
-            format = '<a class="headerlink" href="#%s" title="%s">%s</a>'
-            self.body.append(format % (node['ids'][0], title,
-                                       self.config.html_permalinks_icon))
+            self.body.append(
+                f'<a class="headerlink" href="#{node["ids"][0]}" title="{title}">{icon}</a>',
+            )
 
     # overwritten
     def visit_bullet_list(self, node: Element) -> None:
@@ -456,7 +459,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
         else:
             if isinstance(node.parent.parent.parent, addnodes.glossary):
                 # add permalink if glossary terms
-                self.add_permalink_ref(node, _('Permalink to this term'))
+                self.add_permalink_ref(node, _('Link to this term'))
 
             self.body.append('</dt>')
 
@@ -479,16 +482,16 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
                 node.parent.hasattr('ids') and node.parent['ids']):
             # add permalink anchor
             if close_tag.startswith('</h'):
-                self.add_permalink_ref(node.parent, _('Permalink to this heading'))
+                self.add_permalink_ref(node.parent, _('Link to this heading'))
             elif close_tag.startswith('</a></h'):
                 self.body.append('</a><a class="headerlink" href="#%s" ' %
                                  node.parent['ids'][0] +
                                  'title="{}">{}'.format(
-                                     _('Permalink to this heading'),
+                                     _('Link to this heading'),
                                      self.config.html_permalinks_icon))
             elif isinstance(node.parent, nodes.table):
                 self.body.append('</span>')
-                self.add_permalink_ref(node.parent, _('Permalink to this table'))
+                self.add_permalink_ref(node.parent, _('Link to this table'))
         elif isinstance(node.parent, nodes.table):
             self.body.append('</span>')
 
@@ -531,11 +534,11 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
 
         # append permalink if available
         if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
-            self.add_permalink_ref(node.parent, _('Permalink to this code'))
+            self.add_permalink_ref(node.parent, _('Link to this code'))
         elif isinstance(node.parent, nodes.figure):
-            self.add_permalink_ref(node.parent, _('Permalink to this image'))
+            self.add_permalink_ref(node.parent, _('Link to this image'))
         elif node.parent.get('toctree'):
-            self.add_permalink_ref(node.parent.parent, _('Permalink to this toctree'))
+            self.add_permalink_ref(node.parent.parent, _('Link to this toctree'))
 
         if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
             self.body.append('</div>\n')
@@ -669,7 +672,8 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
             # but it tries the final file name, which does not necessarily exist
             # yet at the time the HTML file is written.
             if not ('width' in node and 'height' in node):
-                size = get_image_size(os.path.join(self.builder.srcdir, olduri))
+                path = os.path.join(self.builder.srcdir, olduri)  # type: ignore[has-type]
+                size = get_image_size(path)
                 if size is None:
                     logger.warning(
                         __('Could not obtain image size. :scale: option is ignored.'),
@@ -879,7 +883,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
         else:
             node['classes'].append('row-odd')
         self.body.append(self.starttag(node, 'tr', ''))
-        node.column = 0  # type: ignore
+        node.column = 0  # type: ignore[attr-defined]
 
     def visit_field_list(self, node: Element) -> None:
         self._fieldlist_row_indices.append(0)
@@ -897,25 +901,29 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
             node['classes'].append('field-odd')
 
     def visit_math(self, node: Element, math_env: str = '') -> None:
-        name = self.builder.math_renderer_name
+        # see validate_math_renderer
+        name: str = self.builder.math_renderer_name  # type: ignore[assignment]
         visit, _ = self.builder.app.registry.html_inline_math_renderers[name]
         visit(self, node)
 
     def depart_math(self, node: Element, math_env: str = '') -> None:
-        name = self.builder.math_renderer_name
+        # see validate_math_renderer
+        name: str = self.builder.math_renderer_name  # type: ignore[assignment]
         _, depart = self.builder.app.registry.html_inline_math_renderers[name]
-        if depart:  # type: ignore[truthy-function]
+        if depart:
             depart(self, node)
 
     def visit_math_block(self, node: Element, math_env: str = '') -> None:
-        name = self.builder.math_renderer_name
+        # see validate_math_renderer
+        name: str = self.builder.math_renderer_name  # type: ignore[assignment]
         visit, _ = self.builder.app.registry.html_block_math_renderers[name]
         visit(self, node)
 
     def depart_math_block(self, node: Element, math_env: str = '') -> None:
-        name = self.builder.math_renderer_name
+        # see validate_math_renderer
+        name: str = self.builder.math_renderer_name  # type: ignore[assignment]
         _, depart = self.builder.app.registry.html_block_math_renderers[name]
-        if depart:  # type: ignore[truthy-function]
+        if depart:
             depart(self, node)
 
     # See Docutils r9413