stubutil.py

"""Utilities for mypy.stubgen, mypy.stubgenc, and mypy.stubdoc modules."""

from __future__ import annotations

import os.path
import re
import sys
import traceback
from abc import abstractmethod
from collections import defaultdict
from collections.abc import Iterable, Iterator, Mapping
from contextlib import contextmanager
from typing import Final, overload

from mypy_extensions import mypyc_attr

import mypy.options
from mypy.modulefinder import ModuleNotFoundReason
from mypy.moduleinspect import InspectError, ModuleInspect
from mypy.nodes import PARAM_SPEC_KIND, TYPE_VAR_TUPLE_KIND, ClassDef, FuncDef, TypeAliasStmt
from mypy.stubdoc import ArgSig, FunctionSig
from mypy.types import (
    AnyType,
    NoneType,
    Type,
    TypeList,
    TypeStrVisitor,
    UnboundType,
    UnionType,
    UnpackType,
)

# Modules that may fail when imported, or that may have side effects (fully qualified).
NOT_IMPORTABLE_MODULES = ()

# Typing constructs to be replaced by their builtin equivalents.
TYPING_BUILTIN_REPLACEMENTS: Final = {
    # From typing
    "typing.Text": "builtins.str",
    "typing.Tuple": "builtins.tuple",
    "typing.List": "builtins.list",
    "typing.Dict": "builtins.dict",
    "typing.Set": "builtins.set",
    "typing.FrozenSet": "builtins.frozenset",
    "typing.Type": "builtins.type",
    # From typing_extensions
    "typing_extensions.Text": "builtins.str",
    "typing_extensions.Tuple": "builtins.tuple",
    "typing_extensions.List": "builtins.list",
    "typing_extensions.Dict": "builtins.dict",
    "typing_extensions.Set": "builtins.set",
    "typing_extensions.FrozenSet": "builtins.frozenset",
    "typing_extensions.Type": "builtins.type",
}


class CantImport(Exception):
    def __init__(self, module: str, message: str) -> None:
        self.module = module
        self.message = message


def walk_packages(
    inspect: ModuleInspect, packages: list[str], verbose: bool = False
) -> Iterator[str]:
    """Iterates through all packages and sub-packages in the given list.

    This uses runtime imports (in another process) to find both Python and C modules.
    For Python packages we simply pass the __path__ attribute to pkgutil.walk_packages() to
    get the content of the package (all subpackages and modules).  However, packages in C
    extensions do not have this attribute, so we have to roll out our own logic: recursively
    find all modules imported in the package that have matching names.
    """
    for package_name in packages:
        if package_name in NOT_IMPORTABLE_MODULES:
            print(f"{package_name}: Skipped (blacklisted)")
            continue
        if verbose:
            print(f"Trying to import {package_name!r} for runtime introspection")
        try:
            prop = inspect.get_package_properties(package_name)
        except InspectError:
            if verbose:
                tb = traceback.format_exc()
                sys.stderr.write(tb)
            report_missing(package_name)
            continue
        yield prop.name
        if prop.is_c_module:
            # Recursively iterate through the subpackages
            yield from walk_packages(inspect, prop.subpackages, verbose)
        else:
            yield from prop.subpackages


def find_module_path_using_sys_path(module: str, sys_path: list[str]) -> str | None:
    relative_candidates = (
        module.replace(".", "/") + ".py",
        os.path.join(module.replace(".", "/"), "__init__.py"),
    )
    for base in sys_path:
        for relative_path in relative_candidates:
            path = os.path.join(base, relative_path)
            if os.path.isfile(path):
                return path
    return None


def find_module_path_and_all_py3(
    inspect: ModuleInspect, module: str, verbose: bool
) -> tuple[str | None, list[str] | None] | None:
    """Find module and determine __all__ for a Python 3 module.

    Return None if the module is a C or pyc-only module.
    Return (module_path, __all__) if it is a Python module.
    Raise CantImport if import failed.
    """
    if module in NOT_IMPORTABLE_MODULES:
        raise CantImport(module, "")

    # TODO: Support custom interpreters.
    if verbose:
        print(f"Trying to import {module!r} for runtime introspection")
    try:
        mod = inspect.get_package_properties(module)
    except InspectError as e:
        # Fall back to finding the module using sys.path.
        path = find_module_path_using_sys_path(module, sys.path)
        if path is None:
            raise CantImport(module, str(e)) from e
        return path, None
    if mod.is_c_module:
        return None
    return mod.file, mod.all


@contextmanager
def generate_guarded(
    mod: str, target: str, ignore_errors: bool = True, verbose: bool = False
) -> Iterator[None]:
    """Ignore or report errors during stub generation.

    Optionally report success.
    """
    if verbose:
        print(f"Processing {mod}")
    try:
        yield
    except Exception as e:
        if not ignore_errors:
            raise e
        else:
            # --ignore-errors was passed
            print("Stub generation failed for", mod, file=sys.stderr)
    else:
        if verbose:
            print(f"Created {target}")


def report_missing(mod: str, message: str | None = "", traceback: str = "") -> None:
    if message:
        message = " with error: " + message
    print(f"{mod}: Failed to import, skipping{message}")


def fail_missing(mod: str, reason: ModuleNotFoundReason) -> None:
    if reason is ModuleNotFoundReason.NOT_FOUND:
        clarification = "(consider using --search-path)"
    elif reason is ModuleNotFoundReason.FOUND_WITHOUT_TYPE_HINTS:
        clarification = "(module likely exists, but is not PEP 561 compatible)"
    else:
        clarification = f"(unknown reason '{reason}')"
    raise SystemExit(f"Can't find module '{mod}' {clarification}")


@overload
def remove_misplaced_type_comments(source: bytes) -> bytes: ...


@overload
def remove_misplaced_type_comments(source: str) -> str: ...


def remove_misplaced_type_comments(source: str | bytes) -> str | bytes:
    """Remove comments from source that could be understood as misplaced type comments.

    Normal comments may look like misplaced type comments, and since they cause blocking
    parse errors, we want to avoid them.
    """
    if isinstance(source, bytes):
        # This gives us a 1-1 character code mapping, so it's roundtrippable.
        text = source.decode("latin1")
    else:
        text = source

    # Remove something that looks like a variable type comment but that's by itself
    # on a line, as it will often generate a parse error (unless it's # type: ignore).
    text = re.sub(r'^[ \t]*# +type: +["\'a-zA-Z_].*$', "", text, flags=re.MULTILINE)

    # Remove something that looks like a function type comment after docstring,
    # which will result in a parse error.
    text = re.sub(r'""" *\n[ \t\n]*# +type: +\(.*$', '"""\n', text, flags=re.MULTILINE)
    text = re.sub(r"''' *\n[ \t\n]*# +type: +\(.*$", "'''\n", text, flags=re.MULTILINE)

    # Remove something that looks like a badly formed function type comment.
    text = re.sub(r"^[ \t]*# +type: +\([^()]+(\)[ \t]*)?$", "", text, flags=re.MULTILINE)

    if isinstance(source, bytes):
        return text.encode("latin1")
    else:
        return text


def common_dir_prefix(paths: list[str]) -> str:
    if not paths:
        return "."
    cur = os.path.dirname(os.path.normpath(paths[0]))
    for path in paths[1:]:
        while True:
            path = os.path.dirname(os.path.normpath(path))
            if (cur + os.sep).startswith(path + os.sep):
                cur = path
                break
    return cur or "."


class AnnotationPrinter(TypeStrVisitor):
    """Visitor used to print existing annotations in a file.

    The main difference from TypeStrVisitor is a better treatment of
    unbound types.

    Notes:
    * This visitor doesn't add imports necessary for annotations, this is done separately
      by ImportTracker.
    * It can print all kinds of types, but the generated strings may not be valid (notably
      callable types) since it prints the same string that reveal_type() does.
    * For Instance types it prints the fully qualified names.
    """

    # TODO: Generate valid string representation for callable types.
    # TODO: Use short names for Instances.
    def __init__(
        self,
        stubgen: BaseStubGenerator,
        known_modules: list[str] | None = None,
        local_modules: list[str] | None = None,
    ) -> None:
        super().__init__(options=mypy.options.Options())
        self.stubgen = stubgen
        self.known_modules = known_modules
        self.local_modules = local_modules or ["builtins"]

    def visit_any(self, t: AnyType) -> str:
        s = super().visit_any(t)
        self.stubgen.import_tracker.require_name(s)
        return s

    def visit_unbound_type(self, t: UnboundType) -> str:
        s = t.name
        fullname = self.stubgen.resolve_name(s)
        if fullname == "typing.Union":
            return " | ".join([item.accept(self) for item in t.args])
        if fullname == "typing.Optional":
            if len(t.args) == 1:
                return f"{t.args[0].accept(self)} | None"
            return self.stubgen.add_name("_typeshed.Incomplete")
        if fullname in TYPING_BUILTIN_REPLACEMENTS:
            s = self.stubgen.add_name(TYPING_BUILTIN_REPLACEMENTS[fullname], require=True)
        if self.known_modules is not None and "." in s:
            # see if this object is from any of the modules that we're currently processing.
            # reverse sort so that subpackages come before parents: e.g. "foo.bar" before "foo".
            for module_name in self.local_modules + sorted(self.known_modules, reverse=True):
                if s.startswith(module_name + "."):
                    if module_name in self.local_modules:
                        s = s[len(module_name) + 1 :]
                    arg_module = module_name
                    break
            else:
                arg_module = s[: s.rindex(".")]
            if arg_module not in self.local_modules:
                self.stubgen.import_tracker.add_import(arg_module, require=True)
        elif s == "NoneType":
            # when called without analysis all types are unbound, so this won't hit
            # visit_none_type().
            s = "None"
        else:
            self.stubgen.import_tracker.require_name(s)
        if t.args:
            s += f"[{self.args_str(t.args)}]"
        elif t.empty_tuple_index:
            s += "[()]"
        return s

    def visit_none_type(self, t: NoneType) -> str:
        return "None"

    def visit_type_list(self, t: TypeList) -> str:
        return f"[{self.list_str(t.items)}]"

    def visit_union_type(self, t: UnionType) -> str:
        return " | ".join([item.accept(self) for item in t.items])

    def visit_unpack_type(self, t: UnpackType) -> str:
        if self.options.python_version >= (3, 11):
            return f"*{t.type.accept(self)}"
        return super().visit_unpack_type(t)

    def args_str(self, args: Iterable[Type]) -> str:
        """Convert an array of arguments to strings and join the results with commas.

        The main difference from list_str is the preservation of quotes for string
        arguments
        """
        types = ["builtins.bytes", "builtins.str"]
        res = []
        for arg in args:
            arg_str = arg.accept(self)
            if isinstance(arg, UnboundType) and arg.original_str_fallback in types:
                res.append(f"'{arg_str}'")
            else:
                res.append(arg_str)
        return ", ".join(res)


class ClassInfo:
    def __init__(
        self,
        name: str,
        self_var: str,
        docstring: str | None = None,
        cls: type | None = None,
        parent: ClassInfo | None = None,
    ) -> None:
        self.name = name
        self.self_var = self_var
        self.docstring = docstring
        self.cls = cls
        self.parent = parent


class FunctionContext:
    def __init__(
        self,
        module_name: str,
        name: str,
        docstring: str | None = None,
        is_abstract: bool = False,
        class_info: ClassInfo | None = None,
    ) -> None:
        self.module_name = module_name
        self.name = name
        self.docstring = docstring
        self.is_abstract = is_abstract
        self.class_info = class_info
        self._fullname: str | None = None

    @property
    def fullname(self) -> str:
        if self._fullname is None:
            if self.class_info:
                parents = []
                class_info: ClassInfo | None = self.class_info
                while class_info is not None:
                    parents.append(class_info.name)
                    class_info = class_info.parent
                namespace = ".".join(reversed(parents))
                self._fullname = f"{self.module_name}.{namespace}.{self.name}"
            else:
                self._fullname = f"{self.module_name}.{self.name}"
        return self._fullname


def infer_method_ret_type(name: str) -> str | None:
    """Infer return types for known special methods"""
    if name.startswith("__") and name.endswith("__"):
        name = name[2:-2]
        if name in ("float", "bool", "bytes", "int", "complex", "str"):
            return name
        # Note: __eq__ and co may return arbitrary types, but bool is good enough for stubgen.
        elif name in ("eq", "ne", "lt", "le", "gt", "ge", "contains"):
            return "bool"
        elif name in ("len", "length_hint", "index", "hash", "sizeof", "trunc", "floor", "ceil"):
            return "int"
        elif name in ("format", "repr"):
            return "str"
        elif name in ("init", "setitem", "del", "delitem"):
            return "None"
    return None


def infer_method_arg_types(
    name: str, self_var: str = "self", arg_names: list[str] | None = None
) -> list[ArgSig] | None:
    """Infer argument types for known special methods"""
    args: list[ArgSig] | None = None
    if name.startswith("__") and name.endswith("__"):
        if arg_names and len(arg_names) >= 1 and arg_names[0] == "self":
            arg_names = arg_names[1:]

        name = name[2:-2]
        if name == "exit":
            if arg_names is None:
                arg_names = ["type", "value", "traceback"]
            if len(arg_names) == 3:
                arg_types = [
                    "type[BaseException] | None",
                    "BaseException | None",
                    "types.TracebackType | None",
                ]
                args = [
                    ArgSig(name=arg_name, type=arg_type)
                    for arg_name, arg_type in zip(arg_names, arg_types)
                ]
    if args is not None:
        return [ArgSig(name=self_var)] + args
    return None


@mypyc_attr(allow_interpreted_subclasses=True)
class SignatureGenerator:
    """Abstract base class for extracting a list of FunctionSigs for each function."""

    def remove_self_type(
        self, inferred: list[FunctionSig] | None, self_var: str
    ) -> list[FunctionSig] | None:
        """Remove type annotation from self/cls argument"""
        if inferred:
            for signature in inferred:
                if signature.args:
                    if signature.args[0].name == self_var:
                        signature.args[0].type = None
        return inferred

    @abstractmethod
    def get_function_sig(
        self, default_sig: FunctionSig, ctx: FunctionContext
    ) -> list[FunctionSig] | None:
        """Return a list of signatures for the given function.

        If no signature can be found, return None. If all of the registered SignatureGenerators
        for the stub generator return None, then the default_sig will be used.
        """
        pass

    @abstractmethod
    def get_property_type(self, default_type: str | None, ctx: FunctionContext) -> str | None:
        """Return the type of the given property"""
        pass


class ImportTracker:
    """Record necessary imports during stub generation."""

    def __init__(self) -> None:
        # module_for['foo'] has the module name where 'foo' was imported from, or None if
        # 'foo' is a module imported directly;
        # direct_imports['foo'] is the module path used when the name 'foo' was added to the
        # namespace.
        # reverse_alias['foo'] is the name that 'foo' had originally when imported with an
        # alias; examples
        #     'from pkg import mod'      ==> module_for['mod'] == 'pkg'
        #     'from pkg import mod as m' ==> module_for['m'] == 'pkg'
        #                                ==> reverse_alias['m'] == 'mod'
        #     'import pkg.mod as m'      ==> module_for['m'] == None
        #                                ==> reverse_alias['m'] == 'pkg.mod'
        #     'import pkg.mod'           ==> module_for['pkg'] == None
        #                                ==> module_for['pkg.mod'] == None
        #                                ==> direct_imports['pkg'] == 'pkg.mod'
        #                                ==> direct_imports['pkg.mod'] == 'pkg.mod'
        self.module_for: dict[str, str | None] = {}
        self.direct_imports: dict[str, str] = {}
        self.reverse_alias: dict[str, str] = {}

        # required_names is the set of names that are actually used in a type annotation
        self.required_names: set[str] = set()

        # Names that should be reexported if they come from another module
        self.reexports: set[str] = set()

    def add_import_from(
        self, module: str, names: list[tuple[str, str | None]], require: bool = False
    ) -> None:
        for name, alias in names:
            if alias:
                # 'from {module} import {name} as {alias}'
                self.module_for[alias] = module
                self.reverse_alias[alias] = name
            else:
                # 'from {module} import {name}'
                self.module_for[name] = module
                self.reverse_alias.pop(name, None)
            if require:
                self.require_name(alias or name)
            self.direct_imports.pop(alias or name, None)

    def add_import(self, module: str, alias: str | None = None, require: bool = False) -> None:
        if alias:
            # 'import {module} as {alias}'
            assert "." not in alias  # invalid syntax
            self.module_for[alias] = None
            self.reverse_alias[alias] = module
            if require:
                self.required_names.add(alias)
        else:
            # 'import {module}'
            name = module
            if require:
                self.required_names.add(name)
            # add module and its parent packages
            while name:
                self.module_for[name] = None
                self.direct_imports[name] = module
                self.reverse_alias.pop(name, None)
                name = name.rpartition(".")[0]

    def require_name(self, name: str) -> None:
        while name not in self.direct_imports and "." in name:
            name = name.rsplit(".", 1)[0]
        self.required_names.add(name)

    def reexport(self, name: str) -> None:
        """Mark a given non qualified name as needed in __all__.

        This means that in case it comes from a module, it should be
        imported with an alias even if the alias is the same as the name.
        """
        self.require_name(name)
        self.reexports.add(name)

    def import_lines(self) -> list[str]:
        """The list of required import lines (as strings with python code).

        In order for a module be included in this output, an identifier must be both
        'required' via require_name() and 'imported' via add_import_from()
        or add_import()
        """
        result = []

        # To summarize multiple names imported from a same module, we collect those
        # in the `module_map` dictionary, mapping a module path to the list of names that should
        # be imported from it. the names can also be alias in the form 'original as alias'
        module_map: Mapping[str, list[str]] = defaultdict(list)

        for name in sorted(
            self.required_names,
            key=lambda n: (self.reverse_alias[n], n) if n in self.reverse_alias else (n, ""),
        ):
            # If we haven't seen this name in an import statement, ignore it
            if name not in self.module_for:
                continue

            m = self.module_for[name]
            if m is not None:
                # This name was found in a from ... import ...
                # Collect the name in the module_map
                if name in self.reverse_alias:
                    name = f"{self.reverse_alias[name]} as {name}"
                elif name in self.reexports:
                    name = f"{name} as {name}"
                module_map[m].append(name)
            else:
                # This name was found in an import ...
                # We can already generate the import line
                if name in self.reverse_alias:
                    source = self.reverse_alias[name]
                    result.append(f"import {source} as {name}\n")
                elif name in self.reexports:
                    assert "." not in name  # Because reexports only has nonqualified names
                    result.append(f"import {name} as {name}\n")
                else:
                    result.append(f"import {name}\n")

        # Now generate all the from ... import ... lines collected in module_map
        for module, names in sorted(module_map.items()):
            result.append(f"from {module} import {', '.join(sorted(names))}\n")
        return result


@mypyc_attr(allow_interpreted_subclasses=True)
class BaseStubGenerator:
    # These names should be omitted from generated stubs.
    IGNORED_DUNDERS: Final = {
        "__all__",
        "__author__",
        "__about__",
        "__copyright__",
        "__email__",
        "__license__",
        "__summary__",
        "__title__",
        "__uri__",
        "__str__",
        "__repr__",
        "__getstate__",
        "__setstate__",
        "__slots__",
        "__builtins__",
        "__cached__",
        "__file__",
        "__name__",
        "__package__",
        "__path__",
        "__spec__",
        "__loader__",
    }
    TYPING_MODULE_NAMES: Final = ("typing", "typing_extensions")
    # Special-cased names that are implicitly exported from the stub (from m import y as y).
    EXTRA_EXPORTED: Final = {
        "pyasn1_modules.rfc2437.univ",
        "pyasn1_modules.rfc2459.char",
        "pyasn1_modules.rfc2459.univ",
    }

    def __init__(
        self,
        _all_: list[str] | None = None,
        include_private: bool = False,
        export_less: bool = False,
        include_docstrings: bool = False,
    ) -> None:
        # Best known value of __all__.
        self._all_ = _all_
        self._include_private = include_private
        self._include_docstrings = include_docstrings
        # Disable implicit exports of package-internal imports?
        self.export_less = export_less
        self._import_lines: list[str] = []
        self._output: list[str] = []
        # Current indent level (indent is hardcoded to 4 spaces).
        self._indent = ""
        self._toplevel_names: list[str] = []
        self.import_tracker = ImportTracker()
        # Top-level members
        self.defined_names: set[str] = set()
        self.sig_generators = self.get_sig_generators()
        # populated by visit_mypy_file
        self.module_name: str = ""
        # These are "soft" imports for objects which might appear in annotations but not have
        # a corresponding import statement.
        self.known_imports = {
            "_typeshed": ["Incomplete"],
            "typing": ["Any", "TypeVar", "NamedTuple", "TypedDict"],
            "collections.abc": ["Generator"],
            "typing_extensions": ["ParamSpec", "TypeVarTuple"],
        }

    def get_sig_generators(self) -> list[SignatureGenerator]:
        return []

    def resolve_name(self, name: str) -> str:
        """Return the full name resolving imports and import aliases."""
        if "." not in name:
            real_module = self.import_tracker.module_for.get(name)
            real_short = self.import_tracker.reverse_alias.get(name, name)
            if real_module is None and real_short not in self.defined_names:
                real_module = "builtins"  # not imported and not defined, must be a builtin
        else:
            name_module, real_short = name.split(".", 1)
            real_module = self.import_tracker.reverse_alias.get(name_module, name_module)
        resolved_name = real_short if real_module is None else f"{real_module}.{real_short}"
        return resolved_name

    def add_name(self, fullname: str, require: bool = True) -> str:
        """Add a name to be imported and return the name reference.

        The import will be internal to the stub (i.e don't reexport).
        """
        module, name = fullname.rsplit(".", 1)
        alias = "_" + name if name in self.defined_names else None
        while alias in self.defined_names:
            alias = "_" + alias
        if module != "builtins" or alias:  # don't import from builtins unless needed
            self.import_tracker.add_import_from(module, [(name, alias)], require=require)
        return alias or name

    def add_import_line(self, line: str) -> None:
        """Add a line of text to the import section, unless it's already there."""
        if line not in self._import_lines:
            self._import_lines.append(line)

    def get_imports(self) -> str:
        """Return the import statements for the stub."""
        imports = ""
        if self._import_lines:
            imports += "".join(self._import_lines)
        imports += "".join(self.import_tracker.import_lines())
        return imports

    def output(self) -> str:
        """Return the text for the stub."""
        pieces: list[str] = []
        if imports := self.get_imports():
            pieces.append(imports)
        if dunder_all := self.get_dunder_all():
            pieces.append(dunder_all)
        if self._output:
            pieces.append("".join(self._output))
        return "\n".join(pieces)

    def get_dunder_all(self) -> str:
        """Return the __all__ list for the stub."""
        if self._all_:
            # Note we emit all names in the runtime __all__ here, even if they
            # don't actually exist. If that happens, the runtime has a bug, and
            # it's not obvious what the correct behavior should be. We choose
            # to reflect the runtime __all__ as closely as possible.
            return f"__all__ = {self._all_!r}\n"
        return ""

    def add(self, string: str) -> None:
        """Add text to generated stub."""
        self._output.append(string)

    def is_top_level(self) -> bool:
        """Are we processing the top level of a file?"""
        return self._indent == ""

    def indent(self) -> None:
        """Add one level of indentation."""
        self._indent += "    "

    def dedent(self) -> None:
        """Remove one level of indentation."""
        self._indent = self._indent[:-4]

    def record_name(self, name: str) -> None:
        """Mark a name as defined.

        This only does anything if at the top level of a module.
        """
        if self.is_top_level():
            self._toplevel_names.append(name)

    def is_recorded_name(self, name: str) -> bool:
        """Has this name been recorded previously?"""
        return self.is_top_level() and name in self._toplevel_names

    def set_defined_names(self, defined_names: set[str]) -> None:
        self.defined_names = defined_names
        # Names in __all__ are required
        for name in self._all_ or ():
            self.import_tracker.reexport(name)

        for pkg, imports in self.known_imports.items():
            for t in imports:
                # require=False means that the import won't be added unless require_name() is called
                # for the object during generation.
                self.add_name(f"{pkg}.{t}", require=False)

    def check_undefined_names(self) -> None:
        undefined_names = [name for name in self._all_ or [] if name not in self._toplevel_names]
        if undefined_names:
            if self._output:
                self.add("\n")
            self.add("# Names in __all__ with no definition:\n")
            for name in sorted(undefined_names):
                self.add(f"#   {name}\n")

    def get_signatures(
        self,
        default_signature: FunctionSig,
        sig_generators: list[SignatureGenerator],
        func_ctx: FunctionContext,
    ) -> list[FunctionSig]:
        for sig_gen in sig_generators:
            inferred = sig_gen.get_function_sig(default_signature, func_ctx)
            if inferred:
                return inferred

        return [default_signature]

    def get_property_type(
        self,
        default_type: str | None,
        sig_generators: list[SignatureGenerator],
        func_ctx: FunctionContext,
    ) -> str | None:
        for sig_gen in sig_generators:
            inferred = sig_gen.get_property_type(default_type, func_ctx)
            if inferred:
                return inferred

        return default_type

    def format_func_def(
        self,
        sigs: list[FunctionSig],
        is_coroutine: bool = False,
        decorators: list[str] | None = None,
        docstring: str | None = None,
    ) -> list[str]:
        lines: list[str] = []
        if decorators is None:
            decorators = []

        for signature in sigs:
            # dump decorators, just before "def ..."
            for deco in decorators:
                lines.append(f"{self._indent}{deco}")

            lines.append(
                signature.format_sig(
                    indent=self._indent,
                    is_async=is_coroutine,
                    docstring=docstring if self._include_docstrings else None,
                )
            )
        return lines

    def format_type_args(self, o: TypeAliasStmt | FuncDef | ClassDef) -> str:
        if not o.type_args:
            return ""
        p = AnnotationPrinter(self)
        type_args_list: list[str] = []
        for type_arg in o.type_args:
            if type_arg.kind == PARAM_SPEC_KIND:
                prefix = "**"
            elif type_arg.kind == TYPE_VAR_TUPLE_KIND:
                prefix = "*"
            else:
                prefix = ""
            if type_arg.upper_bound:
                bound_or_values = f": {type_arg.upper_bound.accept(p)}"
            elif type_arg.values:
                bound_or_values = f": ({', '.join(v.accept(p) for v in type_arg.values)})"
            else:
                bound_or_values = ""
            if type_arg.default:
                default = f" = {type_arg.default.accept(p)}"
            else:
                default = ""
            type_args_list.append(f"{prefix}{type_arg.name}{bound_or_values}{default}")
        return "[" + ", ".join(type_args_list) + "]"

    def print_annotation(
        self,
        t: Type,
        known_modules: list[str] | None = None,
        local_modules: list[str] | None = None,
    ) -> str:
        printer = AnnotationPrinter(self, known_modules, local_modules)
        return t.accept(printer)

    def is_not_in_all(self, name: str) -> bool:
        if self.is_private_name(name):
            return False
        if self._all_:
            return self.is_top_level() and name not in self._all_
        return False

    def is_private_name(self, name: str, fullname: str | None = None) -> bool:
        if "__mypy-" in name:
            return True  # Never include mypy generated symbols
        if self._include_private:
            return False
        if fullname in self.EXTRA_EXPORTED:
            return False
        if name == "_":
            return False
        if not name.startswith("_"):
            return False
        if self._all_ and name in self._all_:
            return False
        if name.startswith("__") and name.endswith("__"):
            return name in self.IGNORED_DUNDERS
        return True

    def should_reexport(self, name: str, full_module: str, name_is_alias: bool) -> bool:
        if (
            not name_is_alias
            and self.module_name
            and (self.module_name + "." + name) in self.EXTRA_EXPORTED
        ):
            # Special case certain names that should be exported, against our general rules.
            return True
        if name_is_alias:
            return False
        if self.export_less:
            return False
        if not self.module_name:
            return False
        is_private = self.is_private_name(name, full_module + "." + name)
        if is_private:
            return False
        top_level = full_module.split(".")[0]
        self_top_level = self.module_name.split(".", 1)[0]
        if top_level not in (self_top_level, "_" + self_top_level):
            # Export imports from the same package, since we can't reliably tell whether they
            # are part of the public API.
            return False
        if self._all_:
            return name in self._all_
        return True