mypy-dev 1.9.0.dev0__py3-none-any.whl

mypy/plugins/common.py

@@ -0,0 +1,440 @@
+from __future__ import annotations
+
+from typing import NamedTuple
+
+from mypy.argmap import map_actuals_to_formals
+from mypy.fixup import TypeFixer
+from mypy.nodes import (
+    ARG_POS,
+    MDEF,
+    SYMBOL_FUNCBASE_TYPES,
+    Argument,
+    Block,
+    CallExpr,
+    ClassDef,
+    Decorator,
+    Expression,
+    FuncDef,
+    JsonDict,
+    NameExpr,
+    Node,
+    OverloadedFuncDef,
+    PassStmt,
+    RefExpr,
+    SymbolTableNode,
+    TypeInfo,
+    Var,
+)
+from mypy.plugin import CheckerPluginInterface, ClassDefContext, SemanticAnalyzerPluginInterface
+from mypy.semanal_shared import (
+    ALLOW_INCOMPATIBLE_OVERRIDE,
+    parse_bool,
+    require_bool_literal_argument,
+    set_callable_name,
+)
+from mypy.typeops import try_getting_str_literals as try_getting_str_literals
+from mypy.types import (
+    AnyType,
+    CallableType,
+    Instance,
+    LiteralType,
+    NoneType,
+    Overloaded,
+    Type,
+    TypeOfAny,
+    TypeType,
+    TypeVarType,
+    deserialize_type,
+    get_proper_type,
+)
+from mypy.types_utils import is_overlapping_none
+from mypy.typevars import fill_typevars
+from mypy.util import get_unique_redefinition_name
+
+
+def _get_decorator_bool_argument(ctx: ClassDefContext, name: str, default: bool) -> bool:
+    """Return the bool argument for the decorator.
+
+    This handles both @decorator(...) and @decorator.
+    """
+    if isinstance(ctx.reason, CallExpr):
+        return _get_bool_argument(ctx, ctx.reason, name, default)
+    else:
+        return default
+
+
+def _get_bool_argument(ctx: ClassDefContext, expr: CallExpr, name: str, default: bool) -> bool:
+    """Return the boolean value for an argument to a call or the
+    default if it's not found.
+    """
+    attr_value = _get_argument(expr, name)
+    if attr_value:
+        return require_bool_literal_argument(ctx.api, attr_value, name, default)
+    return default
+
+
+def _get_argument(call: CallExpr, name: str) -> Expression | None:
+    """Return the expression for the specific argument."""
+    # To do this we use the CallableType of the callee to find the FormalArgument,
+    # then walk the actual CallExpr looking for the appropriate argument.
+    #
+    # Note: I'm not hard-coding the index so that in the future we can support other
+    # attrib and class makers.
+    callee_type = _get_callee_type(call)
+    if not callee_type:
+        return None
+
+    argument = callee_type.argument_by_name(name)
+    if not argument:
+        return None
+    assert argument.name
+
+    for i, (attr_name, attr_value) in enumerate(zip(call.arg_names, call.args)):
+        if argument.pos is not None and not attr_name and i == argument.pos:
+            return attr_value
+        if attr_name == argument.name:
+            return attr_value
+
+    return None
+
+
+def find_shallow_matching_overload_item(overload: Overloaded, call: CallExpr) -> CallableType:
+    """Perform limited lookup of a matching overload item.
+
+    Full overload resolution is only supported during type checking, but plugins
+    sometimes need to resolve overloads. This can be used in some such use cases.
+
+    Resolve overloads based on these things only:
+
+    * Match using argument kinds and names
+    * If formal argument has type None, only accept the "None" expression in the callee
+    * If formal argument has type Literal[True] or Literal[False], only accept the
+      relevant bool literal
+
+    Return the first matching overload item, or the last one if nothing matches.
+    """
+    for item in overload.items[:-1]:
+        ok = True
+        mapped = map_actuals_to_formals(
+            call.arg_kinds,
+            call.arg_names,
+            item.arg_kinds,
+            item.arg_names,
+            lambda i: AnyType(TypeOfAny.special_form),
+        )
+
+        # Look for extra actuals
+        matched_actuals = set()
+        for actuals in mapped:
+            matched_actuals.update(actuals)
+        if any(i not in matched_actuals for i in range(len(call.args))):
+            ok = False
+
+        for arg_type, kind, actuals in zip(item.arg_types, item.arg_kinds, mapped):
+            if kind.is_required() and not actuals:
+                # Missing required argument
+                ok = False
+                break
+            elif actuals:
+                args = [call.args[i] for i in actuals]
+                arg_type = get_proper_type(arg_type)
+                arg_none = any(isinstance(arg, NameExpr) and arg.name == "None" for arg in args)
+                if isinstance(arg_type, NoneType):
+                    if not arg_none:
+                        ok = False
+                        break
+                elif (
+                    arg_none
+                    and not is_overlapping_none(arg_type)
+                    and not (
+                        isinstance(arg_type, Instance)
+                        and arg_type.type.fullname == "builtins.object"
+                    )
+                    and not isinstance(arg_type, AnyType)
+                ):
+                    ok = False
+                    break
+                elif isinstance(arg_type, LiteralType) and isinstance(arg_type.value, bool):
+                    if not any(parse_bool(arg) == arg_type.value for arg in args):
+                        ok = False
+                        break
+        if ok:
+            return item
+    return overload.items[-1]
+
+
+def _get_callee_type(call: CallExpr) -> CallableType | None:
+    """Return the type of the callee, regardless of its syntatic form."""
+
+    callee_node: Node | None = call.callee
+
+    if isinstance(callee_node, RefExpr):
+        callee_node = callee_node.node
+
+    # Some decorators may be using typing.dataclass_transform, which is itself a decorator, so we
+    # need to unwrap them to get at the true callee
+    if isinstance(callee_node, Decorator):
+        callee_node = callee_node.func
+
+    if isinstance(callee_node, (Var, SYMBOL_FUNCBASE_TYPES)) and callee_node.type:
+        callee_node_type = get_proper_type(callee_node.type)
+        if isinstance(callee_node_type, Overloaded):
+            return find_shallow_matching_overload_item(callee_node_type, call)
+        elif isinstance(callee_node_type, CallableType):
+            return callee_node_type
+
+    return None
+
+
+def add_method(
+    ctx: ClassDefContext,
+    name: str,
+    args: list[Argument],
+    return_type: Type,
+    self_type: Type | None = None,
+    tvar_def: TypeVarType | None = None,
+    is_classmethod: bool = False,
+    is_staticmethod: bool = False,
+) -> None:
+    """
+    Adds a new method to a class.
+    Deprecated, use add_method_to_class() instead.
+    """
+    add_method_to_class(
+        ctx.api,
+        ctx.cls,
+        name=name,
+        args=args,
+        return_type=return_type,
+        self_type=self_type,
+        tvar_def=tvar_def,
+        is_classmethod=is_classmethod,
+        is_staticmethod=is_staticmethod,
+    )
+
+
+class MethodSpec(NamedTuple):
+    """Represents a method signature to be added, except for `name`."""
+
+    args: list[Argument]
+    return_type: Type
+    self_type: Type | None = None
+    tvar_defs: list[TypeVarType] | None = None
+
+
+def add_method_to_class(
+    api: SemanticAnalyzerPluginInterface | CheckerPluginInterface,
+    cls: ClassDef,
+    name: str,
+    # MethodSpec items kept for backward compatibility:
+    args: list[Argument],
+    return_type: Type,
+    self_type: Type | None = None,
+    tvar_def: list[TypeVarType] | TypeVarType | None = None,
+    is_classmethod: bool = False,
+    is_staticmethod: bool = False,
+) -> FuncDef | Decorator:
+    """Adds a new method to a class definition."""
+    _prepare_class_namespace(cls, name)
+
+    if tvar_def is not None and not isinstance(tvar_def, list):
+        tvar_def = [tvar_def]
+
+    func, sym = _add_method_by_spec(
+        api,
+        cls.info,
+        name,
+        MethodSpec(args=args, return_type=return_type, self_type=self_type, tvar_defs=tvar_def),
+        is_classmethod=is_classmethod,
+        is_staticmethod=is_staticmethod,
+    )
+    cls.info.names[name] = sym
+    cls.info.defn.defs.body.append(func)
+    return func
+
+
+def add_overloaded_method_to_class(
+    api: SemanticAnalyzerPluginInterface | CheckerPluginInterface,
+    cls: ClassDef,
+    name: str,
+    items: list[MethodSpec],
+    is_classmethod: bool = False,
+    is_staticmethod: bool = False,
+) -> OverloadedFuncDef:
+    """Adds a new overloaded method to a class definition."""
+    assert len(items) >= 2, "Overloads must contain at least two cases"
+
+    # Save old definition, if it exists.
+    _prepare_class_namespace(cls, name)
+
+    # Create function bodies for each passed method spec.
+    funcs: list[Decorator | FuncDef] = []
+    for item in items:
+        func, _sym = _add_method_by_spec(
+            api,
+            cls.info,
+            name=name,
+            spec=item,
+            is_classmethod=is_classmethod,
+            is_staticmethod=is_staticmethod,
+        )
+        if isinstance(func, FuncDef):
+            var = Var(func.name, func.type)
+            var.set_line(func.line)
+            func.is_decorated = True
+            func.deco_line = func.line
+
+            deco = Decorator(func, [], var)
+        else:
+            deco = func
+        deco.is_overload = True
+        funcs.append(deco)
+
+    # Create the final OverloadedFuncDef node:
+    overload_def = OverloadedFuncDef(funcs)
+    overload_def.info = cls.info
+    overload_def.is_class = is_classmethod
+    overload_def.is_static = is_staticmethod
+    sym = SymbolTableNode(MDEF, overload_def)
+    sym.plugin_generated = True
+
+    cls.info.names[name] = sym
+    cls.info.defn.defs.body.append(overload_def)
+    return overload_def
+
+
+def _prepare_class_namespace(cls: ClassDef, name: str) -> None:
+    info = cls.info
+    assert info
+
+    # First remove any previously generated methods with the same name
+    # to avoid clashes and problems in the semantic analyzer.
+    if name in info.names:
+        sym = info.names[name]
+        if sym.plugin_generated and isinstance(sym.node, FuncDef):
+            cls.defs.body.remove(sym.node)
+
+    # NOTE: we would like the plugin generated node to dominate, but we still
+    # need to keep any existing definitions so they get semantically analyzed.
+    if name in info.names:
+        # Get a nice unique name instead.
+        r_name = get_unique_redefinition_name(name, info.names)
+        info.names[r_name] = info.names[name]
+
+
+def _add_method_by_spec(
+    api: SemanticAnalyzerPluginInterface | CheckerPluginInterface,
+    info: TypeInfo,
+    name: str,
+    spec: MethodSpec,
+    *,
+    is_classmethod: bool,
+    is_staticmethod: bool,
+) -> tuple[FuncDef | Decorator, SymbolTableNode]:
+    args, return_type, self_type, tvar_defs = spec
+
+    assert not (
+        is_classmethod is True and is_staticmethod is True
+    ), "Can't add a new method that's both staticmethod and classmethod."
+
+    if isinstance(api, SemanticAnalyzerPluginInterface):
+        function_type = api.named_type("builtins.function")
+    else:
+        function_type = api.named_generic_type("builtins.function", [])
+
+    if is_classmethod:
+        self_type = self_type or TypeType(fill_typevars(info))
+        first = [Argument(Var("_cls"), self_type, None, ARG_POS, True)]
+    elif is_staticmethod:
+        first = []
+    else:
+        self_type = self_type or fill_typevars(info)
+        first = [Argument(Var("self"), self_type, None, ARG_POS)]
+    args = first + args
+
+    arg_types, arg_names, arg_kinds = [], [], []
+    for arg in args:
+        assert arg.type_annotation, "All arguments must be fully typed."
+        arg_types.append(arg.type_annotation)
+        arg_names.append(arg.variable.name)
+        arg_kinds.append(arg.kind)
+
+    signature = CallableType(arg_types, arg_kinds, arg_names, return_type, function_type)
+    if tvar_defs:
+        signature.variables = tvar_defs
+
+    func = FuncDef(name, args, Block([PassStmt()]))
+    func.info = info
+    func.type = set_callable_name(signature, func)
+    func.is_class = is_classmethod
+    func.is_static = is_staticmethod
+    func._fullname = info.fullname + "." + name
+    func.line = info.line
+
+    # Add decorator for is_staticmethod. It's unnecessary for is_classmethod.
+    if is_staticmethod:
+        func.is_decorated = True
+        v = Var(name, func.type)
+        v.info = info
+        v._fullname = func._fullname
+        v.is_staticmethod = True
+        dec = Decorator(func, [], v)
+        dec.line = info.line
+        sym = SymbolTableNode(MDEF, dec)
+        sym.plugin_generated = True
+        return dec, sym
+
+    sym = SymbolTableNode(MDEF, func)
+    sym.plugin_generated = True
+    return func, sym
+
+
+def add_attribute_to_class(
+    api: SemanticAnalyzerPluginInterface,
+    cls: ClassDef,
+    name: str,
+    typ: Type,
+    final: bool = False,
+    no_serialize: bool = False,
+    override_allow_incompatible: bool = False,
+    fullname: str | None = None,
+    is_classvar: bool = False,
+    overwrite_existing: bool = False,
+) -> Var:
+    """
+    Adds a new attribute to a class definition.
+    This currently only generates the symbol table entry and no corresponding AssignmentStatement
+    """
+    info = cls.info
+
+    # NOTE: we would like the plugin generated node to dominate, but we still
+    # need to keep any existing definitions so they get semantically analyzed.
+    if name in info.names and not overwrite_existing:
+        # Get a nice unique name instead.
+        r_name = get_unique_redefinition_name(name, info.names)
+        info.names[r_name] = info.names[name]
+
+    node = Var(name, typ)
+    node.info = info
+    node.is_final = final
+    node.is_classvar = is_classvar
+    if name in ALLOW_INCOMPATIBLE_OVERRIDE:
+        node.allow_incompatible_override = True
+    else:
+        node.allow_incompatible_override = override_allow_incompatible
+
+    if fullname:
+        node._fullname = fullname
+    else:
+        node._fullname = info.fullname + "." + name
+
+    info.names[name] = SymbolTableNode(
+        MDEF, node, plugin_generated=True, no_serialize=no_serialize
+    )
+    return node
+
+
+def deserialize_and_fixup_type(data: str | JsonDict, api: SemanticAnalyzerPluginInterface) -> Type:
+    typ = deserialize_type(data)
+    typ.accept(TypeFixer(api.modules, allow_missing=False))
+    return typ

mypy/plugins/ctypes.py

@@ -0,0 +1,245 @@
+"""Plugin to provide accurate types for some parts of the ctypes module."""
+
+from __future__ import annotations
+
+# Fully qualified instead of "from mypy.plugin import ..." to avoid circular import problems.
+import mypy.plugin
+from mypy import nodes
+from mypy.maptype import map_instance_to_supertype
+from mypy.messages import format_type
+from mypy.subtypes import is_subtype
+from mypy.typeops import make_simplified_union
+from mypy.types import (
+    AnyType,
+    CallableType,
+    Instance,
+    NoneType,
+    ProperType,
+    Type,
+    TypeOfAny,
+    UnionType,
+    flatten_nested_unions,
+    get_proper_type,
+)
+
+
+def _find_simplecdata_base_arg(
+    tp: Instance, api: mypy.plugin.CheckerPluginInterface
+) -> ProperType | None:
+    """Try to find a parametrized _SimpleCData in tp's bases and return its single type argument.
+
+    None is returned if _SimpleCData appears nowhere in tp's (direct or indirect) bases.
+    """
+    if tp.type.has_base("_ctypes._SimpleCData"):
+        simplecdata_base = map_instance_to_supertype(
+            tp,
+            api.named_generic_type("_ctypes._SimpleCData", [AnyType(TypeOfAny.special_form)]).type,
+        )
+        assert len(simplecdata_base.args) == 1, "_SimpleCData takes exactly one type argument"
+        return get_proper_type(simplecdata_base.args[0])
+    return None
+
+
+def _autoconvertible_to_cdata(tp: Type, api: mypy.plugin.CheckerPluginInterface) -> Type:
+    """Get a type that is compatible with all types that can be implicitly converted to the given
+    CData type.
+
+    Examples:
+    * c_int -> Union[c_int, int]
+    * c_char_p -> Union[c_char_p, bytes, int, NoneType]
+    * MyStructure -> MyStructure
+    """
+    allowed_types = []
+    # If tp is a union, we allow all types that are convertible to at least one of the union
+    # items. This is not quite correct - strictly speaking, only types convertible to *all* of the
+    # union items should be allowed. This may be worth changing in the future, but the more
+    # correct algorithm could be too strict to be useful.
+    for t in flatten_nested_unions([tp]):
+        t = get_proper_type(t)
+        # Every type can be converted from itself (obviously).
+        allowed_types.append(t)
+        if isinstance(t, Instance):
+            unboxed = _find_simplecdata_base_arg(t, api)
+            if unboxed is not None:
+                # If _SimpleCData appears in tp's (direct or indirect) bases, its type argument
+                # specifies the type's "unboxed" version, which can always be converted back to
+                # the original "boxed" type.
+                allowed_types.append(unboxed)
+
+                if t.type.has_base("ctypes._PointerLike"):
+                    # Pointer-like _SimpleCData subclasses can also be converted from
+                    # an int or None.
+                    allowed_types.append(api.named_generic_type("builtins.int", []))
+                    allowed_types.append(NoneType())
+
+    return make_simplified_union(allowed_types)
+
+
+def _autounboxed_cdata(tp: Type) -> ProperType:
+    """Get the auto-unboxed version of a CData type, if applicable.
+
+    For *direct* _SimpleCData subclasses, the only type argument of _SimpleCData in the bases list
+    is returned.
+    For all other CData types, including indirect _SimpleCData subclasses, tp is returned as-is.
+    """
+    tp = get_proper_type(tp)
+
+    if isinstance(tp, UnionType):
+        return make_simplified_union([_autounboxed_cdata(t) for t in tp.items])
+    elif isinstance(tp, Instance):
+        for base in tp.type.bases:
+            if base.type.fullname == "_ctypes._SimpleCData":
+                # If tp has _SimpleCData as a direct base class,
+                # the auto-unboxed type is the single type argument of the _SimpleCData type.
+                assert len(base.args) == 1
+                return get_proper_type(base.args[0])
+    # If tp is not a concrete type, or if there is no _SimpleCData in the bases,
+    # the type is not auto-unboxed.
+    return tp
+
+
+def _get_array_element_type(tp: Type) -> ProperType | None:
+    """Get the element type of the Array type tp, or None if not specified."""
+    tp = get_proper_type(tp)
+    if isinstance(tp, Instance):
+        assert tp.type.fullname == "_ctypes.Array"
+        if len(tp.args) == 1:
+            return get_proper_type(tp.args[0])
+    return None
+
+
+def array_constructor_callback(ctx: mypy.plugin.FunctionContext) -> Type:
+    """Callback to provide an accurate signature for the ctypes.Array constructor."""
+    # Extract the element type from the constructor's return type, i. e. the type of the array
+    # being constructed.
+    et = _get_array_element_type(ctx.default_return_type)
+    if et is not None:
+        allowed = _autoconvertible_to_cdata(et, ctx.api)
+        assert (
+            len(ctx.arg_types) == 1
+        ), "The stub of the ctypes.Array constructor should have a single vararg parameter"
+        for arg_num, (arg_kind, arg_type) in enumerate(zip(ctx.arg_kinds[0], ctx.arg_types[0]), 1):
+            if arg_kind == nodes.ARG_POS and not is_subtype(arg_type, allowed):
+                ctx.api.msg.fail(
+                    "Array constructor argument {} of type {}"
+                    " is not convertible to the array element type {}".format(
+                        arg_num,
+                        format_type(arg_type, ctx.api.options),
+                        format_type(et, ctx.api.options),
+                    ),
+                    ctx.context,
+                )
+            elif arg_kind == nodes.ARG_STAR:
+                ty = ctx.api.named_generic_type("typing.Iterable", [allowed])
+                if not is_subtype(arg_type, ty):
+                    it = ctx.api.named_generic_type("typing.Iterable", [et])
+                    ctx.api.msg.fail(
+                        "Array constructor argument {} of type {}"
+                        " is not convertible to the array element type {}".format(
+                            arg_num,
+                            format_type(arg_type, ctx.api.options),
+                            format_type(it, ctx.api.options),
+                        ),
+                        ctx.context,
+                    )
+
+    return ctx.default_return_type
+
+
+def array_getitem_callback(ctx: mypy.plugin.MethodContext) -> Type:
+    """Callback to provide an accurate return type for ctypes.Array.__getitem__."""
+    et = _get_array_element_type(ctx.type)
+    if et is not None:
+        unboxed = _autounboxed_cdata(et)
+        assert (
+            len(ctx.arg_types) == 1
+        ), "The stub of ctypes.Array.__getitem__ should have exactly one parameter"
+        assert (
+            len(ctx.arg_types[0]) == 1
+        ), "ctypes.Array.__getitem__'s parameter should not be variadic"
+        index_type = get_proper_type(ctx.arg_types[0][0])
+        if isinstance(index_type, Instance):
+            if index_type.type.has_base("builtins.int"):
+                return unboxed
+            elif index_type.type.has_base("builtins.slice"):
+                return ctx.api.named_generic_type("builtins.list", [unboxed])
+    return ctx.default_return_type
+
+
+def array_setitem_callback(ctx: mypy.plugin.MethodSigContext) -> CallableType:
+    """Callback to provide an accurate signature for ctypes.Array.__setitem__."""
+    et = _get_array_element_type(ctx.type)
+    if et is not None:
+        allowed = _autoconvertible_to_cdata(et, ctx.api)
+        assert len(ctx.default_signature.arg_types) == 2
+        index_type = get_proper_type(ctx.default_signature.arg_types[0])
+        if isinstance(index_type, Instance):
+            arg_type = None
+            if index_type.type.has_base("builtins.int"):
+                arg_type = allowed
+            elif index_type.type.has_base("builtins.slice"):
+                arg_type = ctx.api.named_generic_type("builtins.list", [allowed])
+            if arg_type is not None:
+                # Note: arg_type can only be None if index_type is invalid, in which case we use
+                # the default signature and let mypy report an error about it.
+                return ctx.default_signature.copy_modified(
+                    arg_types=ctx.default_signature.arg_types[:1] + [arg_type]
+                )
+    return ctx.default_signature
+
+
+def array_iter_callback(ctx: mypy.plugin.MethodContext) -> Type:
+    """Callback to provide an accurate return type for ctypes.Array.__iter__."""
+    et = _get_array_element_type(ctx.type)
+    if et is not None:
+        unboxed = _autounboxed_cdata(et)
+        return ctx.api.named_generic_type("typing.Iterator", [unboxed])
+    return ctx.default_return_type
+
+
+def array_value_callback(ctx: mypy.plugin.AttributeContext) -> Type:
+    """Callback to provide an accurate type for ctypes.Array.value."""
+    et = _get_array_element_type(ctx.type)
+    if et is not None:
+        types: list[Type] = []
+        for tp in flatten_nested_unions([et]):
+            tp = get_proper_type(tp)
+            if isinstance(tp, AnyType):
+                types.append(AnyType(TypeOfAny.from_another_any, source_any=tp))
+            elif isinstance(tp, Instance) and tp.type.fullname == "ctypes.c_char":
+                types.append(ctx.api.named_generic_type("builtins.bytes", []))
+            elif isinstance(tp, Instance) and tp.type.fullname == "ctypes.c_wchar":
+                types.append(ctx.api.named_generic_type("builtins.str", []))
+            else:
+                ctx.api.msg.fail(
+                    'Array attribute "value" is only available'
+                    ' with element type "c_char" or "c_wchar", not {}'.format(
+                        format_type(et, ctx.api.options)
+                    ),
+                    ctx.context,
+                )
+        return make_simplified_union(types)
+    return ctx.default_attr_type
+
+
+def array_raw_callback(ctx: mypy.plugin.AttributeContext) -> Type:
+    """Callback to provide an accurate type for ctypes.Array.raw."""
+    et = _get_array_element_type(ctx.type)
+    if et is not None:
+        types: list[Type] = []
+        for tp in flatten_nested_unions([et]):
+            tp = get_proper_type(tp)
+            if (
+                isinstance(tp, AnyType)
+                or isinstance(tp, Instance)
+                and tp.type.fullname == "ctypes.c_char"
+            ):
+                types.append(ctx.api.named_generic_type("builtins.bytes", []))
+            else:
+                ctx.api.msg.fail(
+                    'Array attribute "raw" is only available'
+                    ' with element type "c_char", not {}'.format(format_type(et, ctx.api.options)),
+                    ctx.context,
+                )
+        return make_simplified_union(types)
+    return ctx.default_attr_type