Sphinx 8.1.3__py3-none-any.whl → 8.2.0rc1__py3-none-any.whl

sphinx/domains/python/_annotations.py

@@ -6,25 +6,28 @@ 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.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 +53,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 +72,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 +96,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 +156,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 +173,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 +229,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 +265,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 +274,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 +297,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 +342,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 +393,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 +437,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 +457,41 @@ 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):
+            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 += addnodes.desc_parameter(
+                '', '', addnodes.desc_sig_operator('', '*')
+            )
 
         node = addnodes.desc_parameter()
         if param.kind == param.VAR_POSITIONAL:
@@ -464,8 +515,9 @@ 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
@@ -478,9 +530,12 @@ def _parse_arglist(
 
 
 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 +543,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 +564,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 +574,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