Sphinx 7.2.6__py3-none-any.whl → 7.3.1__py3-none-any.whl

sphinx/domains/python.py

@@ -1,1769 +0,0 @@
-"""The Python domain."""
-
-from __future__ import annotations
-
-import ast
-import builtins
-import contextlib
-import inspect
-import re
-import token
-import typing
-from inspect import Parameter
-from typing import TYPE_CHECKING, Any, NamedTuple, cast
-
-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.directives import ObjectDescription
-from sphinx.domains import Domain, Index, IndexEntry, ObjType
-from sphinx.locale import _, __
-from sphinx.pycode.parser import Token, TokenProcessor
-from sphinx.roles import XRefRole
-from sphinx.util import logging
-from sphinx.util.docfields import Field, GroupedField, TypedField
-from sphinx.util.docutils import SphinxDirective
-from sphinx.util.inspect import signature_from_str
-from sphinx.util.nodes import (
-    find_pending_xref_condition,
-    make_id,
-    make_refnode,
-    nested_parse_with_titles,
-)
-
-if TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator
-
-    from docutils.nodes import Element, Node
-    from docutils.parsers.rst.states import Inliner
-
-    from sphinx.application import Sphinx
-    from sphinx.builders import Builder
-    from sphinx.environment import BuildEnvironment
-    from sphinx.util.typing import OptionSpec, TextlikeNode
-
-logger = logging.getLogger(__name__)
-
-
-# REs for Python signatures
-py_sig_re = re.compile(
-    r'''^ ([\w.]*\.)?            # class name(s)
-          (\w+)  \s*             # thing name
-          (?: \[\s*(.*)\s*])?    # optional: type parameters list
-          (?: \(\s*(.*)\s*\)     # optional: arguments
-           (?:\s* -> \s* (.*))?  #           return annotation
-          )? $                   # and nothing more
-          ''', re.VERBOSE)
-
-
-pairindextypes = {
-    'module': 'module',
-    'keyword': 'keyword',
-    'operator': 'operator',
-    'object': 'object',
-    'exception': 'exception',
-    'statement': 'statement',
-    'builtin': 'built-in function',
-}
-
-
-class ObjectEntry(NamedTuple):
-    docname: str
-    node_id: str
-    objtype: str
-    aliased: bool
-
-
-class ModuleEntry(NamedTuple):
-    docname: str
-    node_id: str
-    synopsis: str
-    platform: str
-    deprecated: 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('.'):
-        reftarget = reftarget[1:]
-        title = reftarget
-        refspecific = True
-    elif reftarget.startswith('~'):
-        reftarget = reftarget[1:]
-        title = reftarget.split('.')[-1]
-    elif suppress_prefix:
-        title = reftarget.split('.')[-1]
-    elif reftarget.startswith('typing.'):
-        title = reftarget[7:]
-    else:
-        title = reftarget
-
-    if reftarget == 'None' or reftarget.startswith('typing.'):
-        # typing module provides non-class types.  Obj reference is good to refer them.
-        reftype = 'obj'
-    else:
-        reftype = 'class'
-
-    return reftype, reftarget, title, refspecific
-
-
-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')}
-    else:
-        kwargs = {}
-
-    reftype, target, title, refspecific = parse_reftarget(target, suppress_prefix)
-
-    if env.config.python_use_unqualified_type_names:
-        # Note: It would be better to use qualname to describe the object to support support
-        # 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='*')]
-    else:
-        contnodes = [nodes.Text(title)]
-
-    return pending_xref('', *contnodes,
-                        refdomain='py', reftype=reftype, reftarget=target,
-                        refspecific=refspecific, **kwargs)
-
-
-def _parse_annotation(annotation: str, env: BuildEnvironment) -> list[Node]:
-    """Parse type annotation."""
-    short_literals = env.config.python_display_short_literal_types
-
-    def unparse(node: ast.AST) -> list[Node]:
-        if isinstance(node, ast.Attribute):
-            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()]
-        if isinstance(node, ast.Constant):
-            if node.value is Ellipsis:
-                return [addnodes.desc_sig_punctuation('', "...")]
-            if isinstance(node.value, bool):
-                return [addnodes.desc_sig_keyword('', repr(node.value))]
-            if isinstance(node.value, int):
-                return [addnodes.desc_sig_literal_number('', repr(node.value))]
-            if isinstance(node.value, str):
-                return [addnodes.desc_sig_literal_string('', repr(node.value))]
-            else:
-                # handles None, which is further handled by type_to_xref later
-                # and fallback for other types that should be converted
-                return [nodes.Text(repr(node.value))]
-        if isinstance(node, ast.Expr):
-            return unparse(node.value)
-        if isinstance(node, ast.Invert):
-            return [addnodes.desc_sig_punctuation('', '~')]
-        if isinstance(node, ast.List):
-            result = [addnodes.desc_sig_punctuation('', '[')]
-            if node.elts:
-                # check if there are elements in node.elts to only pop the
-                # last element of result if the for-loop was run at least
-                # once
-                for elem in node.elts:
-                    result.extend(unparse(elem))
-                    result.append(addnodes.desc_sig_punctuation('', ','))
-                    result.append(addnodes.desc_sig_space())
-                result.pop()
-                result.pop()
-            result.append(addnodes.desc_sig_punctuation('', ']'))
-            return result
-        if isinstance(node, ast.Module):
-            return sum((unparse(e) for e in node.body), [])
-        if isinstance(node, ast.Name):
-            return [nodes.Text(node.id)]
-        if isinstance(node, ast.Subscript):
-            if getattr(node.value, 'id', '') in {'Optional', 'Union'}:
-                return _unparse_pep_604_annotation(node)
-            if short_literals and getattr(node.value, 'id', '') == 'Literal':
-                return _unparse_pep_604_annotation(node)
-            result = unparse(node.value)
-            result.append(addnodes.desc_sig_punctuation('', '['))
-            result.extend(unparse(node.slice))
-            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'):
-                for i, subnode in enumerate(result[1:], start=1):
-                    if isinstance(subnode, nodes.Text):
-                        result[i] = nodes.literal('', '', subnode)
-            return result
-        if isinstance(node, ast.UnaryOp):
-            return unparse(node.op) + unparse(node.operand)
-        if isinstance(node, ast.Tuple):
-            if node.elts:
-                result = []
-                for elem in node.elts:
-                    result.extend(unparse(elem))
-                    result.append(addnodes.desc_sig_punctuation('', ','))
-                    result.append(addnodes.desc_sig_space())
-                result.pop()
-                result.pop()
-            else:
-                result = [addnodes.desc_sig_punctuation('', '('),
-                          addnodes.desc_sig_punctuation('', ')')]
-
-            return result
-        raise SyntaxError  # unsupported syntax
-
-    def _unparse_pep_604_annotation(node: ast.Subscript) -> list[Node]:
-        subscript = node.slice
-
-        flattened: list[Node] = []
-        if isinstance(subscript, ast.Tuple):
-            flattened.extend(unparse(subscript.elts[0]))
-            for elt in subscript.elts[1:]:
-                flattened.extend(unparse(ast.BitOr()))
-                flattened.extend(unparse(elt))
-        else:
-            # e.g. a Union[] inside an Optional[]
-            flattened.extend(unparse(subscript))
-
-        if getattr(node.value, 'id', '') == 'Optional':
-            flattened.extend(unparse(ast.BitOr()))
-            flattened.append(nodes.Text('None'))
-
-        return flattened
-
-    try:
-        tree = ast.parse(annotation, type_comments=True)
-        result: list[Node] = []
-        for node in unparse(tree):
-            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() == '~'):
-                    result.pop()
-                    result.append(type_to_xref(str(node), env, suppress_prefix=True))
-                else:
-                    result.append(type_to_xref(str(node), env))
-            else:
-                result.append(node)
-        return result
-    except SyntaxError:
-        return [type_to_xref(annotation, env)]
-
-
-class _TypeParameterListParser(TokenProcessor):
-    def __init__(self, sig: str) -> None:
-        signature = sig.replace('\n', '').strip()
-        super().__init__([signature])
-        # Each item is a tuple (name, kind, default, annotation) mimicking
-        # ``inspect.Parameter`` to allow default values on VAR_POSITIONAL
-        # or VAR_KEYWORD parameters.
-        self.type_params: list[tuple[str, int, Any, Any]] = []
-
-    def fetch_type_param_spec(self) -> list[Token]:
-        tokens = []
-        while current := self.fetch_token():
-            tokens.append(current)
-            for ldelim, rdelim in ('(', ')'), ('{', '}'), ('[', ']'):
-                if current == [token.OP, ldelim]:
-                    tokens += self.fetch_until([token.OP, rdelim])
-                    break
-            else:
-                if current == token.INDENT:
-                    tokens += self.fetch_until(token.DEDENT)
-                elif current.match(
-                        [token.OP, ':'], [token.OP, '='], [token.OP, ',']):
-                    tokens.pop()
-                    break
-        return tokens
-
-    def parse(self) -> None:
-        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 == [token.OP, '*']:
-                        tp_kind = Parameter.VAR_POSITIONAL
-                    else:
-                        tp_kind = Parameter.VAR_KEYWORD  # type: ignore[assignment]
-                else:
-                    tp_kind = Parameter.POSITIONAL_OR_KEYWORD  # type: ignore[assignment]
-
-                tp_ann: Any = Parameter.empty
-                tp_default: Any = Parameter.empty
-
-                current = self.fetch_token()
-                if current and current.match([token.OP, ':'], [token.OP, '=']):
-                    if current == [token.OP, ':']:
-                        tokens = self.fetch_type_param_spec()
-                        tp_ann = self._build_identifier(tokens)
-
-                    if self.current and self.current == [token.OP, '=']:
-                        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')
-                    raise SyntaxError(msg)
-
-                type_param = (tp_name, tp_kind, tp_default, tp_ann)
-                self.type_params.append(type_param)
-
-    def _build_identifier(self, tokens: list[Token]) -> str:
-        from itertools import chain, tee
-
-        def pairwise(iterable):
-            a, b = tee(iterable)
-            next(b, None)
-            return zip(a, b)
-
-        def triplewise(iterable):
-            for (a, _z), (b, c) in pairwise(pairwise(iterable)):
-                yield a, b, c
-
-        idents: list[str] = []
-        tokens: Iterable[Token] = iter(tokens)  # type: ignore[no-redef]
-        # do not format opening brackets
-        for tok in tokens:
-            if not tok.match([token.OP, '('], [token.OP, '['], [token.OP, '{']):
-                # check if the first non-delimiter character is an unpack operator
-                is_unpack_operator = tok.match([token.OP, '*'], [token.OP, ['**']])
-                idents.append(self._pformat_token(tok, native=is_unpack_operator))
-                break
-            idents.append(tok.value)
-
-        # check the remaining tokens
-        stop = Token(token.ENDMARKER, '', (-1, -1), (-1, -1), '<sentinel>')
-        is_unpack_operator = False
-        for tok, op, after in triplewise(chain(tokens, [stop, stop])):
-            ident = self._pformat_token(tok, native=is_unpack_operator)
-            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, '{'])
-                )
-            )
-
-        return ''.join(idents).strip()
-
-    def _pformat_token(self, tok: Token, native: bool = False) -> str:
-        if native:
-            return tok.value
-
-        if tok.match(token.NEWLINE, token.ENDMARKER):
-            return ''
-
-        if tok.match([token.OP, ':'], [token.OP, ','], [token.OP, '#']):
-            return f'{tok.value} '
-
-        # Arithmetic operators are allowed because PEP 695 specifies the
-        # default type parameter to be *any* expression (so "T1 << T2" is
-        # allowed if it makes sense). The caller is responsible to ensure
-        # that a multiplication operator ("*") is not to be confused with
-        # an unpack operator (which will not be surrounded by spaces).
-        #
-        # The operators are ordered according to how likely they are to
-        # be used and for (possible) future implementations (e.g., "&" for
-        # an intersection type).
-        if tok.match(
-            # Most likely operators to appear
-            [token.OP, '='], [token.OP, '|'],
-            # Type composition (future compatibility)
-            [token.OP, '&'], [token.OP, '^'], [token.OP, '<'], [token.OP, '>'],
-            # Unlikely type composition
-            [token.OP, '+'], [token.OP, '-'], [token.OP, '*'], [token.OP, '**'],
-            # Unlikely operators but included for completeness
-            [token.OP, '@'], [token.OP, '/'], [token.OP, '//'], [token.OP, '%'],
-            [token.OP, '<<'], [token.OP, '>>'], [token.OP, '>>>'],
-            [token.OP, '<='], [token.OP, '>='], [token.OP, '=='], [token.OP, '!='],
-        ):
-            return f' {tok.value} '
-
-        return tok.value
-
-
-def _parse_type_list(
-    tp_list: str, env: BuildEnvironment,
-    multi_line_parameter_list: bool = False,
-) -> 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
-    # 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:
-        # 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')
-            raise SyntaxError(msg)
-
-        node = addnodes.desc_type_parameter()
-        if tp_kind == Parameter.VAR_POSITIONAL:
-            node += addnodes.desc_sig_operator('', '*')
-        elif tp_kind == Parameter.VAR_KEYWORD:
-            node += addnodes.desc_sig_operator('', '**')
-        node += addnodes.desc_sig_name('', tp_name)
-
-        if tp_ann is not Parameter.empty:
-            annotation = _parse_annotation(tp_ann, env)
-            if not annotation:
-                continue
-
-            node += addnodes.desc_sig_punctuation('', ':')
-            node += addnodes.desc_sig_space()
-
-            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(')'):
-                type_ann_text = type_ann_expr.astext()
-                if type_ann_text.startswith('(') and type_ann_text.endswith(')'):
-                    node += type_ann_expr
-                else:
-                    # surrounding braces are lost when using _parse_annotation()
-                    node += addnodes.desc_sig_punctuation('', '(')
-                    node += type_ann_expr  # type constraint
-                    node += addnodes.desc_sig_punctuation('', ')')
-            else:
-                node += type_ann_expr  # type bound
-
-        if tp_default is not Parameter.empty:
-            # Always surround '=' with spaces, even if there is no annotation
-            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)
-
-        type_params += node
-    return type_params
-
-
-def _parse_arglist(
-    arglist: str, env: BuildEnvironment, multi_line_parameter_list: bool = False,
-) -> 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
-    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('', '*'))
-
-        node = addnodes.desc_parameter()
-        if param.kind == param.VAR_POSITIONAL:
-            node += addnodes.desc_sig_operator('', '*')
-            node += addnodes.desc_sig_name('', param.name)
-        elif param.kind == param.VAR_KEYWORD:
-            node += addnodes.desc_sig_operator('', '**')
-            node += addnodes.desc_sig_name('', param.name)
-        else:
-            node += addnodes.desc_sig_name('', param.name)
-
-        if param.annotation is not param.empty:
-            children = _parse_annotation(param.annotation, env)
-            node += addnodes.desc_sig_punctuation('', ':')
-            node += addnodes.desc_sig_space()
-            node += addnodes.desc_sig_name('', '', *children)  # type: ignore[arg-type]
-        if param.default is not param.empty:
-            if param.annotation is not param.empty:
-                node += addnodes.desc_sig_space()
-                node += addnodes.desc_sig_operator('', '=')
-                node += addnodes.desc_sig_space()
-            else:
-                node += addnodes.desc_sig_operator('', '=')
-            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('', '/'))
-
-    return params
-
-
-def _pseudo_parse_arglist(
-    signode: desc_signature, arglist: str, multi_line_parameter_list: bool = False,
-) -> None:
-    """"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
-    string literal (e.g. default argument value).
-    """
-    paramlist = addnodes.desc_parameterlist()
-    paramlist['multi_line_parameter_list'] = multi_line_parameter_list
-    stack: list[Element] = [paramlist]
-    try:
-        for argument in arglist.split(','):
-            argument = argument.strip()
-            ends_open = ends_close = 0
-            while argument.startswith('['):
-                stack.append(addnodes.desc_optional())
-                stack[-2] += stack[-1]
-                argument = argument[1:].strip()
-            while argument.startswith(']'):
-                stack.pop()
-                argument = argument[1:].strip()
-            while argument.endswith(']') and not argument.endswith('[]'):
-                ends_close += 1
-                argument = argument[:-1].strip()
-            while argument.endswith('['):
-                ends_open += 1
-                argument = argument[:-1].strip()
-            if argument:
-                stack[-1] += addnodes.desc_parameter(
-                    '', '', addnodes.desc_sig_name(argument, argument))
-            while ends_open:
-                stack.append(addnodes.desc_optional())
-                stack[-2] += stack[-1]
-                ends_open -= 1
-            while ends_close:
-                stack.pop()
-                ends_close -= 1
-        if len(stack) != 1:
-            raise IndexError
-    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
-        # already partially populated paramlist node
-        paramlist = addnodes.desc_parameterlist()
-        paramlist += addnodes.desc_parameter(arglist, arglist)
-        signode += paramlist
-    else:
-        signode += paramlist
-
-
-# This override allows our inline type specifiers to behave like :class: link
-# when it comes to handling "." and "~" prefixes.
-class PyXrefMixin:
-    def make_xref(
-        self,
-        rolename: str,
-        domain: str,
-        target: str,
-        innernode: type[TextlikeNode] = nodes.emphasis,
-        contnode: Node | None = None,
-        env: BuildEnvironment | None = None,
-        inliner: Inliner | None = None,
-        location: Node | None = None,
-    ) -> 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)
-        if isinstance(result, pending_xref):
-            assert env is not None
-            result['refspecific'] = True
-            result['py:module'] = env.ref_context.get('py:module')
-            result['py:class'] = env.ref_context.get('py:class')
-
-            reftype, reftarget, reftitle, _ = parse_reftarget(target)
-            if reftarget != reftitle:
-                result['reftype'] = reftype
-                result['reftarget'] = reftarget
-
-                result.clear()
-                result += innernode(reftitle, reftitle)
-            elif env.config.python_use_unqualified_type_names:
-                children = result.children
-                result.clear()
-
-                shortname = target.split('.')[-1]
-                textnode = innernode('', shortname)
-                contnodes = [pending_xref_condition('', '', textnode, condition='resolved'),
-                             pending_xref_condition('', '', *children, condition='*')]
-                result.extend(contnodes)
-
-        return result
-
-    def make_xrefs(
-        self,
-        rolename: str,
-        domain: str,
-        target: str,
-        innernode: type[TextlikeNode] = nodes.emphasis,
-        contnode: Node | None = None,
-        env: BuildEnvironment | None = None,
-        inliner: Inliner | None = None,
-        location: Node | None = None,
-    ) -> list[Node]:
-        delims = r'(\s*[\[\]\(\),](?:\s*o[rf]\s)?\s*|\s+o[rf]\s+|\s*\|\s*|\.\.\.)'
-        delims_re = re.compile(delims)
-        sub_targets = re.split(delims, target)
-
-        split_contnode = bool(contnode and contnode.astext() == target)
-
-        in_literal = False
-        results = []
-        for sub_target in filter(None, sub_targets):
-            if split_contnode:
-                contnode = nodes.Text(sub_target)
-
-            if in_literal or delims_re.match(sub_target):
-                results.append(contnode or innernode(sub_target, sub_target))
-            else:
-                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
-
-        return results
-
-
-class PyField(PyXrefMixin, Field):
-    pass
-
-
-class PyGroupedField(PyXrefMixin, GroupedField):
-    pass
-
-
-class PyTypedField(PyXrefMixin, TypedField):
-    pass
-
-
-class PyObject(ObjectDescription[tuple[str, str]]):
-    """
-    Description of a general Python object.
-
-    :cvar allow_nesting: Class is an object that allows for nested namespaces
-    :vartype allow_nesting: bool
-    """
-    option_spec: OptionSpec = {
-        'no-index': directives.flag,
-        'no-index-entry': directives.flag,
-        'no-contents-entry': directives.flag,
-        'no-typesetting': directives.flag,
-        'noindex': directives.flag,
-        'noindexentry': directives.flag,
-        'nocontentsentry': directives.flag,
-        'single-line-parameter-list': directives.flag,
-        'single-line-type-parameter-list': directives.flag,
-        'module': directives.unchanged,
-        'canonical': directives.unchanged,
-        'annotation': directives.unchanged,
-    }
-
-    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'),
-    ]
-
-    allow_nesting = False
-
-    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
-        """May return a prefix to put before the object name in the
-        signature.
-        """
-        return []
-
-    def needs_arglist(self) -> bool:
-        """May return true if an empty argument list is to be generated even if
-        the document contains none.
-        """
-        return False
-
-    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
-        """Transform a Python signature into RST nodes.
-
-        Return (fully qualified name of the thing, classname if any).
-
-        If inside a class, the current class name is handled intelligently:
-        * it is stripped from the displayed name if present
-        * it is added to the full name (return value) if not present
-        """
-        m = py_sig_re.match(sig)
-        if m is None:
-            raise ValueError
-        prefix, name, tp_list, arglist, retann = m.groups()
-
-        # determine module and class name (if applicable), as well as full name
-        modname = self.options.get('module', self.env.ref_context.get('py:module'))
-        classname = self.env.ref_context.get('py:class')
-        if classname:
-            add_module = False
-            if prefix and (prefix == classname or
-                           prefix.startswith(classname + ".")):
-                fullname = prefix + name
-                # class name is given again in the signature
-                prefix = prefix[len(classname):].lstrip('.')
-            elif prefix:
-                # class name is given in the signature, but different
-                # (shouldn't happen)
-                fullname = classname + '.' + prefix + name
-            else:
-                # class name is not given in the signature
-                fullname = classname + '.' + name
-        else:
-            add_module = True
-            if prefix:
-                classname = prefix.rstrip('.')
-                fullname = prefix + name
-            else:
-                classname = ''
-                fullname = name
-
-        signode['module'] = modname
-        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)
-
-        # determine if the function arguments (without its type parameters)
-        # should be formatted on a multiline or not by removing the width of
-        # the type parameters list (if any)
-        sig_len = len(sig)
-        tp_list_span = m.span(3)
-        multi_line_parameter_list = (
-            'single-line-parameter-list' not in self.options
-            and (sig_len - (tp_list_span[1] - tp_list_span[0])) > max_len > 0
-        )
-
-        # determine whether the type parameter list must be wrapped or not
-        arglist_span = m.span(4)
-        multi_line_type_parameter_list = (
-            'single-line-type-parameter-list' not in self.options
-            and (sig_len - (arglist_span[1] - arglist_span[0])) > max_len > 0
-        )
-
-        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}'.")
-                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 + '.'
-            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)
-            except Exception as exc:
-                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:
-                # 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)
-            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)
-        else:
-            if self.needs_arglist():
-                # for callables, add an empty parameter list
-                signode += addnodes.desc_parameterlist()
-
-        if retann:
-            children = _parse_annotation(retann, self.env)
-            signode += addnodes.desc_returns(retann, '', *children)
-
-        anno = self.options.get('annotation')
-        if anno:
-            signode += addnodes.desc_annotation(' ' + anno, '',
-                                                addnodes.desc_sig_space(),
-                                                nodes.Text(anno))
-
-        return fullname, prefix
-
-    def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
-        if 'fullname' not in sig_node:
-            return ()
-        modname = sig_node.get('module')
-        fullname = sig_node['fullname']
-
-        if modname:
-            return (modname, *fullname.split('.'))
-        else:
-            return tuple(fullname.split('.'))
-
-    def get_index_text(self, modname: str, name: tuple[str, str]) -> str:
-        """Return the text for the index entry of the object."""
-        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]
-        node_id = make_id(self.env, self.state.document, '', fullname)
-        signode['ids'].append(node_id)
-        self.state.document.note_explicit_target(signode)
-
-        domain = cast(PythonDomain, self.env.get_domain('py'))
-        domain.note_object(fullname, self.objtype, node_id, location=signode)
-
-        canonical_name = self.options.get('canonical')
-        if canonical_name:
-            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))
-
-    def before_content(self) -> None:
-        """Handle object nesting before content
-
-        :py:class:`PyObject` represents Python language constructs. For
-        constructs that are nestable, such as a Python classes, this method will
-        build up a stack of the nesting hierarchy so that it can be later
-        de-nested correctly, in :py:meth:`after_content`.
-
-        For constructs that aren't nestable, the stack is bypassed, and instead
-        only the most recent object is tracked. This object prefix name will be
-        removed with :py:meth:`after_content`.
-        """
-        prefix = None
-        if self.names:
-            # fullname and name_prefix come from the `handle_signature` method.
-            # fullname represents the full object name that is constructed using
-            # object nesting and explicit prefixes. `name_prefix` is the
-            # explicit prefix given in a signature
-            (fullname, name_prefix) = self.names[-1]
-            if self.allow_nesting:
-                prefix = fullname
-            elif name_prefix:
-                prefix = name_prefix.strip('.')
-        if prefix:
-            self.env.ref_context['py:class'] = prefix
-            if self.allow_nesting:
-                classes = self.env.ref_context.setdefault('py:classes', [])
-                classes.append(prefix)
-        if 'module' in self.options:
-            modules = self.env.ref_context.setdefault('py:modules', [])
-            modules.append(self.env.ref_context.get('py:module'))
-            self.env.ref_context['py:module'] = self.options['module']
-
-    def after_content(self) -> None:
-        """Handle object de-nesting after content
-
-        If this class is a nestable object, removing the last nested class prefix
-        ends further nesting in the object.
-
-        If this class is not a nestable object, the list of classes should not
-        be altered as we didn't affect the nesting levels in
-        :py:meth:`before_content`.
-        """
-        classes = self.env.ref_context.setdefault('py:classes', [])
-        if self.allow_nesting:
-            with contextlib.suppress(IndexError):
-                classes.pop()
-
-        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:
-                self.env.ref_context['py:module'] = modules.pop()
-            else:
-                self.env.ref_context.pop('py:module')
-
-    def _toc_entry_name(self, sig_node: desc_signature) -> str:
-        if not sig_node.get('_toc_parts'):
-            return ''
-
-        config = self.env.app.config
-        objtype = sig_node.parent.get('objtype')
-        if config.add_function_parentheses and objtype in {'function', 'method'}:
-            parens = '()'
-        else:
-            parens = ''
-        *parents, name = sig_node['_toc_parts']
-        if config.toc_object_entries_show_parents == 'domain':
-            return sig_node.get('fullname', name) + parens
-        if config.toc_object_entries_show_parents == 'hide':
-            return name + parens
-        if config.toc_object_entries_show_parents == 'all':
-            return '.'.join(parents + [name + parens])
-        return ''
-
-
-class PyFunction(PyObject):
-    """Description of a function."""
-
-    option_spec: OptionSpec = PyObject.option_spec.copy()
-    option_spec.update({
-        'async': directives.flag,
-    })
-
-    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
-        if 'async' in self.options:
-            return [addnodes.desc_sig_keyword('', 'async'),
-                    addnodes.desc_sig_space()]
-        else:
-            return []
-
-    def needs_arglist(self) -> bool:
-        return True
-
-    def add_target_and_index(self, name_cls: tuple[str, str], sig: str,
-                             signode: desc_signature) -> None:
-        super().add_target_and_index(name_cls, sig, signode)
-        if 'no-index-entry' not in self.options:
-            modname = self.options.get('module', self.env.ref_context.get('py:module'))
-            node_id = signode['ids'][0]
-
-            name, cls = name_cls
-            if modname:
-                text = _('%s() (in module %s)') % (name, modname)
-                self.indexnode['entries'].append(('single', text, node_id, '', None))
-            else:
-                text = f'built-in function; {name}()'
-                self.indexnode['entries'].append(('pair', text, node_id, '', None))
-
-    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
-        # add index in own add_target_and_index() instead.
-        return ''
-
-
-class PyDecoratorFunction(PyFunction):
-    """Description of a decorator."""
-
-    def run(self) -> list[Node]:
-        # a decorator function is a function after all
-        self.name = 'py:function'
-        return super().run()
-
-    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
-        ret = super().handle_signature(sig, signode)
-        signode.insert(0, addnodes.desc_addname('@', '@'))
-        return ret
-
-    def needs_arglist(self) -> bool:
-        return False
-
-
-class PyVariable(PyObject):
-    """Description of a variable."""
-
-    option_spec: OptionSpec = PyObject.option_spec.copy()
-    option_spec.update({
-        'type': directives.unchanged,
-        'value': directives.unchanged,
-    })
-
-    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
-        fullname, prefix = super().handle_signature(sig, signode)
-
-        typ = self.options.get('type')
-        if typ:
-            annotations = _parse_annotation(typ, self.env)
-            signode += addnodes.desc_annotation(typ, '',
-                                                addnodes.desc_sig_punctuation('', ':'),
-                                                addnodes.desc_sig_space(), *annotations)
-
-        value = self.options.get('value')
-        if value:
-            signode += addnodes.desc_annotation(value, '',
-                                                addnodes.desc_sig_space(),
-                                                addnodes.desc_sig_punctuation('', '='),
-                                                addnodes.desc_sig_space(),
-                                                nodes.Text(value))
-
-        return fullname, prefix
-
-    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
-        name, cls = name_cls
-        if modname:
-            return _('%s (in module %s)') % (name, modname)
-        else:
-            return _('%s (built-in variable)') % name
-
-
-class PyClasslike(PyObject):
-    """
-    Description of a class-like object (classes, interfaces, exceptions).
-    """
-
-    option_spec: OptionSpec = PyObject.option_spec.copy()
-    option_spec.update({
-        'final': directives.flag,
-    })
-
-    allow_nesting = True
-
-    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
-        if 'final' in self.options:
-            return [nodes.Text('final'), addnodes.desc_sig_space(),
-                    nodes.Text(self.objtype), addnodes.desc_sig_space()]
-        else:
-            return [nodes.Text(self.objtype), addnodes.desc_sig_space()]
-
-    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
-        if self.objtype == 'class':
-            if not modname:
-                return _('%s (built-in class)') % name_cls[0]
-            return _('%s (class in %s)') % (name_cls[0], modname)
-        elif self.objtype == 'exception':
-            return name_cls[0]
-        else:
-            return ''
-
-
-class PyMethod(PyObject):
-    """Description of a method."""
-
-    option_spec: OptionSpec = PyObject.option_spec.copy()
-    option_spec.update({
-        'abstractmethod': directives.flag,
-        'async': directives.flag,
-        'classmethod': directives.flag,
-        'final': directives.flag,
-        'staticmethod': directives.flag,
-    })
-
-    def needs_arglist(self) -> bool:
-        return True
-
-    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
-        prefix: list[nodes.Node] = []
-        if 'final' in self.options:
-            prefix.append(nodes.Text('final'))
-            prefix.append(addnodes.desc_sig_space())
-        if 'abstractmethod' in self.options:
-            prefix.append(nodes.Text('abstract'))
-            prefix.append(addnodes.desc_sig_space())
-        if 'async' in self.options:
-            prefix.append(nodes.Text('async'))
-            prefix.append(addnodes.desc_sig_space())
-        if 'classmethod' in self.options:
-            prefix.append(nodes.Text('classmethod'))
-            prefix.append(addnodes.desc_sig_space())
-        if 'staticmethod' in self.options:
-            prefix.append(nodes.Text('static'))
-            prefix.append(addnodes.desc_sig_space())
-        return prefix
-
-    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
-        name, cls = name_cls
-        try:
-            clsname, methname = name.rsplit('.', 1)
-            if modname and self.env.config.add_module_names:
-                clsname = '.'.join([modname, clsname])
-        except ValueError:
-            if modname:
-                return _('%s() (in module %s)') % (name, modname)
-            else:
-                return '%s()' % name
-
-        if 'classmethod' in self.options:
-            return _('%s() (%s class method)') % (methname, clsname)
-        elif 'staticmethod' in self.options:
-            return _('%s() (%s static method)') % (methname, clsname)
-        else:
-            return _('%s() (%s method)') % (methname, clsname)
-
-
-class PyClassMethod(PyMethod):
-    """Description of a classmethod."""
-
-    option_spec: OptionSpec = PyObject.option_spec.copy()
-
-    def run(self) -> list[Node]:
-        self.name = 'py:method'
-        self.options['classmethod'] = True
-
-        return super().run()
-
-
-class PyStaticMethod(PyMethod):
-    """Description of a staticmethod."""
-
-    option_spec: OptionSpec = PyObject.option_spec.copy()
-
-    def run(self) -> list[Node]:
-        self.name = 'py:method'
-        self.options['staticmethod'] = True
-
-        return super().run()
-
-
-class PyDecoratorMethod(PyMethod):
-    """Description of a decoratormethod."""
-
-    def run(self) -> list[Node]:
-        self.name = 'py:method'
-        return super().run()
-
-    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
-        ret = super().handle_signature(sig, signode)
-        signode.insert(0, addnodes.desc_addname('@', '@'))
-        return ret
-
-    def needs_arglist(self) -> bool:
-        return False
-
-
-class PyAttribute(PyObject):
-    """Description of an attribute."""
-
-    option_spec: OptionSpec = PyObject.option_spec.copy()
-    option_spec.update({
-        'type': directives.unchanged,
-        'value': directives.unchanged,
-    })
-
-    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
-        fullname, prefix = super().handle_signature(sig, signode)
-
-        typ = self.options.get('type')
-        if typ:
-            annotations = _parse_annotation(typ, self.env)
-            signode += addnodes.desc_annotation(typ, '',
-                                                addnodes.desc_sig_punctuation('', ':'),
-                                                addnodes.desc_sig_space(),
-                                                *annotations)
-
-        value = self.options.get('value')
-        if value:
-            signode += addnodes.desc_annotation(value, '',
-                                                addnodes.desc_sig_space(),
-                                                addnodes.desc_sig_punctuation('', '='),
-                                                addnodes.desc_sig_space(),
-                                                nodes.Text(value))
-
-        return fullname, prefix
-
-    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
-        name, cls = name_cls
-        try:
-            clsname, attrname = name.rsplit('.', 1)
-            if modname and self.env.config.add_module_names:
-                clsname = '.'.join([modname, clsname])
-        except ValueError:
-            if modname:
-                return _('%s (in module %s)') % (name, modname)
-            else:
-                return name
-
-        return _('%s (%s attribute)') % (attrname, clsname)
-
-
-class PyProperty(PyObject):
-    """Description of an attribute."""
-
-    option_spec = PyObject.option_spec.copy()
-    option_spec.update({
-        'abstractmethod': directives.flag,
-        'classmethod': directives.flag,
-        'type': directives.unchanged,
-    })
-
-    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
-        fullname, prefix = super().handle_signature(sig, signode)
-
-        typ = self.options.get('type')
-        if typ:
-            annotations = _parse_annotation(typ, self.env)
-            signode += addnodes.desc_annotation(typ, '',
-                                                addnodes.desc_sig_punctuation('', ':'),
-                                                addnodes.desc_sig_space(),
-                                                *annotations)
-
-        return fullname, prefix
-
-    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
-        prefix: list[nodes.Node] = []
-        if 'abstractmethod' in self.options:
-            prefix.append(nodes.Text('abstract'))
-            prefix.append(addnodes.desc_sig_space())
-        if 'classmethod' in self.options:
-            prefix.append(nodes.Text('class'))
-            prefix.append(addnodes.desc_sig_space())
-
-        prefix.append(nodes.Text('property'))
-        prefix.append(addnodes.desc_sig_space())
-        return prefix
-
-    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
-        name, cls = name_cls
-        try:
-            clsname, attrname = name.rsplit('.', 1)
-            if modname and self.env.config.add_module_names:
-                clsname = '.'.join([modname, clsname])
-        except ValueError:
-            if modname:
-                return _('%s (in module %s)') % (name, modname)
-            else:
-                return name
-
-        return _('%s (%s property)') % (attrname, clsname)
-
-
-class PyModule(SphinxDirective):
-    """
-    Directive to mark description of a new module.
-    """
-
-    has_content = True
-    required_arguments = 1
-    optional_arguments = 0
-    final_argument_whitespace = False
-    option_spec: OptionSpec = {
-        'platform': lambda x: x,
-        'synopsis': lambda x: x,
-        'no-index': directives.flag,
-        'no-contents-entry': directives.flag,
-        'no-typesetting': directives.flag,
-        'noindex': directives.flag,
-        'nocontentsentry': directives.flag,
-        'deprecated': directives.flag,
-    }
-
-    def run(self) -> list[Node]:
-        domain = cast(PythonDomain, self.env.get_domain('py'))
-
-        modname = self.arguments[0].strip()
-        no_index = 'no-index' in self.options or 'noindex' in self.options
-        self.env.ref_context['py:module'] = modname
-
-        content_node: Element = nodes.section()
-        # necessary so that the child nodes get the right source/line set
-        content_node.document = self.state.document
-        nested_parse_with_titles(self.state, self.content, content_node, self.content_offset)
-
-        ret: list[Node] = []
-        if not no_index:
-            # note module to the domain
-            node_id = make_id(self.env, self.state.document, 'module', modname)
-            target = nodes.target('', '', ids=[node_id], ismod=True)
-            self.set_source_info(target)
-            self.state.document.note_explicit_target(target)
-
-            domain.note_module(modname,
-                               node_id,
-                               self.options.get('synopsis', ''),
-                               self.options.get('platform', ''),
-                               'deprecated' in self.options)
-            domain.note_object(modname, 'module', node_id, location=target)
-
-            # the platform and synopsis aren't printed; in fact, they are only
-            # used in the modindex currently
-            indextext = f'module; {modname}'
-            inode = addnodes.index(entries=[('pair', indextext, node_id, '', None)])
-            # The node order is: index node first, then target node.
-            ret.append(inode)
-            ret.append(target)
-        ret.extend(content_node.children)
-        return ret
-
-
-class PyCurrentModule(SphinxDirective):
-    """
-    This directive is just to tell Sphinx that we're documenting
-    stuff in module foo, but links to module foo won't lead here.
-    """
-
-    has_content = False
-    required_arguments = 1
-    optional_arguments = 0
-    final_argument_whitespace = False
-    option_spec: OptionSpec = {}
-
-    def run(self) -> list[Node]:
-        modname = self.arguments[0].strip()
-        if modname == 'None':
-            self.env.ref_context.pop('py:module', None)
-        else:
-            self.env.ref_context['py:module'] = modname
-        return []
-
-
-class PyXRefRole(XRefRole):
-    def process_link(self, env: BuildEnvironment, refnode: Element,
-                     has_explicit_title: bool, title: str, target: str) -> tuple[str, str]:
-        refnode['py:module'] = env.ref_context.get('py:module')
-        refnode['py:class'] = env.ref_context.get('py:class')
-        if not has_explicit_title:
-            title = title.lstrip('.')    # only has a meaning for the target
-            target = target.lstrip('~')  # only has a meaning for the title
-            # if the first character is a tilde, don't display the module/class
-            # parts of the contents
-            if title[0:1] == '~':
-                title = title[1:]
-                dot = title.rfind('.')
-                if dot != -1:
-                    title = title[dot + 1:]
-        # if the first character is a dot, search more specific namespaces first
-        # else search builtins first
-        if target[0:1] == '.':
-            target = target[1:]
-            refnode['refspecific'] = True
-        return title, target
-
-
-def filter_meta_fields(app: Sphinx, domain: str, objtype: str, content: Element) -> None:
-    """Filter ``:meta:`` field from its docstring."""
-    if domain != 'py':
-        return
-
-    for node in content:
-        if isinstance(node, nodes.field_list):
-            fields = cast(list[nodes.field], node)
-            # removing list items while iterating the list needs reversed()
-            for field in reversed(fields):
-                field_name = cast(nodes.field_body, field[0]).astext().strip()
-                if field_name == 'meta' or field_name.startswith('meta '):
-                    node.remove(field)
-
-
-class PythonModuleIndex(Index):
-    """
-    Index subclass to provide the Python module index.
-    """
-
-    name = 'modindex'
-    localname = _('Python Module Index')
-    shortname = _('modules')
-
-    def generate(self, docnames: Iterable[str] | None = None,
-                 ) -> tuple[list[tuple[str, list[IndexEntry]]], bool]:
-        content: dict[str, list[IndexEntry]] = {}
-        # list of prefixes to ignore
-        ignores: list[str] = self.domain.env.config['modindex_common_prefix']
-        ignores = sorted(ignores, key=len, reverse=True)
-        # list of all modules, sorted by module name
-        modules = sorted(self.domain.data['modules'].items(),
-                         key=lambda x: x[0].lower())
-        # sort out collapsible modules
-        prev_modname = ''
-        num_toplevels = 0
-        for modname, (docname, node_id, synopsis, platforms, deprecated) in modules:
-            if docnames and docname not in docnames:
-                continue
-
-            for ignore in ignores:
-                if modname.startswith(ignore):
-                    modname = modname[len(ignore):]
-                    stripped = ignore
-                    break
-            else:
-                stripped = ''
-
-            # we stripped the whole module name?
-            if not modname:
-                modname, stripped = stripped, ''
-
-            entries = content.setdefault(modname[0].lower(), [])
-
-            package = modname.split('.')[0]
-            if package != modname:
-                # it's a submodule
-                if prev_modname == package:
-                    # first submodule - make parent a group head
-                    if entries:
-                        last = entries[-1]
-                        entries[-1] = IndexEntry(last[0], 1, last[2], last[3],
-                                                 last[4], last[5], last[6])
-                elif not prev_modname.startswith(package):
-                    # submodule without parent in list, add dummy entry
-                    entries.append(IndexEntry(stripped + package, 1, '', '', '', '', ''))
-                subtype = 2
-            else:
-                num_toplevels += 1
-                subtype = 0
-
-            qualifier = _('Deprecated') if deprecated else ''
-            entries.append(IndexEntry(stripped + modname, subtype, docname,
-                                      node_id, platforms, qualifier, synopsis))
-            prev_modname = modname
-
-        # apply heuristics when to collapse modindex at page load:
-        # only collapse if number of toplevel modules is larger than
-        # number of submodules
-        collapse = len(modules) - num_toplevels < num_toplevels
-
-        # sort by first letter
-        sorted_content = sorted(content.items())
-
-        return sorted_content, collapse
-
-
-class PythonDomain(Domain):
-    """Python language domain."""
-    name = 'py'
-    label = 'Python'
-    object_types: dict[str, ObjType] = {
-        'function':     ObjType(_('function'),      'func', 'obj'),
-        'data':         ObjType(_('data'),          'data', 'obj'),
-        'class':        ObjType(_('class'),         'class', 'exc', 'obj'),
-        'exception':    ObjType(_('exception'),     'exc', 'class', 'obj'),
-        'method':       ObjType(_('method'),        'meth', 'obj'),
-        'classmethod':  ObjType(_('class method'),  'meth', 'obj'),
-        'staticmethod': ObjType(_('static method'), 'meth', 'obj'),
-        'attribute':    ObjType(_('attribute'),     'attr', 'obj'),
-        'property':     ObjType(_('property'),      'attr', '_prop', 'obj'),
-        'module':       ObjType(_('module'),        'mod', 'obj'),
-    }
-
-    directives = {
-        'function':        PyFunction,
-        'data':            PyVariable,
-        'class':           PyClasslike,
-        'exception':       PyClasslike,
-        'method':          PyMethod,
-        'classmethod':     PyClassMethod,
-        'staticmethod':    PyStaticMethod,
-        'attribute':       PyAttribute,
-        'property':        PyProperty,
-        'module':          PyModule,
-        'currentmodule':   PyCurrentModule,
-        'decorator':       PyDecoratorFunction,
-        'decoratormethod': PyDecoratorMethod,
-    }
-    roles = {
-        'data':  PyXRefRole(),
-        'exc':   PyXRefRole(),
-        'func':  PyXRefRole(fix_parens=True),
-        'class': PyXRefRole(),
-        'const': PyXRefRole(),
-        'attr':  PyXRefRole(),
-        'meth':  PyXRefRole(fix_parens=True),
-        'mod':   PyXRefRole(),
-        'obj':   PyXRefRole(),
-    }
-    initial_data: dict[str, dict[str, tuple[Any]]] = {
-        'objects': {},  # fullname -> docname, objtype
-        'modules': {},  # modname -> docname, synopsis, platform, deprecated
-    }
-    indices = [
-        PythonModuleIndex,
-    ]
-
-    @property
-    def objects(self) -> dict[str, ObjectEntry]:
-        return self.data.setdefault('objects', {})  # fullname -> ObjectEntry
-
-    def note_object(self, name: str, objtype: str, node_id: str,
-                    aliased: bool = False, location: Any = None) -> None:
-        """Note a python object for cross reference.
-
-        .. versionadded:: 2.1
-        """
-        if name in self.objects:
-            other = self.objects[name]
-            if other.aliased and aliased is False:
-                # The original definition found. Override it!
-                pass
-            elif other.aliased is False and aliased:
-                # The original definition is already registered.
-                return
-            else:
-                # duplicated
-                logger.warning(__('duplicate object description of %s, '
-                                  'other instance in %s, use :no-index: for one of them'),
-                               name, other.docname, location=location)
-        self.objects[name] = ObjectEntry(self.env.docname, node_id, objtype, aliased)
-
-    @property
-    def modules(self) -> dict[str, ModuleEntry]:
-        return self.data.setdefault('modules', {})  # modname -> ModuleEntry
-
-    def note_module(self, name: str, node_id: str, synopsis: str,
-                    platform: str, deprecated: bool) -> None:
-        """Note a python module for cross reference.
-
-        .. versionadded:: 2.1
-        """
-        self.modules[name] = ModuleEntry(self.env.docname, node_id,
-                                         synopsis, platform, deprecated)
-
-    def clear_doc(self, docname: str) -> None:
-        for fullname, obj in list(self.objects.items()):
-            if obj.docname == docname:
-                del self.objects[fullname]
-        for modname, mod in list(self.modules.items()):
-            if mod.docname == docname:
-                del self.modules[modname]
-
-    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
-        # XXX check duplicates?
-        for fullname, obj in otherdata['objects'].items():
-            if obj.docname in docnames:
-                self.objects[fullname] = obj
-        for modname, mod in otherdata['modules'].items():
-            if mod.docname in docnames:
-                self.modules[modname] = mod
-
-    def find_obj(self, env: BuildEnvironment, modname: str, classname: str,
-                 name: str, type: str | None, searchmode: int = 0,
-                 ) -> list[tuple[str, ObjectEntry]]:
-        """Find a Python object for "name", perhaps using the given module
-        and/or classname.  Returns a list of (name, object entry) tuples.
-        """
-        # skip parens
-        if name[-2:] == '()':
-            name = name[:-2]
-
-        if not name:
-            return []
-
-        matches: list[tuple[str, ObjectEntry]] = []
-
-        newname = None
-        if searchmode == 1:
-            if type is None:
-                objtypes: list[str] | None = list(self.object_types)
-            else:
-                objtypes = self.objtypes_for_role(type)
-            if objtypes is not None:
-                if modname and classname:
-                    fullname = modname + '.' + classname + '.' + name
-                    if fullname in self.objects and self.objects[fullname].objtype in objtypes:
-                        newname = fullname
-                if not newname:
-                    if modname and modname + '.' + name in self.objects and \
-                       self.objects[modname + '.' + name].objtype in objtypes:
-                        newname = modname + '.' + name
-                    elif name in self.objects and self.objects[name].objtype in objtypes:
-                        newname = name
-                    else:
-                        # "fuzzy" searching mode
-                        searchname = '.' + name
-                        matches = [(oname, self.objects[oname]) for oname in self.objects
-                                   if oname.endswith(searchname) and
-                                   self.objects[oname].objtype in objtypes]
-        else:
-            # NOTE: searching for exact match, object type is not considered
-            if name in self.objects:
-                newname = name
-            elif type == 'mod':
-                # only exact matches allowed for modules
-                return []
-            elif classname and classname + '.' + name in self.objects:
-                newname = classname + '.' + name
-            elif modname and modname + '.' + name in self.objects:
-                newname = modname + '.' + name
-            elif modname and classname and \
-                    modname + '.' + classname + '.' + name in self.objects:
-                newname = modname + '.' + classname + '.' + name
-        if newname is not None:
-            matches.append((newname, self.objects[newname]))
-        return matches
-
-    def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
-                     type: str, target: str, node: pending_xref, contnode: Element,
-                     ) -> Element | None:
-        modname = node.get('py:module')
-        clsname = node.get('py:class')
-        searchmode = 1 if node.hasattr('refspecific') else 0
-        matches = self.find_obj(env, modname, clsname, target,
-                                type, searchmode)
-
-        if not matches and type == 'attr':
-            # fallback to meth (for property; Sphinx 2.4.x)
-            # this ensures that `:attr:` role continues to refer to the old property entry
-            # that defined by ``method`` directive in old reST files.
-            matches = self.find_obj(env, modname, clsname, target, 'meth', searchmode)
-        if not matches and type == 'meth':
-            # fallback to attr (for property)
-            # this ensures that `:meth:` in the old reST files can refer to the property
-            # entry that defined by ``property`` directive.
-            #
-            # Note: _prop is a secret role only for internal look-up.
-            matches = self.find_obj(env, modname, clsname, target, '_prop', searchmode)
-
-        if not matches:
-            return None
-        elif len(matches) > 1:
-            canonicals = [m for m in matches if not m[1].aliased]
-            if len(canonicals) == 1:
-                matches = canonicals
-            else:
-                logger.warning(__('more than one target found for cross-reference %r: %s'),
-                               target, ', '.join(match[0] for match in matches),
-                               type='ref', subtype='python', location=node)
-        name, obj = matches[0]
-
-        if obj[2] == 'module':
-            return self._make_module_refnode(builder, fromdocname, name, contnode)
-        else:
-            # determine the content of the reference by conditions
-            content = find_pending_xref_condition(node, 'resolved')
-            if content:
-                children = content.children
-            else:
-                # if not found, use contnode
-                children = [contnode]
-
-            return make_refnode(builder, fromdocname, obj[0], obj[1], children, name)
-
-    def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
-                         target: str, node: pending_xref, contnode: Element,
-                         ) -> list[tuple[str, Element]]:
-        modname = node.get('py:module')
-        clsname = node.get('py:class')
-        results: list[tuple[str, Element]] = []
-
-        # always search in "refspecific" mode with the :any: role
-        matches = self.find_obj(env, modname, clsname, target, None, 1)
-        multiple_matches = len(matches) > 1
-
-        for name, obj in matches:
-
-            if multiple_matches and obj.aliased:
-                # Skip duplicated matches
-                continue
-
-            if obj[2] == 'module':
-                results.append(('py:mod',
-                                self._make_module_refnode(builder, fromdocname,
-                                                          name, contnode)))
-            else:
-                # determine the content of the reference by conditions
-                content = find_pending_xref_condition(node, 'resolved')
-                if content:
-                    children = content.children
-                else:
-                    # if not found, use contnode
-                    children = [contnode]
-
-                role = 'py:' + self.role_for_objtype(obj[2])  # type: ignore[operator]
-                results.append((role, make_refnode(builder, fromdocname, obj[0], obj[1],
-                                                   children, name)))
-        return results
-
-    def _make_module_refnode(self, builder: Builder, fromdocname: str, name: str,
-                             contnode: Node) -> Element:
-        # get additional info for modules
-        module = self.modules[name]
-        title = name
-        if module.synopsis:
-            title += ': ' + module.synopsis
-        if module.deprecated:
-            title += _(' (deprecated)')
-        if module.platform:
-            title += ' (' + module.platform + ')'
-        return make_refnode(builder, fromdocname, module.docname, module.node_id,
-                            contnode, title)
-
-    def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]:
-        for modname, mod in self.modules.items():
-            yield (modname, modname, 'module', mod.docname, mod.node_id, 0)
-        for refname, obj in self.objects.items():
-            if obj.objtype != 'module':  # modules are already handled
-                if obj.aliased:
-                    # aliased names are not full-text searchable.
-                    yield (refname, refname, obj.objtype, obj.docname, obj.node_id, -1)
-                else:
-                    yield (refname, refname, obj.objtype, obj.docname, obj.node_id, 1)
-
-    def get_full_qualified_name(self, node: Element) -> str | None:
-        modname = node.get('py:module')
-        clsname = node.get('py:class')
-        target = node.get('reftarget')
-        if target is None:
-            return None
-        else:
-            return '.'.join(filter(None, [modname, clsname, target]))
-
-
-def builtin_resolver(app: Sphinx, env: BuildEnvironment,
-                     node: pending_xref, contnode: Element) -> Element | None:
-    """Do not emit nitpicky warnings for built-in types."""
-    def istyping(s: str) -> bool:
-        if s.startswith('typing.'):
-            s = s.split('.', 1)[1]
-
-        return s in typing.__all__
-
-    if node.get('refdomain') != 'py':
-        return None
-    elif node.get('reftype') in ('class', 'obj') and node.get('reftarget') == 'None':
-        return contnode
-    elif node.get('reftype') in ('class', 'obj', 'exc'):
-        reftarget = node.get('reftarget')
-        if inspect.isclass(getattr(builtins, reftarget, None)):
-            # built-in class
-            return contnode
-        if istyping(reftarget):
-            # typing class
-            return contnode
-
-    return None
-
-
-def setup(app: Sphinx) -> dict[str, Any]:
-    app.setup_extension('sphinx.directives')
-
-    app.add_domain(PythonDomain)
-    app.add_config_value('python_use_unqualified_type_names', False, 'env')
-    app.add_config_value('python_maximum_signature_line_length', None, 'env',
-                         types={int, None})
-    app.add_config_value('python_display_short_literal_types', False, 'env')
-    app.connect('object-description-transform', filter_meta_fields)
-    app.connect('missing-reference', builtin_resolver, priority=900)
-
-    return {
-        'version': 'builtin',
-        'env_version': 4,
-        'parallel_read_safe': True,
-        'parallel_write_safe': True,
-    }