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

sphinx/domains/python/_annotations.py

@@ -6,25 +6,29 @@ import operator
 import token
 from collections import deque
 from inspect import Parameter
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 
 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.locale import _
 from sphinx.pycode.parser import Token, TokenProcessor
 from sphinx.util.inspect import signature_from_str
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator
+    from typing import Any
 
     from docutils.nodes import Element, Node
 
+    from sphinx.addnodes import desc_signature
     from sphinx.environment import BuildEnvironment
 
 
-def parse_reftarget(reftarget: str, suppress_prefix: bool = False,
-                    ) -> tuple[str, str, str, bool]:
+def parse_reftarget(
+    reftarget: str, suppress_prefix: bool = False
+) -> tuple[str, str, str, bool]:
     """Parse a type string and return (reftype, reftarget, title, refspecific flag)"""
     refspecific = False
     if reftarget.startswith('.'):
@@ -50,12 +54,15 @@ def parse_reftarget(reftarget: str, suppress_prefix: bool = False,
     return reftype, reftarget, title, refspecific
 
 
-def type_to_xref(target: str, env: BuildEnvironment, *,
-                 suppress_prefix: bool = False) -> addnodes.pending_xref:
+def type_to_xref(
+    target: str, env: BuildEnvironment, *, suppress_prefix: bool = False
+) -> addnodes.pending_xref:
     """Convert a type string to a cross reference node."""
     if env:
-        kwargs = {'py:module': env.ref_context.get('py:module'),
-                  'py:class': env.ref_context.get('py:class')}
+        kwargs = {
+            'py:module': env.ref_context.get('py:module'),
+            'py:class': env.ref_context.get('py:class'),
+        }
     else:
         kwargs = {}
 
@@ -66,14 +73,22 @@ def type_to_xref(target: str, env: BuildEnvironment, *,
         # nested classes.  But python domain can't access the real python object because this
         # module should work not-dynamically.
         shortname = title.split('.')[-1]
-        contnodes: list[Node] = [pending_xref_condition('', shortname, condition='resolved'),
-                                 pending_xref_condition('', title, condition='*')]
+        contnodes: list[Node] = [
+            pending_xref_condition('', shortname, condition='resolved'),
+            pending_xref_condition('', title, condition='*'),
+        ]
     else:
         contnodes = [nodes.Text(title)]
 
-    return pending_xref('', *contnodes,
-                        refdomain='py', reftype=reftype, reftarget=target,
-                        refspecific=refspecific, **kwargs)
+    return pending_xref(
+        '',
+        *contnodes,
+        refdomain='py',
+        reftype=reftype,
+        reftarget=target,
+        refspecific=refspecific,
+        **kwargs,
+    )
 
 
 def _parse_annotation(annotation: str, env: BuildEnvironment) -> list[Node]:
@@ -82,19 +97,21 @@ def _parse_annotation(annotation: str, env: BuildEnvironment) -> list[Node]:
 
     def unparse(node: ast.AST) -> list[Node]:
         if isinstance(node, ast.Attribute):
-            return [nodes.Text(f"{unparse(node.value)[0]}.{node.attr}")]
+            return [nodes.Text(f'{unparse(node.value)[0]}.{node.attr}')]
         if isinstance(node, ast.BinOp):
             result: list[Node] = unparse(node.left)
             result.extend(unparse(node.op))
             result.extend(unparse(node.right))
             return result
         if isinstance(node, ast.BitOr):
-            return [addnodes.desc_sig_space(),
-                    addnodes.desc_sig_punctuation('', '|'),
-                    addnodes.desc_sig_space()]
+            return [
+                addnodes.desc_sig_space(),
+                addnodes.desc_sig_punctuation('', '|'),
+                addnodes.desc_sig_space(),
+            ]
         if isinstance(node, ast.Constant):
             if node.value is Ellipsis:
-                return [addnodes.desc_sig_punctuation('', "...")]
+                return [addnodes.desc_sig_punctuation('', '...')]
             if isinstance(node.value, bool):
                 return [addnodes.desc_sig_keyword('', repr(node.value))]
             if isinstance(node.value, int):
@@ -140,7 +157,7 @@ def _parse_annotation(annotation: str, env: BuildEnvironment) -> list[Node]:
             result.append(addnodes.desc_sig_punctuation('', ']'))
 
             # Wrap the Text nodes inside brackets by literal node if the subscript is a Literal
-            if result[0] in ('Literal', 'typing.Literal'):
+            if result[0] in {'Literal', 'typing.Literal'}:
                 for i, subnode in enumerate(result[1:], start=1):
                     if isinstance(subnode, nodes.Text):
                         result[i] = nodes.literal('', '', subnode)
@@ -157,8 +174,10 @@ def _parse_annotation(annotation: str, env: BuildEnvironment) -> list[Node]:
                 result.pop()
                 result.pop()
             else:
-                result = [addnodes.desc_sig_punctuation('', '('),
-                          addnodes.desc_sig_punctuation('', ')')]
+                result = [
+                    addnodes.desc_sig_punctuation('', '('),
+                    addnodes.desc_sig_punctuation('', ')'),
+                ]
 
             return result
         if isinstance(node, ast.Call):
@@ -211,8 +230,11 @@ def _parse_annotation(annotation: str, env: BuildEnvironment) -> list[Node]:
             if isinstance(node, nodes.literal):
                 result.append(node[0])
             elif isinstance(node, nodes.Text) and node.strip():
-                if (result and isinstance(result[-1], addnodes.desc_sig_punctuation) and
-                        result[-1].astext() == '~'):
+                if (
+                    result
+                    and isinstance(result[-1], addnodes.desc_sig_punctuation)
+                    and result[-1].astext() == '~'
+                ):
                     result.pop()
                     result.append(type_to_xref(str(node), env, suppress_prefix=True))
                 else:
@@ -244,8 +266,7 @@ class _TypeParameterListParser(TokenProcessor):
             else:
                 if current == token.INDENT:
                     tokens += self.fetch_until(token.DEDENT)
-                elif current.match(
-                        [token.OP, ':'], [token.OP, '='], [token.OP, ',']):
+                elif current.match([token.OP, ':'], [token.OP, '='], [token.OP, ',']):
                     tokens.pop()
                     break
         return tokens
@@ -254,7 +275,9 @@ class _TypeParameterListParser(TokenProcessor):
         while current := self.fetch_token():
             if current == token.NAME:
                 tp_name = current.value.strip()
-                if self.previous and self.previous.match([token.OP, '*'], [token.OP, '**']):
+                if self.previous and self.previous.match(
+                    [token.OP, '*'], [token.OP, '**']
+                ):
                     if self.previous == [token.OP, '*']:
                         tp_kind = Parameter.VAR_POSITIONAL
                     else:
@@ -275,9 +298,14 @@ class _TypeParameterListParser(TokenProcessor):
                         tokens = self.fetch_type_param_spec()
                         tp_default = self._build_identifier(tokens)
 
-                if tp_kind != Parameter.POSITIONAL_OR_KEYWORD and tp_ann != Parameter.empty:
-                    msg = ('type parameter bound or constraint is not allowed '
-                           f'for {tp_kind.description} parameters')
+                if (
+                    tp_kind != Parameter.POSITIONAL_OR_KEYWORD
+                    and tp_ann != Parameter.empty
+                ):
+                    msg = (
+                        'type parameter bound or constraint is not allowed '
+                        f'for {tp_kind.description} parameters'
+                    )
                     raise SyntaxError(msg)
 
                 type_param = (tp_name, tp_kind, tp_default, tp_ann)
@@ -315,12 +343,22 @@ class _TypeParameterListParser(TokenProcessor):
             idents.append(ident)
             # determine if the next token is an unpack operator depending
             # on the left and right hand side of the operator symbol
-            is_unpack_operator = (
-                op.match([token.OP, '*'], [token.OP, '**']) and not (
-                    tok.match(token.NAME, token.NUMBER, token.STRING,
-                              [token.OP, ')'], [token.OP, ']'], [token.OP, '}'])
-                    and after.match(token.NAME, token.NUMBER, token.STRING,
-                                    [token.OP, '('], [token.OP, '['], [token.OP, '{'])
+            is_unpack_operator = op.match([token.OP, '*'], [token.OP, '**']) and not (
+                tok.match(
+                    token.NAME,
+                    token.NUMBER,
+                    token.STRING,
+                    [token.OP, ')'],
+                    [token.OP, ']'],
+                    [token.OP, '}'],
+                )
+                and after.match(
+                    token.NAME,
+                    token.NUMBER,
+                    token.STRING,
+                    [token.OP, '('],
+                    [token.OP, '['],
+                    [token.OP, '{'],
                 )
             )
 
@@ -356,28 +394,33 @@ class _TypeParameterListParser(TokenProcessor):
             [token.OP, '@'], [token.OP, '/'], [token.OP, '//'], [token.OP, '%'],
             [token.OP, '<<'], [token.OP, '>>'], [token.OP, '>>>'],
             [token.OP, '<='], [token.OP, '>='], [token.OP, '=='], [token.OP, '!='],
-        ):
+        ):  # fmt: skip
             return f' {tok.value} '
 
         return tok.value
 
 
 def _parse_type_list(
-    tp_list: str, env: BuildEnvironment,
+    tp_list: str,
+    env: BuildEnvironment,
     multi_line_parameter_list: bool = False,
+    trailing_comma: bool = True,
 ) -> addnodes.desc_type_parameter_list:
     """Parse a list of type parameters according to PEP 695."""
     type_params = addnodes.desc_type_parameter_list(tp_list)
     type_params['multi_line_parameter_list'] = multi_line_parameter_list
+    type_params['multi_line_trailing_comma'] = trailing_comma
     # formal parameter names are interpreted as type parameter names and
     # type annotations are interpreted as type parameter bound or constraints
     parser = _TypeParameterListParser(tp_list)
     parser.parse()
-    for (tp_name, tp_kind, tp_default, tp_ann) in parser.type_params:
+    for tp_name, tp_kind, tp_default, tp_ann in parser.type_params:
         # no positional-only or keyword-only allowed in a type parameters list
         if tp_kind in {Parameter.POSITIONAL_ONLY, Parameter.KEYWORD_ONLY}:
-            msg = ('positional-only or keyword-only parameters '
-                   'are prohibited in type parameter lists')
+            msg = (
+                'positional-only or keyword-only parameters '
+                'are prohibited in type parameter lists'
+            )
             raise SyntaxError(msg)
 
         node = addnodes.desc_type_parameter()
@@ -395,8 +438,7 @@ def _parse_type_list(
             node += addnodes.desc_sig_punctuation('', ':')
             node += addnodes.desc_sig_space()
 
-            type_ann_expr = addnodes.desc_sig_name('', '',
-                                                   *annotation)  # type: ignore[arg-type]
+            type_ann_expr = addnodes.desc_sig_name('', '', *annotation)  # type: ignore[arg-type]
             # a type bound is ``T: U`` whereas type constraints
             # must be enclosed with parentheses. ``T: (U, V)``
             if tp_ann.startswith('(') and tp_ann.endswith(')'):
@@ -416,31 +458,35 @@ def _parse_type_list(
             node += addnodes.desc_sig_space()
             node += addnodes.desc_sig_operator('', '=')
             node += addnodes.desc_sig_space()
-            node += nodes.inline('', tp_default,
-                                 classes=['default_value'],
-                                 support_smartquotes=False)
+            node += nodes.inline(
+                '', tp_default, classes=['default_value'], support_smartquotes=False
+            )
 
         type_params += node
     return type_params
 
 
 def _parse_arglist(
-    arglist: str, env: BuildEnvironment, multi_line_parameter_list: bool = False,
+    arglist: str,
+    env: BuildEnvironment,
+    multi_line_parameter_list: bool = False,
+    trailing_comma: bool = True,
 ) -> addnodes.desc_parameterlist:
     """Parse a list of arguments using AST parser"""
     params = addnodes.desc_parameterlist(arglist)
     params['multi_line_parameter_list'] = multi_line_parameter_list
+    params['multi_line_trailing_comma'] = trailing_comma
     sig = signature_from_str('(%s)' % arglist)
     last_kind = None
     for param in sig.parameters.values():
         if param.kind != param.POSITIONAL_ONLY and last_kind == param.POSITIONAL_ONLY:
-            # PEP-570: Separator for Positional Only Parameter: /
-            params += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '/'))
-        if param.kind == param.KEYWORD_ONLY and last_kind in (param.POSITIONAL_OR_KEYWORD,
-                                                              param.POSITIONAL_ONLY,
-                                                              None):
-            # PEP-3102: Separator for Keyword Only Parameter: *
-            params += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '*'))
+            params += _positional_only_separator()
+        if param.kind == param.KEYWORD_ONLY and last_kind in {
+            param.POSITIONAL_OR_KEYWORD,
+            param.POSITIONAL_ONLY,
+            None,
+        }:
+            params += _keyword_only_separator()
 
         node = addnodes.desc_parameter()
         if param.kind == param.VAR_POSITIONAL:
@@ -464,23 +510,48 @@ def _parse_arglist(
                 node += addnodes.desc_sig_space()
             else:
                 node += addnodes.desc_sig_operator('', '=')
-            node += nodes.inline('', param.default, classes=['default_value'],
-                                 support_smartquotes=False)
+            node += nodes.inline(
+                '', param.default, classes=['default_value'], support_smartquotes=False
+            )
 
         params += node
         last_kind = param.kind
 
     if last_kind == Parameter.POSITIONAL_ONLY:
-        # PEP-570: Separator for Positional Only Parameter: /
-        params += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '/'))
+        params += _positional_only_separator()
 
     return params
 
 
+def _positional_only_separator() -> addnodes.desc_parameter:
+    # PEP 570: Separator for positional only parameters: /
+    positional_only_abbr = nodes.abbreviation(
+        '/', '/', explanation=_('Positional-only parameter separator (PEP 570)')
+    )
+    positional_only_op = addnodes.desc_sig_operator(
+        '/', '', positional_only_abbr, classes=['positional-only-separator']
+    )
+    return addnodes.desc_parameter('/', '', positional_only_op)
+
+
+def _keyword_only_separator() -> addnodes.desc_parameter:
+    # PEP 3102: Separator for keyword only parameters: *
+    keyword_only_abbr = nodes.abbreviation(
+        '*', '*', explanation=_('Keyword-only parameters separator (PEP 3102)')
+    )
+    keyword_only_op = addnodes.desc_sig_operator(
+        '*', '', keyword_only_abbr, classes=['keyword-only-separator']
+    )
+    return addnodes.desc_parameter('*', '', keyword_only_op)
+
+
 def _pseudo_parse_arglist(
-    signode: desc_signature, arglist: str, multi_line_parameter_list: bool = False,
+    signode: desc_signature,
+    arglist: str,
+    multi_line_parameter_list: bool = False,
+    trailing_comma: bool = True,
 ) -> None:
-    """"Parse" a list of arguments separated by commas.
+    """'Parse' a list of arguments separated by commas.
 
     Arguments can have "optional" annotations given by enclosing them in
     brackets.  Currently, this will split at any comma, even if it's inside a
@@ -488,6 +559,7 @@ def _pseudo_parse_arglist(
     """
     paramlist = addnodes.desc_parameterlist()
     paramlist['multi_line_parameter_list'] = multi_line_parameter_list
+    paramlist['multi_line_trailing_comma'] = trailing_comma
     stack: list[Element] = [paramlist]
     try:
         for argument in arglist.split(','):
@@ -508,7 +580,8 @@ def _pseudo_parse_arglist(
                 argument = argument[:-1].strip()
             if argument:
                 stack[-1] += addnodes.desc_parameter(
-                    '', '', addnodes.desc_sig_name(argument, argument))
+                    '', '', addnodes.desc_sig_name(argument, argument)
+                )
             while ends_open:
                 stack.append(addnodes.desc_optional())
                 stack[-2] += stack[-1]
@@ -517,7 +590,7 @@ def _pseudo_parse_arglist(
                 stack.pop()
                 ends_close -= 1
         if len(stack) != 1:
-            raise IndexError
+            raise IndexError  # NoQA: TRY301
     except IndexError:
         # if there are too few or too many elements on the stack, just give up
         # and treat the whole argument list as one argument, discarding the