"""Conversion of parse tree nodes to strings."""

from __future__ import annotations

import os
import re
from typing import TYPE_CHECKING, Any, Sequence

import mypy.nodes
from mypy.options import Options
from mypy.util import IdMapper, short_type
from mypy.visitor import NodeVisitor

if TYPE_CHECKING:
    import mypy.patterns
    import mypy.types

class StrConv(NodeVisitor[str]):
    """Visitor for converting a node to a human-readable string.

    For example, an MypyFile node from program '1' is converted into
    something like this:

      MypyFile:1(
        fnam
        ExpressionStmt:1(
          IntExpr(1)))
    """

    __slots__ = ["options", "show_ids", "id_mapper"]

    def __init__(self, *, show_ids: bool = False, options: Options) -> None:
        self.options = options
        self.show_ids = show_ids
        self.id_mapper: IdMapper | None = None
        if show_ids:
            self.id_mapper = IdMapper()

    def stringify_type(self, t: mypy.types.Type) -> str:
        import mypy.types

        return t.accept(mypy.types.TypeStrVisitor(id_mapper=self.id_mapper, options=self.options))

    def get_id(self, o: object) -> int | None:
        if self.id_mapper:
            return self.id_mapper.id(o)
        return None

    def format_id(self, o: object) -> str:
        if self.id_mapper:
            return f"<{self.get_id(o)}>"
        else:
            return ""

    def dump(self, nodes: Sequence[object], obj: mypy.nodes.Context) -> str:
        """Convert a list of items to a multiline pretty-printed string.

        The tag is produced from the type name of obj and its line
        number. See mypy.util.dump_tagged for a description of the nodes
        argument.
        """
        tag = short_type(obj) + ":" + str(obj.line)
        if self.show_ids:
            assert self.id_mapper is not None
            tag += f"<{self.get_id(obj)}>"
        return dump_tagged(nodes, tag, self)

    def func_helper(self, o: mypy.nodes.FuncItem) -> list[object]:
        """Return a list in a format suitable for dump() that represents the
        arguments and the body of a function. The caller can then decorate the
        array with information specific to methods, global functions or
        anonymous functions.
        """
        args: list[mypy.nodes.Var | tuple[str, list[mypy.nodes.Node]]] = []
        extra: list[tuple[str, list[mypy.nodes.Var]]] = []
        for arg in o.arguments:
            kind: mypy.nodes.ArgKind = arg.kind
            if kind.is_required():
                args.append(arg.variable)
            elif kind.is_optional():
                assert arg.initializer is not None
                args.append(("default", [arg.variable, arg.initializer]))
            elif kind == mypy.nodes.ARG_STAR:
                extra.append(("VarArg", [arg.variable]))
            elif kind == mypy.nodes.ARG_STAR2:
                extra.append(("DictVarArg", [arg.variable]))
        a: list[Any] = []
        if o.type_args:
            for p in o.type_args:
                a.append(self.type_param(p))
        if args:
            a.append(("Args", args))
        if o.type:
            a.append(o.type)
        if o.is_generator:
            a.append("Generator")
        a.extend(extra)
        a.append(o.body)
        return a

    # Top-level structures

    def visit_mypy_file(self, o: mypy.nodes.MypyFile) -> str:
        # Skip implicit definitions.
        a: list[Any] = [o.defs]
        if o.is_bom:
            a.insert(0, "BOM")
        # Omit path to special file with name "main". This is used to simplify
        # test case descriptions; the file "main" is used by default in many
        # test cases.
        if o.path != "main":
            # Insert path. Normalize directory separators to / to unify test
            # case# output in all platforms.
            a.insert(0, o.path.replace(os.sep, "/"))
        if o.ignored_lines:
            a.append("IgnoredLines(%s)" % ", ".join(str(line) for line in sorted(o.ignored_lines)))
        return self.dump(a, o)

    def visit_import(self, o: mypy.nodes.Import) -> str:
        a = []
        for id, as_id in o.ids:
            if as_id is not None:
                a.append(f"{id} : {as_id}")
            else:
                a.append(id)
        return f"Import:{o.line}({', '.join(a)})"

    def visit_import_from(self, o: mypy.nodes.ImportFrom) -> str:
        a = []
        for name, as_name in o.names:
            if as_name is not None:
                a.append(f"{name} : {as_name}")
            else:
                a.append(name)
        return f"ImportFrom:{o.line}({'.' * o.relative + o.id}, [{', '.join(a)}])"

    def visit_import_all(self, o: mypy.nodes.ImportAll) -> str:
        return f"ImportAll:{o.line}({'.' * o.relative + o.id})"

    # Definitions

    def visit_func_def(self, o: mypy.nodes.FuncDef) -> str:
        a = self.func_helper(o)
        a.insert(0, o.name)
        arg_kinds = {arg.kind for arg in o.arguments}
        if len(arg_kinds & {mypy.nodes.ARG_NAMED, mypy.nodes.ARG_NAMED_OPT}) > 0:
            a.insert(1, f"MaxPos({o.max_pos})")
        if o.abstract_status in (mypy.nodes.IS_ABSTRACT, mypy.nodes.IMPLICITLY_ABSTRACT):
            a.insert(-1, "Abstract")
        if o.is_static:
            a.insert(-1, "Static")
        if o.is_class:
            a.insert(-1, "Class")
        if o.is_property:
            a.insert(-1, "Property")
        return self.dump(a, o)

    def visit_overloaded_func_def(self, o: mypy.nodes.OverloadedFuncDef) -> str:
        a: Any = o.items.copy()
        if o.type:
            a.insert(0, o.type)
        if o.impl:
            a.insert(0, o.impl)
        if o.is_static:
            a.insert(-1, "Static")
        if o.is_class:
            a.insert(-1, "Class")
        return self.dump(a, o)

    def visit_class_def(self, o: mypy.nodes.ClassDef) -> str:
        a = [o.name, o.defs.body]
        # Display base types unless they are implicitly just builtins.object
        # (in this case base_type_exprs is empty).
        if o.base_type_exprs:
            if o.info and o.info.bases:
                if len(o.info.bases) != 1 or o.info.bases[0].type.fullname != "builtins.object":
                    a.insert(1, ("BaseType", o.info.bases))
            else:
                a.insert(1, ("BaseTypeExpr", o.base_type_exprs))
        if o.type_vars:
            a.insert(1, ("TypeVars", o.type_vars))
        if o.metaclass:
            a.insert(1, f"Metaclass({o.metaclass.accept(self)})")
        if o.decorators:
            a.insert(1, ("Decorators", o.decorators))
        if o.info and o.info._promote:
            a.insert(1, f"Promote([{','.join(self.stringify_type(p) for p in o.info._promote)}])")
        if o.info and o.info.tuple_type:
            a.insert(1, ("TupleType", [o.info.tuple_type]))
        if o.info and o.info.fallback_to_any:
            a.insert(1, "FallbackToAny")
        if o.type_args:
            for p in reversed(o.type_args):
                a.insert(1, self.type_param(p))
        return self.dump(a, o)

    def visit_var(self, o: mypy.nodes.Var) -> str:
        lst = ""
        # Add :nil line number tag if no line number is specified to remain
        # compatible with old test case descriptions that assume this.
        if o.line < 0:
            lst = ":nil"
        return "Var" + lst + "(" + o.name + ")"

    def visit_global_decl(self, o: mypy.nodes.GlobalDecl) -> str:
        return self.dump([o.names], o)

    def visit_nonlocal_decl(self, o: mypy.nodes.NonlocalDecl) -> str:
        return self.dump([o.names], o)

    def visit_decorator(self, o: mypy.nodes.Decorator) -> str:
        return self.dump([o.var, o.decorators, o.func], o)

    # Statements

    def visit_block(self, o: mypy.nodes.Block) -> str:
        return self.dump(o.body, o)

    def visit_expression_stmt(self, o: mypy.nodes.ExpressionStmt) -> str:
        return self.dump([o.expr], o)

    def visit_assignment_stmt(self, o: mypy.nodes.AssignmentStmt) -> str:
        a: list[Any] = []
        if len(o.lvalues) > 1:
            a = [("Lvalues", o.lvalues)]
        else:
            a = [o.lvalues[0]]
        a.append(o.rvalue)
        if o.type:
            a.append(o.type)
        return self.dump(a, o)

    def visit_operator_assignment_stmt(self, o: mypy.nodes.OperatorAssignmentStmt) -> str:
        return self.dump([o.op, o.lvalue, o.rvalue], o)

    def visit_while_stmt(self, o: mypy.nodes.WhileStmt) -> str:
        a: list[Any] = [o.expr, o.body]
        if o.else_body:
            a.append(("Else", o.else_body.body))
        return self.dump(a, o)

    def visit_for_stmt(self, o: mypy.nodes.ForStmt) -> str:
        a: list[Any] = []
        if o.is_async:
            a.append(("Async", ""))
        a.append(o.index)
        if o.index_type:
            a.append(o.index_type)
        a.extend([o.expr, o.body])
        if o.else_body:
            a.append(("Else", o.else_body.body))
        return self.dump(a, o)

    def visit_return_stmt(self, o: mypy.nodes.ReturnStmt) -> str:
        return self.dump([o.expr], o)

    def visit_if_stmt(self, o: mypy.nodes.IfStmt) -> str:
        a: list[Any] = []
        for i in range(len(o.expr)):
            a.append(("If", [o.expr[i]]))
            a.append(("Then", o.body[i].body))

        if not o.else_body:
            return self.dump(a, o)
        else:
            return self.dump([a, ("Else", o.else_body.body)], o)

    def visit_break_stmt(self, o: mypy.nodes.BreakStmt) -> str:
        return self.dump([], o)

    def visit_continue_stmt(self, o: mypy.nodes.ContinueStmt) -> str:
        return self.dump([], o)

    def visit_pass_stmt(self, o: mypy.nodes.PassStmt) -> str:
        return self.dump([], o)

    def visit_raise_stmt(self, o: mypy.nodes.RaiseStmt) -> str:
        return self.dump([o.expr, o.from_expr], o)

    def visit_assert_stmt(self, o: mypy.nodes.AssertStmt) -> str:
        if o.msg is not None:
            return self.dump([o.expr, o.msg], o)
        else:
            return self.dump([o.expr], o)

    def visit_await_expr(self, o: mypy.nodes.AwaitExpr) -> str:
        return self.dump([o.expr], o)

    def visit_del_stmt(self, o: mypy.nodes.DelStmt) -> str:
        return self.dump([o.expr], o)

    def visit_try_stmt(self, o: mypy.nodes.TryStmt) -> str:
        a: list[Any] = [o.body]
        if o.is_star:
            a.append("*")

        for i in range(len(o.vars)):
            a.append(o.types[i])
            if o.vars[i]:
                a.append(o.vars[i])
            a.append(o.handlers[i])

        if o.else_body:
            a.append(("Else", o.else_body.body))
        if o.finally_body:
            a.append(("Finally", o.finally_body.body))

        return self.dump(a, o)

    def visit_with_stmt(self, o: mypy.nodes.WithStmt) -> str:
        a: list[Any] = []
        if o.is_async:
            a.append(("Async", ""))
        for i in range(len(o.expr)):
            a.append(("Expr", [o.expr[i]]))
            if o.target[i]:
                a.append(("Target", [o.target[i]]))
        if o.unanalyzed_type:
            a.append(o.unanalyzed_type)
        return self.dump(a + [o.body], o)

    def visit_match_stmt(self, o: mypy.nodes.MatchStmt) -> str:
        a: list[Any] = [o.subject]
        for i in range(len(o.patterns)):
            a.append(("Pattern", [o.patterns[i]]))
            if o.guards[i] is not None:
                a.append(("Guard", [o.guards[i]]))
            a.append(("Body", o.bodies[i].body))
        return self.dump(a, o)

    def visit_type_alias_stmt(self, o: mypy.nodes.TypeAliasStmt) -> str:
        a: list[Any] = [o.name]
        for p in o.type_args:
            a.append(self.type_param(p))
        a.append(o.value)
        return self.dump(a, o)

    def type_param(self, p: mypy.nodes.TypeParam) -> list[Any]:
        a: list[Any] = []
        if p.kind == mypy.nodes.PARAM_SPEC_KIND:
            prefix = "**"
        elif p.kind == mypy.nodes.TYPE_VAR_TUPLE_KIND:
            prefix = "*"
        else:
            prefix = ""
        a.append(prefix + p.name)
        if p.upper_bound:
            a.append(p.upper_bound)
        if p.values:
            a.append(("Values", p.values))
        return [("TypeParam", a)]

    # Expressions

    # Simple expressions

    def visit_int_expr(self, o: mypy.nodes.IntExpr) -> str:
        return f"IntExpr({o.value})"

    def visit_str_expr(self, o: mypy.nodes.StrExpr) -> str:
        return f"StrExpr({self.str_repr(o.value)})"

    def visit_bytes_expr(self, o: mypy.nodes.BytesExpr) -> str:
        return f"BytesExpr({self.str_repr(o.value)})"

    def str_repr(self, s: str) -> str:
        s = re.sub(r"\\u[0-9a-fA-F]{4}", lambda m: "\\" + m.group(0), s)
        return re.sub("[^\\x20-\\x7e]", lambda m: r"\u%.4x" % ord(m.group(0)), s)

    def visit_float_expr(self, o: mypy.nodes.FloatExpr) -> str:
        return f"FloatExpr({o.value})"

    def visit_complex_expr(self, o: mypy.nodes.ComplexExpr) -> str:
        return f"ComplexExpr({o.value})"

    def visit_ellipsis(self, o: mypy.nodes.EllipsisExpr) -> str:
        return "Ellipsis"

    def visit_star_expr(self, o: mypy.nodes.StarExpr) -> str:
        return self.dump([o.expr], o)

    def visit_name_expr(self, o: mypy.nodes.NameExpr) -> str:
        pretty = self.pretty_name(
            o.name, o.kind, o.fullname, o.is_inferred_def or o.is_special_form, o.node
        )
        if isinstance(o.node, mypy.nodes.Var) and o.node.is_final:
            pretty += f" = {o.node.final_value}"
        return short_type(o) + "(" + pretty + ")"

    def pretty_name(
        self,
        name: str,
        kind: int | None,
        fullname: str | None,
        is_inferred_def: bool,
        target_node: mypy.nodes.Node | None = None,
    ) -> str:
        n = name
        if is_inferred_def:
            n += "*"
        if target_node:
            id = self.format_id(target_node)
        else:
            id = ""
        if isinstance(target_node, mypy.nodes.MypyFile) and name == fullname:
            n += id
        elif kind == mypy.nodes.GDEF or (fullname != name and fullname):
            # Append fully qualified name for global references.
            n += f" [{fullname}{id}]"
        elif kind == mypy.nodes.LDEF:
            # Add tag to signify a local reference.
            n += f" [l{id}]"
        elif kind == mypy.nodes.MDEF:
            # Add tag to signify a member reference.
            n += f" [m{id}]"
        else:
            n += id
        return n

    def visit_member_expr(self, o: mypy.nodes.MemberExpr) -> str:
        pretty = self.pretty_name(o.name, o.kind, o.fullname, o.is_inferred_def, o.node)
        return self.dump([o.expr, pretty], o)

    def visit_yield_expr(self, o: mypy.nodes.YieldExpr) -> str:
        return self.dump([o.expr], o)

    def visit_yield_from_expr(self, o: mypy.nodes.YieldFromExpr) -> str:
        if o.expr:
            return self.dump([o.expr.accept(self)], o)
        else:
            return self.dump([], o)

    def visit_call_expr(self, o: mypy.nodes.CallExpr) -> str:
        if o.analyzed:
            return o.analyzed.accept(self)
        args: list[mypy.nodes.Expression] = []
        extra: list[str | tuple[str, list[Any]]] = []
        for i, kind in enumerate(o.arg_kinds):
            if kind in [mypy.nodes.ARG_POS, mypy.nodes.ARG_STAR]:
                args.append(o.args[i])
                if kind == mypy.nodes.ARG_STAR:
                    extra.append("VarArg")
            elif kind == mypy.nodes.ARG_NAMED:
                extra.append(("KwArgs", [o.arg_names[i], o.args[i]]))
            elif kind == mypy.nodes.ARG_STAR2:
                extra.append(("DictVarArg", [o.args[i]]))
            else:
                raise RuntimeError(f"unknown kind {kind}")
        a: list[Any] = [o.callee, ("Args", args)]
        return self.dump(a + extra, o)

    def visit_op_expr(self, o: mypy.nodes.OpExpr) -> str:
        if o.analyzed:
            return o.analyzed.accept(self)
        return self.dump([o.op, o.left, o.right], o)

    def visit_comparison_expr(self, o: mypy.nodes.ComparisonExpr) -> str:
        return self.dump([o.operators, o.operands], o)

    def visit_cast_expr(self, o: mypy.nodes.CastExpr) -> str:
        return self.dump([o.expr, o.type], o)

    def visit_assert_type_expr(self, o: mypy.nodes.AssertTypeExpr) -> str:
        return self.dump([o.expr, o.type], o)

    def visit_reveal_expr(self, o: mypy.nodes.RevealExpr) -> str:
        if o.kind == mypy.nodes.REVEAL_TYPE:
            return self.dump([o.expr], o)
        else:
            # REVEAL_LOCALS
            return self.dump([o.local_nodes], o)

    def visit_assignment_expr(self, o: mypy.nodes.AssignmentExpr) -> str:
        return self.dump([o.target, o.value], o)

    def visit_unary_expr(self, o: mypy.nodes.UnaryExpr) -> str:
        return self.dump([o.op, o.expr], o)

    def visit_list_expr(self, o: mypy.nodes.ListExpr) -> str:
        return self.dump(o.items, o)

    def visit_dict_expr(self, o: mypy.nodes.DictExpr) -> str:
        return self.dump([[k, v] for k, v in o.items], o)

    def visit_set_expr(self, o: mypy.nodes.SetExpr) -> str:
        return self.dump(o.items, o)

    def visit_tuple_expr(self, o: mypy.nodes.TupleExpr) -> str:
        return self.dump(o.items, o)

    def visit_index_expr(self, o: mypy.nodes.IndexExpr) -> str:
        if o.analyzed:
            return o.analyzed.accept(self)
        return self.dump([o.base, o.index], o)

    def visit_super_expr(self, o: mypy.nodes.SuperExpr) -> str:
        return self.dump([o.name, o.call], o)

    def visit_type_application(self, o: mypy.nodes.TypeApplication) -> str:
        return self.dump([o.expr, ("Types", o.types)], o)

    def visit_type_var_expr(self, o: mypy.nodes.TypeVarExpr) -> str:
        import mypy.types

        a: list[Any] = []
        if o.variance == mypy.nodes.COVARIANT:
            a += ["Variance(COVARIANT)"]
        if o.variance == mypy.nodes.CONTRAVARIANT:
            a += ["Variance(CONTRAVARIANT)"]
        if o.values:
            a += [("Values", o.values)]
        if not mypy.types.is_named_instance(o.upper_bound, "builtins.object"):
            a += [f"UpperBound({self.stringify_type(o.upper_bound)})"]
        return self.dump(a, o)

    def visit_paramspec_expr(self, o: mypy.nodes.ParamSpecExpr) -> str:
        import mypy.types

        a: list[Any] = []
        if o.variance == mypy.nodes.COVARIANT:
            a += ["Variance(COVARIANT)"]
        if o.variance == mypy.nodes.CONTRAVARIANT:
            a += ["Variance(CONTRAVARIANT)"]
        if not mypy.types.is_named_instance(o.upper_bound, "builtins.object"):
            a += [f"UpperBound({self.stringify_type(o.upper_bound)})"]
        return self.dump(a, o)

    def visit_type_var_tuple_expr(self, o: mypy.nodes.TypeVarTupleExpr) -> str:
        import mypy.types

        a: list[Any] = []
        if o.variance == mypy.nodes.COVARIANT:
            a += ["Variance(COVARIANT)"]
        if o.variance == mypy.nodes.CONTRAVARIANT:
            a += ["Variance(CONTRAVARIANT)"]
        if not mypy.types.is_named_instance(o.upper_bound, "builtins.object"):
            a += [f"UpperBound({self.stringify_type(o.upper_bound)})"]
        return self.dump(a, o)

    def visit_type_alias_expr(self, o: mypy.nodes.TypeAliasExpr) -> str:
        return f"TypeAliasExpr({self.stringify_type(o.node.target)})"

    def visit_namedtuple_expr(self, o: mypy.nodes.NamedTupleExpr) -> str:
        return f"NamedTupleExpr:{o.line}({o.info.name}, {self.stringify_type(o.info.tuple_type) if o.info.tuple_type is not None else None})"

    def visit_enum_call_expr(self, o: mypy.nodes.EnumCallExpr) -> str:
        return f"EnumCallExpr:{o.line}({o.info.name}, {o.items})"

    def visit_typeddict_expr(self, o: mypy.nodes.TypedDictExpr) -> str:
        return f"TypedDictExpr:{o.line}({o.info.name})"

    def visit__promote_expr(self, o: mypy.nodes.PromoteExpr) -> str:
        return f"PromoteExpr:{o.line}({self.stringify_type(o.type)})"

    def visit_newtype_expr(self, o: mypy.nodes.NewTypeExpr) -> str:
        return f"NewTypeExpr:{o.line}({o.name}, {self.dump([o.old_type], o)})"

    def visit_lambda_expr(self, o: mypy.nodes.LambdaExpr) -> str:
        a = self.func_helper(o)
        return self.dump(a, o)

    def visit_generator_expr(self, o: mypy.nodes.GeneratorExpr) -> str:
        condlists = o.condlists if any(o.condlists) else None
        return self.dump([o.left_expr, o.indices, o.sequences, condlists], o)

    def visit_list_comprehension(self, o: mypy.nodes.ListComprehension) -> str:
        return self.dump([o.generator], o)

    def visit_set_comprehension(self, o: mypy.nodes.SetComprehension) -> str:
        return self.dump([o.generator], o)

    def visit_dictionary_comprehension(self, o: mypy.nodes.DictionaryComprehension) -> str:
        condlists = o.condlists if any(o.condlists) else None
        return self.dump([o.key, o.value, o.indices, o.sequences, condlists], o)

    def visit_conditional_expr(self, o: mypy.nodes.ConditionalExpr) -> str:
        return self.dump([("Condition", [o.cond]), o.if_expr, o.else_expr], o)

    def visit_slice_expr(self, o: mypy.nodes.SliceExpr) -> str:
        a: list[Any] = [o.begin_index, o.end_index, o.stride]
        if not a[0]:
            a[0] = "<empty>"
        if not a[1]:
            a[1] = "<empty>"
        return self.dump(a, o)

    def visit_temp_node(self, o: mypy.nodes.TempNode) -> str:
        return self.dump([o.type], o)

    def visit_as_pattern(self, o: mypy.patterns.AsPattern) -> str:
        return self.dump([o.pattern, o.name], o)

    def visit_or_pattern(self, o: mypy.patterns.OrPattern) -> str:
        return self.dump(o.patterns, o)

    def visit_value_pattern(self, o: mypy.patterns.ValuePattern) -> str:
        return self.dump([o.expr], o)

    def visit_singleton_pattern(self, o: mypy.patterns.SingletonPattern) -> str:
        return self.dump([o.value], o)

    def visit_sequence_pattern(self, o: mypy.patterns.SequencePattern) -> str:
        return self.dump(o.patterns, o)

    def visit_starred_pattern(self, o: mypy.patterns.StarredPattern) -> str:
        return self.dump([o.capture], o)

    def visit_mapping_pattern(self, o: mypy.patterns.MappingPattern) -> str:
        a: list[Any] = []
        for i in range(len(o.keys)):
            a.append(("Key", [o.keys[i]]))
            a.append(("Value", [o.values[i]]))
        if o.rest is not None:
            a.append(("Rest", [o.rest]))
        return self.dump(a, o)

    def visit_class_pattern(self, o: mypy.patterns.ClassPattern) -> str:
        a: list[Any] = [o.class_ref]
        if len(o.positionals) > 0:
            a.append(("Positionals", o.positionals))
        for i in range(len(o.keyword_keys)):
            a.append(("Keyword", [o.keyword_keys[i], o.keyword_values[i]]))

        return self.dump(a, o)

def dump_tagged(nodes: Sequence[object], tag: str | None, str_conv: StrConv) -> str:
    """Convert an array into a pretty-printed multiline string representation.

    The format is
      tag(
        item1..
        itemN)
    Individual items are formatted like this:
     - arrays are flattened
     - pairs (str, array) are converted recursively, so that str is the tag
     - other items are converted to strings and indented
    """
    from mypy.types import Type, TypeStrVisitor

    a: list[str] = []
    if tag:
        a.append(tag + "(")
    for n in nodes:
        if isinstance(n, list):
            if n:
                a.append(dump_tagged(n, None, str_conv))
        elif isinstance(n, tuple):
            s = dump_tagged(n[1], n[0], str_conv)
            a.append(indent(s, 2))
        elif isinstance(n, mypy.nodes.Node):
            a.append(indent(n.accept(str_conv), 2))
        elif isinstance(n, Type):
            a.append(
                indent(n.accept(TypeStrVisitor(str_conv.id_mapper, options=str_conv.options)), 2)
            )
        elif n is not None:
            a.append(indent(str(n), 2))
    if tag:
        a[-1] += ")"
    return "\n".join(a)

def indent(s: str, n: int) -> str:
    """Indent all the lines in s (separated by newlines) by n spaces."""
    s = " " * n + s
    s = s.replace("\n", "\n" + " " * n)
    return s


"""Parsing/inferring signatures from documentation.

This module provides several functions to generate better stubs using
docstrings and Sphinx docs (.rst files).
"""

from __future__ import annotations

import contextlib
import io
import keyword
import re
import tokenize
from typing import Any, Final, MutableMapping, MutableSequence, NamedTuple, Sequence, Tuple
from typing_extensions import TypeAlias as _TypeAlias

import mypy.util

# Type alias for signatures strings in format ('func_name', '(arg, opt_arg=False)').
Sig: _TypeAlias = Tuple[str, str]

_TYPE_RE: Final = re.compile(r"^[a-zA-Z_][\w\[\], .\"\']*(\.[a-zA-Z_][\w\[\], ]*)*$")
_ARG_NAME_RE: Final = re.compile(r"\**[A-Za-z_][A-Za-z0-9_]*$")

def is_valid_type(s: str) -> bool:
    """Try to determine whether a string might be a valid type annotation."""
    if s in ("True", "False", "retval"):
        return False
    if "," in s and "[" not in s:
        return False
    return _TYPE_RE.match(s) is not None

class ArgSig:
    """Signature info for a single argument."""

    def __init__(
        self,
        name: str,
        type: str | None = None,
        *,
        default: bool = False,
        default_value: str = "...",
    ) -> None:
        self.name = name
        self.type = type
        # Does this argument have a default value?
        self.default = default
        self.default_value = default_value

    def is_star_arg(self) -> bool:
        return self.name.startswith("*") and not self.name.startswith("**")

    def is_star_kwarg(self) -> bool:
        return self.name.startswith("**")

    def __repr__(self) -> str:
        return "ArgSig(name={}, type={}, default={})".format(
            repr(self.name), repr(self.type), repr(self.default)
        )

    def __eq__(self, other: Any) -> bool:
        if isinstance(other, ArgSig):
            return (
                self.name == other.name
                and self.type == other.type
                and self.default == other.default
                and self.default_value == other.default_value
            )
        return False

class FunctionSig(NamedTuple):
    name: str
    args: list[ArgSig]
    ret_type: str | None

    def is_special_method(self) -> bool:
        return bool(
            self.name.startswith("__")
            and self.name.endswith("__")
            and self.args
            and self.args[0].name in ("self", "cls")
        )

    def has_catchall_args(self) -> bool:
        """Return if this signature has catchall args: (*args, **kwargs)"""
        if self.args and self.args[0].name in ("self", "cls"):
            args = self.args[1:]
        else:
            args = self.args
        return (
            len(args) == 2
            and all(a.type in (None, "object", "Any", "typing.Any") for a in args)
            and args[0].is_star_arg()
            and args[1].is_star_kwarg()
        )

    def is_catchall_signature(self) -> bool:
        """Return if this signature is the catchall identity: (*args, **kwargs) -> Any"""
        return self.has_catchall_args() and self.ret_type in (None, "Any", "typing.Any")

    def format_sig(
        self,
        indent: str = "",
        is_async: bool = False,
        any_val: str | None = None,
        docstring: str | None = None,
    ) -> str:
        args: list[str] = []
        for arg in self.args:
            arg_def = arg.name

            if arg_def in keyword.kwlist:
                arg_def = "_" + arg_def

            if (
                arg.type is None
                and any_val is not None
                and arg.name not in ("self", "cls")
                and not arg.name.startswith("*")
            ):
                arg_type: str | None = any_val
            else:
                arg_type = arg.type
            if arg_type:
                arg_def += ": " + arg_type
                if arg.default:
                    arg_def += f" = {arg.default_value}"

            elif arg.default:
                arg_def += f"={arg.default_value}"

            args.append(arg_def)

        retfield = ""
        ret_type = self.ret_type if self.ret_type else any_val
        if ret_type is not None:
            retfield = " -> " + ret_type

        prefix = "async " if is_async else ""
        sig = "{indent}{prefix}def {name}({args}){ret}:".format(
            indent=indent, prefix=prefix, name=self.name, args=", ".join(args), ret=retfield
        )
        if docstring:
            suffix = f"\n{indent}    {mypy.util.quote_docstring(docstring)}"
        else:
            suffix = " ..."
        return f"{sig}{suffix}"

# States of the docstring parser.
STATE_INIT: Final = 1
STATE_FUNCTION_NAME: Final = 2
STATE_ARGUMENT_LIST: Final = 3
STATE_ARGUMENT_TYPE: Final = 4
STATE_ARGUMENT_DEFAULT: Final = 5
STATE_RETURN_VALUE: Final = 6
STATE_OPEN_BRACKET: Final = 7  # For generic types.

class DocStringParser:
    """Parse function signatures in documentation."""

    def __init__(self, function_name: str) -> None:
        # Only search for signatures of function with this name.
        self.function_name = function_name
        self.state = [STATE_INIT]
        self.accumulator = ""
        self.arg_type: str | None = None
        self.arg_name = ""
        self.arg_default: str | None = None
        self.ret_type = "Any"
        self.found = False
        self.args: list[ArgSig] = []
        # Valid signatures found so far.
        self.signatures: list[FunctionSig] = []

    def add_token(self, token: tokenize.TokenInfo) -> None:
        """Process next token from the token stream."""
        if (
            token.type == tokenize.NAME
            and token.string == self.function_name
            and self.state[-1] == STATE_INIT
        ):
            self.state.append(STATE_FUNCTION_NAME)

        elif (
            token.type == tokenize.OP
            and token.string == "("
            and self.state[-1] == STATE_FUNCTION_NAME
        ):
            self.state.pop()
            self.accumulator = ""
            self.found = True
            self.state.append(STATE_ARGUMENT_LIST)

        elif self.state[-1] == STATE_FUNCTION_NAME:
            # Reset state, function name not followed by '('.
            self.state.pop()

        elif (
            token.type == tokenize.OP
            and token.string in ("[", "(", "{")
            and self.state[-1] != STATE_INIT
        ):
            self.accumulator += token.string
            self.state.append(STATE_OPEN_BRACKET)

        elif (
            token.type == tokenize.OP
            and token.string in ("]", ")", "}")
            and self.state[-1] == STATE_OPEN_BRACKET
        ):
            self.accumulator += token.string
            self.state.pop()

        elif (
            token.type == tokenize.OP
            and token.string == ":"
            and self.state[-1] == STATE_ARGUMENT_LIST
        ):
            self.arg_name = self.accumulator
            self.accumulator = ""
            self.state.append(STATE_ARGUMENT_TYPE)

        elif (
            token.type == tokenize.OP
            and token.string == "="
            and self.state[-1] in (STATE_ARGUMENT_LIST, STATE_ARGUMENT_TYPE)
        ):
            if self.state[-1] == STATE_ARGUMENT_TYPE:
                self.arg_type = self.accumulator
                self.state.pop()
            else:
                self.arg_name = self.accumulator
            self.accumulator = ""
            self.state.append(STATE_ARGUMENT_DEFAULT)

        elif (
            token.type == tokenize.OP
            and token.string in (",", ")")
            and self.state[-1]
            in (STATE_ARGUMENT_LIST, STATE_ARGUMENT_DEFAULT, STATE_ARGUMENT_TYPE)
        ):
            if self.state[-1] == STATE_ARGUMENT_DEFAULT:
                self.arg_default = self.accumulator
                self.state.pop()
            elif self.state[-1] == STATE_ARGUMENT_TYPE:
                self.arg_type = self.accumulator
                self.state.pop()
            elif self.state[-1] == STATE_ARGUMENT_LIST:
                self.arg_name = self.accumulator
                if not (
                    token.string == ")" and self.accumulator.strip() == ""
                ) and not _ARG_NAME_RE.match(self.arg_name):
                    # Invalid argument name.
                    self.reset()
                    return

            if token.string == ")":
                self.state.pop()

            # arg_name is empty when there are no args. e.g. func()
            if self.arg_name:
                if self.arg_type and not is_valid_type(self.arg_type):
                    # wrong type, use Any
                    self.args.append(
                        ArgSig(name=self.arg_name, type=None, default=bool(self.arg_default))
                    )
                else:
                    self.args.append(
                        ArgSig(
                            name=self.arg_name, type=self.arg_type, default=bool(self.arg_default)
                        )
                    )
            self.arg_name = ""
            self.arg_type = None
            self.arg_default = None
            self.accumulator = ""

        elif token.type == tokenize.OP and token.string == "->" and self.state[-1] == STATE_INIT:
            self.accumulator = ""
            self.state.append(STATE_RETURN_VALUE)

        # ENDMAKER is necessary for python 3.4 and 3.5.
        elif token.type in (tokenize.NEWLINE, tokenize.ENDMARKER) and self.state[-1] in (
            STATE_INIT,
            STATE_RETURN_VALUE,
        ):
            if self.state[-1] == STATE_RETURN_VALUE:
                if not is_valid_type(self.accumulator):
                    self.reset()
                    return
                self.ret_type = self.accumulator
                self.accumulator = ""
                self.state.pop()

            if self.found:
                self.signatures.append(
                    FunctionSig(name=self.function_name, args=self.args, ret_type=self.ret_type)
                )
                self.found = False
            self.args = []
            self.ret_type = "Any"
            # Leave state as INIT.
        else:
            self.accumulator += token.string

    def reset(self) -> None:
        self.state = [STATE_INIT]
        self.args = []
        self.found = False
        self.accumulator = ""

    def get_signatures(self) -> list[FunctionSig]:
        """Return sorted copy of the list of signatures found so far."""

        def has_arg(name: str, signature: FunctionSig) -> bool:
            return any(x.name == name for x in signature.args)

        def args_kwargs(signature: FunctionSig) -> bool:
            return has_arg("*args", signature) and has_arg("**kwargs", signature)

        # Move functions with (*args, **kwargs) in their signature to last place.
        return sorted(self.signatures, key=lambda x: 1 if args_kwargs(x) else 0)

def infer_sig_from_docstring(docstr: str | None, name: str) -> list[FunctionSig] | None:
    """Convert function signature to list of FunctionSig

    Look for function signatures of function in docstring. Signature is a string of
    the format <function_name>(<signature>) -> <return type> or perhaps without
    the return type.

    Returns empty list, when no signature is found, one signature in typical case,
    multiple signatures, if docstring specifies multiple signatures for overload functions.
    Return None if the docstring is empty.

    Arguments:
        * docstr: docstring
        * name: name of function for which signatures are to be found
    """
    if not (isinstance(docstr, str) and docstr):
        return None

    state = DocStringParser(name)
    # Return all found signatures, even if there is a parse error after some are found.
    with contextlib.suppress(tokenize.TokenError):
        try:
            tokens = tokenize.tokenize(io.BytesIO(docstr.encode("utf-8")).readline)
            for token in tokens:
                state.add_token(token)
        except IndentationError:
            return None
    sigs = state.get_signatures()

    def is_unique_args(sig: FunctionSig) -> bool:
        """return true if function argument names are unique"""
        return len(sig.args) == len({arg.name for arg in sig.args})

    # Return only signatures that have unique argument names. Mypy fails on non-unique arg names.
    return [sig for sig in sigs if is_unique_args(sig)]

def infer_arg_sig_from_anon_docstring(docstr: str) -> list[ArgSig]:
    """Convert signature in form of "(self: TestClass, arg0: str='ada')" to List[TypedArgList]."""
    ret = infer_sig_from_docstring("stub" + docstr, "stub")
    if ret:
        return ret[0].args
    return []

def infer_ret_type_sig_from_docstring(docstr: str, name: str) -> str | None:
    """Convert signature in form of "func(self: TestClass, arg0) -> int" to their return type."""
    ret = infer_sig_from_docstring(docstr, name)
    if ret:
        return ret[0].ret_type
    return None

def infer_ret_type_sig_from_anon_docstring(docstr: str) -> str | None:
    """Convert signature in form of "(self: TestClass, arg0) -> int" to their return type."""
    lines = ["stub" + line.strip() for line in docstr.splitlines() if line.strip().startswith("(")]
    return infer_ret_type_sig_from_docstring("".join(lines), "stub")

def parse_signature(sig: str) -> tuple[str, list[str], list[str]] | None:
    """Split function signature into its name, positional an optional arguments.

    The expected format is "func_name(arg, opt_arg=False)". Return the name of function
    and lists of positional and optional argument names.
    """
    m = re.match(r"([.a-zA-Z0-9_]+)\(([^)]*)\)", sig)
    if not m:
        return None
    name = m.group(1)
    name = name.split(".")[-1]
    arg_string = m.group(2)
    if not arg_string.strip():
        # Simple case -- no arguments.
        return name, [], []

    args = [arg.strip() for arg in arg_string.split(",")]
    positional = []
    optional = []
    i = 0
    while i < len(args):
        # Accept optional arguments as in both formats: x=None and [x].
        if args[i].startswith("[") or "=" in args[i]:
            break
        positional.append(args[i].rstrip("["))
        i += 1
        if args[i - 1].endswith("["):
            break
    while i < len(args):
        arg = args[i]
        arg = arg.strip("[]")
        arg = arg.split("=")[0]
        optional.append(arg)
        i += 1
    return name, positional, optional

def build_signature(positional: Sequence[str], optional: Sequence[str]) -> str:
    """Build function signature from lists of positional and optional argument names."""
    args: MutableSequence[str] = []
    args.extend(positional)
    for arg in optional:
        if arg.startswith("*"):
            args.append(arg)
        else:
            args.append(f"{arg}=...")
    sig = f"({', '.join(args)})"
    # Ad-hoc fixes.
    sig = sig.replace("(self)", "")
    return sig

def parse_all_signatures(lines: Sequence[str]) -> tuple[list[Sig], list[Sig]]:
    """Parse all signatures in a given reST document.

    Return lists of found signatures for functions and classes.
    """
    sigs = []
    class_sigs = []
    for line in lines:
        line = line.strip()
        m = re.match(r"\.\. *(function|method|class) *:: *[a-zA-Z_]", line)
        if m:
            sig = line.split("::")[1].strip()
            parsed = parse_signature(sig)
            if parsed:
                name, fixed, optional = parsed
                if m.group(1) != "class":
                    sigs.append((name, build_signature(fixed, optional)))
                else:
                    class_sigs.append((name, build_signature(fixed, optional)))

    return sorted(sigs), sorted(class_sigs)

def find_unique_signatures(sigs: Sequence[Sig]) -> list[Sig]:
    """Remove names with duplicate found signatures."""
    sig_map: MutableMapping[str, list[str]] = {}
    for name, sig in sigs:
        sig_map.setdefault(name, []).append(sig)

    result = []
    for name, name_sigs in sig_map.items():
        if len(set(name_sigs)) == 1:
            result.append((name, name_sigs[0]))
    return sorted(result)

def infer_prop_type_from_docstring(docstr: str | None) -> str | None:
    """Check for Google/Numpy style docstring type annotation for a property.

    The docstring has the format "<type>: <descriptions>".
    In the type string, we allow the following characters:
    * dot: because sometimes classes are annotated using full path
    * brackets: to allow type hints like List[int]
    * comma/space: things like Tuple[int, int]
    """
    if not docstr:
        return None
    test_str = r"^([a-zA-Z0-9_, \.\[\]]*): "
    m = re.match(test_str, docstr)
    return m.group(1) if m else None