Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/domains/python/_object.py

@@ -2,13 +2,13 @@ from __future__ import annotations
 
 import contextlib
 import re
-from typing import TYPE_CHECKING, ClassVar
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.parsers.rst import directives
 
 from sphinx import addnodes
-from sphinx.addnodes import desc_signature, pending_xref, pending_xref_condition
+from sphinx.addnodes import pending_xref, pending_xref_condition
 from sphinx.directives import ObjectDescription
 from sphinx.domains.python._annotations import (
     _parse_annotation,
@@ -25,9 +25,13 @@ from sphinx.util.nodes import (
 )
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from typing import ClassVar
+
     from docutils.nodes import Node
     from docutils.parsers.rst.states import Inliner
 
+    from sphinx.addnodes import desc_signature
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import OptionSpec, TextlikeNode
 
@@ -35,13 +39,15 @@ logger = logging.getLogger(__name__)
 
 # REs for Python signatures
 py_sig_re = re.compile(
-    r'''^ ([\w.]*\.)?            # class name(s)
+    r"""^ ([\w.]*\.)?            # class name(s)
           (\w+)  \s*             # thing name
-          (?: \[\s*(.*)\s*])?    # optional: type parameters list
+          (?: \[\s*(.*?)\s*])?   # optional: type parameters list
           (?: \(\s*(.*)\s*\)     # optional: arguments
            (?:\s* -> \s* (.*))?  #           return annotation
           )? $                   # and nothing more
-          ''', re.VERBOSE)
+      """,
+    re.VERBOSE,
+)
 
 
 # This override allows our inline type specifiers to behave like :class: link
@@ -60,9 +66,16 @@ class PyXrefMixin:
     ) -> Node:
         # we use inliner=None to make sure we get the old behaviour with a single
         # pending_xref node
-        result = super().make_xref(rolename, domain, target,  # type: ignore[misc]
-                                   innernode, contnode,
-                                   env, inliner=None, location=None)
+        result = super().make_xref(  # type: ignore[misc]
+            rolename,
+            domain,
+            target,
+            innernode,
+            contnode,
+            env,
+            inliner=None,
+            location=None,
+        )
         if isinstance(result, pending_xref):
             assert env is not None
             result['refspecific'] = True
@@ -82,8 +95,10 @@ class PyXrefMixin:
 
                 shortname = target.split('.')[-1]
                 textnode = innernode('', shortname)  # type: ignore[call-arg]
-                contnodes = [pending_xref_condition('', '', textnode, condition='resolved'),
-                             pending_xref_condition('', '', *children, condition='*')]
+                contnodes = [
+                    pending_xref_condition('', '', textnode, condition='resolved'),
+                    pending_xref_condition('', '', *children, condition='*'),
+                ]
                 result.extend(contnodes)
 
         return result
@@ -116,8 +131,18 @@ class PyXrefMixin:
             if in_literal or self._delimiters_re.match(sub_target):
                 results.append(contnode or innernode(sub_target, sub_target))  # type: ignore[call-arg]
             else:
-                results.append(self.make_xref(rolename, domain, sub_target,
-                                              innernode, contnode, env, inliner, location))
+                results.append(
+                    self.make_xref(
+                        rolename,
+                        domain,
+                        sub_target,
+                        innernode,
+                        contnode,
+                        env,
+                        inliner,
+                        location,
+                    )
+                )
 
             if sub_target in {'Literal', 'typing.Literal', '~typing.Literal'}:
                 in_literal = True
@@ -138,8 +163,7 @@ class PyTypedField(PyXrefMixin, TypedField):
 
 
 class PyObject(ObjectDescription[tuple[str, str]]):
-    """
-    Description of a general Python object.
+    """Description of a general Python object.
 
     :cvar allow_nesting: Class is an object that allows for nested namespaces
     :vartype allow_nesting: bool
@@ -161,27 +185,55 @@ class PyObject(ObjectDescription[tuple[str, str]]):
     }
 
     doc_field_types = [
-        PyTypedField('parameter', label=_('Parameters'),
-                     names=('param', 'parameter', 'arg', 'argument',
-                            'keyword', 'kwarg', 'kwparam'),
-                     typerolename='class', typenames=('paramtype', 'type'),
-                     can_collapse=True),
-        PyTypedField('variable', label=_('Variables'),
-                     names=('var', 'ivar', 'cvar'),
-                     typerolename='class', typenames=('vartype',),
-                     can_collapse=True),
-        PyGroupedField('exceptions', label=_('Raises'), rolename='exc',
-                       names=('raises', 'raise', 'exception', 'except'),
-                       can_collapse=True),
-        Field('returnvalue', label=_('Returns'), has_arg=False,
-              names=('returns', 'return')),
-        PyField('returntype', label=_('Return type'), has_arg=False,
-                names=('rtype',), bodyrolename='class'),
+        PyTypedField(
+            'parameter',
+            label=_('Parameters'),
+            names=(
+                'param',
+                'parameter',
+                'arg',
+                'argument',
+                'keyword',
+                'kwarg',
+                'kwparam',
+            ),
+            typerolename='class',
+            typenames=('paramtype', 'type'),
+            can_collapse=True,
+        ),
+        PyTypedField(
+            'variable',
+            label=_('Variables'),
+            names=('var', 'ivar', 'cvar'),
+            typerolename='class',
+            typenames=('vartype',),
+            can_collapse=True,
+        ),
+        PyGroupedField(
+            'exceptions',
+            label=_('Raises'),
+            rolename='exc',
+            names=('raises', 'raise', 'exception', 'except'),
+            can_collapse=True,
+        ),
+        Field(
+            'returnvalue',
+            label=_('Returns'),
+            has_arg=False,
+            names=('returns', 'return'),
+        ),
+        PyField(
+            'returntype',
+            label=_('Return type'),
+            has_arg=False,
+            names=('rtype',),
+            bodyrolename='class',
+        ),
     ]
 
     allow_nesting = False
 
-    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
+    def get_signature_prefix(self, sig: str) -> Sequence[nodes.Node]:
         """May return a prefix to put before the object name in the
         signature.
         """
@@ -212,18 +264,17 @@ class PyObject(ObjectDescription[tuple[str, str]]):
         classname = self.env.ref_context.get('py:class')
         if classname:
             add_module = False
-            if prefix and (prefix == classname or
-                           prefix.startswith(classname + ".")):
+            if prefix and (prefix == classname or prefix.startswith(f'{classname}.')):
                 fullname = prefix + name
                 # class name is given again in the signature
-                prefix = prefix[len(classname):].lstrip('.')
+                prefix = prefix[len(classname) :].lstrip('.')
             elif prefix:
                 # class name is given in the signature, but different
                 # (shouldn't happen)
-                fullname = classname + '.' + prefix + name
+                fullname = f'{classname}.{prefix}{name}'
             else:
                 # class name is not given in the signature
-                fullname = classname + '.' + name
+                fullname = f'{classname}.{name}'
         else:
             add_module = True
             if prefix:
@@ -237,9 +288,11 @@ class PyObject(ObjectDescription[tuple[str, str]]):
         signode['class'] = classname
         signode['fullname'] = fullname
 
-        max_len = (self.env.config.python_maximum_signature_line_length
-                   or self.env.config.maximum_signature_line_length
-                   or 0)
+        max_len = (
+            self.config.python_maximum_signature_line_length
+            or self.config.maximum_signature_line_length
+            or 0
+        )
 
         # determine if the function arguments (without its type parameters)
         # should be formatted on a multiline or not by removing the width of
@@ -258,44 +311,72 @@ class PyObject(ObjectDescription[tuple[str, str]]):
             and (sig_len - (arglist_span[1] - arglist_span[0])) > max_len > 0
         )
 
+        trailing_comma = self.env.config.python_trailing_comma_in_multi_line_signatures
         sig_prefix = self.get_signature_prefix(sig)
         if sig_prefix:
             if type(sig_prefix) is str:
-                msg = ("Python directive method get_signature_prefix()"
-                       " must return a list of nodes."
-                       f" Return value was '{sig_prefix}'.")
+                msg = (
+                    'Python directive method get_signature_prefix()'
+                    ' must return a list of nodes.'
+                    f" Return value was '{sig_prefix}'."
+                )
                 raise TypeError(msg)
             signode += addnodes.desc_annotation(str(sig_prefix), '', *sig_prefix)
 
         if prefix:
             signode += addnodes.desc_addname(prefix, prefix)
-        elif modname and add_module and self.env.config.add_module_names:
-            nodetext = modname + '.'
+        elif modname and add_module and self.config.add_module_names:
+            nodetext = f'{modname}.'
             signode += addnodes.desc_addname(nodetext, nodetext)
 
         signode += addnodes.desc_name(name, name)
 
         if tp_list:
             try:
-                signode += _parse_type_list(tp_list, self.env, multi_line_type_parameter_list)
+                signode += _parse_type_list(
+                    tp_list,
+                    self.env,
+                    multi_line_type_parameter_list,
+                    trailing_comma,
+                )
             except Exception as exc:
-                logger.warning("could not parse tp_list (%r): %s", tp_list, exc,
-                               location=signode)
+                logger.warning(
+                    'could not parse tp_list (%r): %s', tp_list, exc, location=signode
+                )
 
         if arglist:
             try:
-                signode += _parse_arglist(arglist, self.env, multi_line_parameter_list)
-            except SyntaxError:
+                signode += _parse_arglist(
+                    arglist,
+                    self.env,
+                    multi_line_parameter_list,
+                    trailing_comma,
+                )
+            except SyntaxError as exc:
                 # fallback to parse arglist original parser
                 # (this may happen if the argument list is incorrectly used
                 # as a list of bases when documenting a class)
                 # it supports to represent optional arguments (ex. "func(foo [, bar])")
-                _pseudo_parse_arglist(signode, arglist, multi_line_parameter_list)
+                logger.debug(
+                    'syntax error in arglist (%r): %s', arglist, exc, location=signode
+                )
+                _pseudo_parse_arglist(
+                    signode,
+                    arglist,
+                    multi_line_parameter_list,
+                    trailing_comma,
+                )
             except (NotImplementedError, ValueError) as exc:
                 # duplicated parameter names raise ValueError and not a SyntaxError
-                logger.warning("could not parse arglist (%r): %s", arglist, exc,
-                               location=signode)
-                _pseudo_parse_arglist(signode, arglist, multi_line_parameter_list)
+                logger.warning(
+                    'could not parse arglist (%r): %s', arglist, exc, location=signode
+                )
+                _pseudo_parse_arglist(
+                    signode,
+                    arglist,
+                    multi_line_parameter_list,
+                    trailing_comma,
+                )
         else:
             if self.needs_arglist():
                 # for callables, add an empty parameter list
@@ -307,9 +388,9 @@ class PyObject(ObjectDescription[tuple[str, str]]):
 
         anno = self.options.get('annotation')
         if anno:
-            signode += addnodes.desc_annotation(' ' + anno, '',
-                                                addnodes.desc_sig_space(),
-                                                nodes.Text(anno))
+            signode += addnodes.desc_annotation(
+                f' {anno}', '', addnodes.desc_sig_space(), nodes.Text(anno)
+            )
 
         return fullname, prefix
 
@@ -329,10 +410,11 @@ class PyObject(ObjectDescription[tuple[str, str]]):
         msg = 'must be implemented in subclasses'
         raise NotImplementedError(msg)
 
-    def add_target_and_index(self, name_cls: tuple[str, str], sig: str,
-                             signode: desc_signature) -> None:
-        modname = self.options.get('module', self.env.ref_context.get('py:module'))
-        fullname = (modname + '.' if modname else '') + name_cls[0]
+    def add_target_and_index(
+        self, name_cls: tuple[str, str], sig: str, signode: desc_signature
+    ) -> None:
+        mod_name = self.options.get('module', self.env.ref_context.get('py:module'))
+        fullname = (f'{mod_name}.' if mod_name else '') + name_cls[0]
         node_id = make_id(self.env, self.state.document, '', fullname)
         signode['ids'].append(node_id)
         self.state.document.note_explicit_target(signode)
@@ -342,13 +424,19 @@ class PyObject(ObjectDescription[tuple[str, str]]):
 
         canonical_name = self.options.get('canonical')
         if canonical_name:
-            domain.note_object(canonical_name, self.objtype, node_id, aliased=True,
-                               location=signode)
+            domain.note_object(
+                canonical_name, self.objtype, node_id, aliased=True, location=signode
+            )
 
         if 'no-index-entry' not in self.options:
-            indextext = self.get_index_text(modname, name_cls)
-            if indextext:
-                self.indexnode['entries'].append(('single', indextext, node_id, '', None))
+            if index_text := self.get_index_text(mod_name, name_cls):
+                self.indexnode['entries'].append((
+                    'single',
+                    index_text,
+                    node_id,
+                    '',
+                    None,
+                ))
 
     def before_content(self) -> None:
         """Handle object nesting before content
@@ -398,8 +486,7 @@ class PyObject(ObjectDescription[tuple[str, str]]):
             with contextlib.suppress(IndexError):
                 classes.pop()
 
-        self.env.ref_context['py:class'] = (classes[-1] if len(classes) > 0
-                                            else None)
+        self.env.ref_context['py:class'] = classes[-1] if len(classes) > 0 else None
         if 'module' in self.options:
             modules = self.env.ref_context.setdefault('py:modules', [])
             if modules:
@@ -411,7 +498,7 @@ class PyObject(ObjectDescription[tuple[str, str]]):
         if not sig_node.get('_toc_parts'):
             return ''
 
-        config = self.env.app.config
+        config = self.config
         objtype = sig_node.parent.get('objtype')
         if config.add_function_parentheses and objtype in {'function', 'method'}:
             parens = '()'

sphinx/domains/rst.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING, Any, ClassVar
+from typing import TYPE_CHECKING
 
 from docutils.parsers.rst import directives
 
@@ -17,7 +17,9 @@ from sphinx.util.nodes import make_id, make_refnode
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Set
+    from typing import Any, ClassVar
 
+    from docutils import nodes
     from docutils.nodes import Element
 
     from sphinx.addnodes import desc_signature, pending_xref
@@ -32,9 +34,7 @@ dir_sig_re = re.compile(r'\.\. (.+?)::(.*)$')
 
 
 class ReSTMarkup(ObjectDescription[str]):
-    """
-    Description of generic reST markup.
-    """
+    """Description of generic reST markup."""
 
     option_spec: ClassVar[OptionSpec] = {
         'no-index': directives.flag,
@@ -46,7 +46,9 @@ class ReSTMarkup(ObjectDescription[str]):
         'nocontentsentry': directives.flag,
     }
 
-    def add_target_and_index(self, name: str, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(
+        self, name: str, sig: str, signode: desc_signature
+    ) -> None:
         node_id = make_id(self.env, self.state.document, self.objtype, name)
         signode['ids'].append(node_id)
         self.state.document.note_explicit_target(signode)
@@ -55,9 +57,14 @@ class ReSTMarkup(ObjectDescription[str]):
         domain.note_object(self.objtype, name, node_id, location=signode)
 
         if 'no-index-entry' not in self.options:
-            indextext = self.get_index_text(self.objtype, name)
-            if indextext:
-                self.indexnode['entries'].append(('single', indextext, node_id, '', None))
+            if index_text := self.get_index_text(self.objtype, name):
+                self.indexnode['entries'].append((
+                    'single',
+                    index_text,
+                    node_id,
+                    '',
+                    None,
+                ))
 
     def get_index_text(self, objectname: str, name: str) -> str:
         return ''
@@ -75,12 +82,11 @@ class ReSTMarkup(ObjectDescription[str]):
         if not sig_node.get('_toc_parts'):
             return ''
 
-        config = self.env.app.config
         objtype = sig_node.parent.get('objtype')
         *parents, name = sig_node['_toc_parts']
         if objtype == 'directive:option':
             return f':{name}:'
-        if config.toc_object_entries_show_parents in {'domain', 'all'}:
+        if self.config.toc_object_entries_show_parents in {'domain', 'all'}:
             name = ':'.join(sig_node['_toc_parts'])
         if objtype == 'role':
             return f':{name}:'
@@ -98,21 +104,19 @@ def parse_directive(d: str) -> tuple[str, str]:
     dir = d.strip()
     if not dir.startswith('.'):
         # Assume it is a directive without syntax
-        return (dir, '')
+        return dir, ''
     m = dir_sig_re.match(dir)
     if not m:
-        return (dir, '')
+        return dir, ''
     parsed_dir, parsed_args = m.groups()
     if parsed_args.strip():
-        return (parsed_dir.strip(), ' ' + parsed_args.strip())
+        return parsed_dir.strip(), ' ' + parsed_args.strip()
     else:
-        return (parsed_dir.strip(), '')
+        return parsed_dir.strip(), ''
 
 
 class ReSTDirective(ReSTMarkup):
-    """
-    Description of a reST directive.
-    """
+    """Description of a reST directive."""
 
     def handle_signature(self, sig: str, signode: desc_signature) -> str:
         name, args = parse_directive(sig)
@@ -138,9 +142,7 @@ class ReSTDirective(ReSTMarkup):
 
 
 class ReSTDirectiveOption(ReSTMarkup):
-    """
-    Description of an option for reST directive.
-    """
+    """Description of an option for reST directive."""
 
     option_spec: ClassVar[OptionSpec] = ReSTMarkup.option_spec.copy()
     option_spec.update({
@@ -157,13 +159,16 @@ class ReSTDirectiveOption(ReSTMarkup):
         signode['fullname'] = name.strip()
         signode += addnodes.desc_name(desc_name, desc_name)
         if argument:
-            signode += addnodes.desc_annotation(' ' + argument, ' ' + argument)
+            text = f' {argument}'
+            signode += addnodes.desc_annotation(text, text)
         if self.options.get('type'):
             text = ' (%s)' % self.options['type']
             signode += addnodes.desc_annotation(text, text)
         return name
 
-    def add_target_and_index(self, name: str, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(
+        self, name: str, sig: str, signode: desc_signature
+    ) -> None:
         domain = self.env.domains.restructuredtext_domain
 
         directive_name = self.current_directive
@@ -181,9 +186,17 @@ class ReSTDirectiveOption(ReSTMarkup):
 
         if directive_name:
             key = name[0].upper()
-            pair = [_('%s (directive)') % directive_name,
-                    _(':%s: (directive option)') % name]
-            self.indexnode['entries'].append(('pair', '; '.join(pair), node_id, '', key))
+            pair = [
+                _('%s (directive)') % directive_name,
+                _(':%s: (directive option)') % name,
+            ]
+            self.indexnode['entries'].append((
+                'pair',
+                '; '.join(pair),
+                node_id,
+                '',
+                key,
+            ))
         else:
             key = name[0].upper()
             text = _(':%s: (directive option)') % name
@@ -199,9 +212,7 @@ class ReSTDirectiveOption(ReSTMarkup):
 
 
 class ReSTRole(ReSTMarkup):
-    """
-    Description of a reST role.
-    """
+    """Description of a reST role."""
 
     def handle_signature(self, sig: str, signode: desc_signature) -> str:
         desc_name = f':{sig}:'
@@ -220,17 +231,17 @@ class ReSTDomain(Domain):
     label = 'reStructuredText'
 
     object_types = {
-        'directive':        ObjType(_('directive'),        'dir'),
+        'directive': ObjType(_('directive'), 'dir'),
         'directive:option': ObjType(_('directive-option'), 'dir'),
-        'role':             ObjType(_('role'),             'role'),
+        'role': ObjType(_('role'), 'role'),
     }
     directives = {
         'directive': ReSTDirective,
         'directive:option': ReSTDirectiveOption,
-        'role':      ReSTRole,
+        'role': ReSTRole,
     }
     roles = {
-        'dir':  XRefRole(),
+        'dir': XRefRole(),
         'role': XRefRole(),
     }
     initial_data: dict[str, dict[tuple[str, str], str]] = {
@@ -239,13 +250,21 @@ class ReSTDomain(Domain):
 
     @property
     def objects(self) -> dict[tuple[str, str], tuple[str, str]]:
-        return self.data.setdefault('objects', {})  # (objtype, fullname) -> (docname, node_id)
+        # (objtype, fullname) -> (docname, node_id)
+        return self.data.setdefault('objects', {})
 
-    def note_object(self, objtype: str, name: str, node_id: str, location: Any = None) -> None:
+    def note_object(
+        self, objtype: str, name: str, node_id: str, location: Any = None
+    ) -> None:
         if (objtype, name) in self.objects:
             docname, node_id = self.objects[objtype, name]
-            logger.warning(__('duplicate description of %s %s, other instance in %s'),
-                           objtype, name, docname, location=location)
+            logger.warning(
+                __('duplicate description of %s %s, other instance in %s'),
+                objtype,
+                name,
+                docname,
+                location=location,
+            )
 
         self.objects[objtype, name] = (self.env.docname, node_id)
 
@@ -260,9 +279,16 @@ class ReSTDomain(Domain):
             if doc in docnames:
                 self.objects[typ, name] = (doc, node_id)
 
-    def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
-                     typ: str, target: str, node: pending_xref, contnode: Element,
-                     ) -> Element | None:
+    def resolve_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | None:
         objtypes = self.objtypes_for_role(typ)
         if not objtypes:
             return None
@@ -270,22 +296,41 @@ class ReSTDomain(Domain):
             result = self.objects.get((objtype, target))
             if result:
                 todocname, node_id = result
-                return make_refnode(builder, fromdocname, todocname, node_id,
-                                    contnode, target + ' ' + objtype)
+                return make_refnode(
+                    builder,
+                    fromdocname,
+                    todocname,
+                    node_id,
+                    contnode,
+                    f'{target} {objtype}',
+                )
         return None
 
-    def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
-                         target: str, node: pending_xref, contnode: Element,
-                         ) -> list[tuple[str, Element]]:
-        results: list[tuple[str, Element]] = []
+    def resolve_any_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> list[tuple[str, nodes.reference]]:
+        results: list[tuple[str, nodes.reference]] = []
         for objtype in self.object_types:
             result = self.objects.get((objtype, target))
             if result:
                 todocname, node_id = result
-                results.append(
-                    ('rst:' + self.role_for_objtype(objtype),  # type: ignore[operator]
-                     make_refnode(builder, fromdocname, todocname, node_id,
-                                  contnode, target + ' ' + objtype)))
+                results.append((
+                    f'rst:{self.role_for_objtype(objtype)}',
+                    make_refnode(
+                        builder,
+                        fromdocname,
+                        todocname,
+                        node_id,
+                        contnode,
+                        f'{target} {objtype}',
+                    ),
+                ))
         return results
 
     def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]: