"""Semantic analysis of types"""

from __future__ import annotations

import itertools

from collections.abc import Callable, Iterable, Iterator, Sequence

from contextlib import contextmanager

from typing import Final, Protocol, TypeVar

from mypy import errorcodes as codes, message_registry, nodes

from mypy.errorcodes import ErrorCode

from mypy.errors import ErrorInfo

from mypy.expandtype import expand_type

from mypy.message_registry import (

INVALID_PARAM_SPEC_LOCATION,

INVALID_PARAM_SPEC_LOCATION_NOTE,

TYPEDDICT_OVERRIDE_MERGE,

)

from mypy.messages import (

MessageBuilder,

format_type,

format_type_bare,

quote_type_string,

wrong_type_arg_count,

)

from mypy.nodes import (

ARG_NAMED,

ARG_NAMED_OPT,

ARG_OPT,

ARG_POS,

ARG_STAR,

ARG_STAR2,

MISSING_FALLBACK,

SYMBOL_FUNCBASE_TYPES,

ArgKind,

Context,

Decorator,

ImportFrom,

MypyFile,

ParamSpecExpr,

PlaceholderNode,

SymbolTableNode,

TypeAlias,

TypeInfo,

TypeVarExpr,

TypeVarLikeExpr,

TypeVarTupleExpr,

Var,

check_arg_kinds,

check_arg_names,

)

from mypy.options import INLINE_TYPEDDICT, TYPE_FORM, Options

from mypy.plugin import AnalyzeTypeContext, Plugin, TypeAnalyzerPluginInterface

from mypy.semanal_shared import (

SemanticAnalyzerCoreInterface,

SemanticAnalyzerInterface,

paramspec_args,

paramspec_kwargs,

)

from mypy.state import state

from mypy.tvar_scope import TypeVarLikeScope

from mypy.types import (

ANNOTATED_TYPE_NAMES,

ANY_STRATEGY,

CONCATENATE_TYPE_NAMES,

FINAL_TYPE_NAMES,

LITERAL_TYPE_NAMES,

NEVER_NAMES,

TUPLE_NAMES,

TYPE_ALIAS_NAMES,

TYPE_NAMES,

UNPACK_TYPE_NAMES,

AnyType,

BoolTypeQuery,

CallableArgument,

CallableType,

DeletedType,

EllipsisType,

ErasedType,

Instance,

LiteralType,

NoneType,

Overloaded,

Parameters,

ParamSpecFlavor,

ParamSpecType,

PartialType,

PlaceholderType,

ProperType,

RawExpressionType,

ReadOnlyType,

RequiredType,

SyntheticTypeVisitor,

TrivialSyntheticTypeTranslator,

TupleType,

Type,

TypeAliasType,

TypedDictType,

TypeList,

TypeOfAny,

TypeQuery,

TypeType,

TypeVarId,

TypeVarLikeType,

TypeVarTupleType,

TypeVarType,

UnboundType,

UninhabitedType,

UnionType,

UnpackType,

callable_with_ellipsis,

find_unpack_in_list,

flatten_nested_tuples,

get_proper_type,

has_type_vars,

)

from mypy.types_utils import get_bad_type_type_item

from mypy.typevars import fill_typevars

T = TypeVar("T")

type_constructors: Final = {

"typing.Callable",

"typing.Optional",

"typing.Tuple",

"typing.Type",

"typing.Union",

*LITERAL_TYPE_NAMES,

*ANNOTATED_TYPE_NAMES,

}

ARG_KINDS_BY_CONSTRUCTOR: Final = {

"mypy_extensions.Arg": ARG_POS,

"mypy_extensions.DefaultArg": ARG_OPT,

"mypy_extensions.NamedArg": ARG_NAMED,

"mypy_extensions.DefaultNamedArg": ARG_NAMED_OPT,

"mypy_extensions.VarArg": ARG_STAR,

"mypy_extensions.KwArg": ARG_STAR2,

}

SELF_TYPE_NAMES: Final = {"typing.Self", "typing_extensions.Self"}

def analyze_type_alias(

type: Type,

api: SemanticAnalyzerCoreInterface,

tvar_scope: TypeVarLikeScope,

plugin: Plugin,

options: Options,

cur_mod_node: MypyFile,

is_typeshed_stub: bool,

allow_placeholder: bool = False,

in_dynamic_func: bool = False,

global_scope: bool = True,

allowed_alias_tvars: list[TypeVarLikeType] | None = None,

alias_type_params_names: list[str] | None = None,

python_3_12_type_alias: bool = False,

) -> tuple[Type, set[str]]:

"""Analyze r.h.s. of a (potential) type alias definition.

If `node` is valid as a type alias rvalue, return the resulting type and a set of

full names of type aliases it depends on (directly or indirectly).

'node' must have been semantically analyzed.

"""

analyzer = TypeAnalyser(

api,

tvar_scope,

plugin,

options,

cur_mod_node,

is_typeshed_stub,

defining_alias=True,

allow_placeholder=allow_placeholder,

prohibit_self_type="type alias target",

allowed_alias_tvars=allowed_alias_tvars,

alias_type_params_names=alias_type_params_names,

python_3_12_type_alias=python_3_12_type_alias,

)

analyzer.in_dynamic_func = in_dynamic_func

analyzer.global_scope = global_scope

res = analyzer.anal_type(type, nested=False)

return res, analyzer.aliases_used

class TypeAnalyser(SyntheticTypeVisitor[Type], TypeAnalyzerPluginInterface):

"""Semantic analyzer for types.

Converts unbound types into bound types. This is a no-op for already

bound types.

If an incomplete reference is encountered, this does a defer. The

caller never needs to defer.

"""

# Is this called from an untyped function definition?

in_dynamic_func: bool = False

# Is this called from global scope?

global_scope: bool = True

def __init__(

self,

api: SemanticAnalyzerCoreInterface,

tvar_scope: TypeVarLikeScope,

plugin: Plugin,

options: Options,

cur_mod_node: MypyFile,

is_typeshed_stub: bool,

*,

defining_alias: bool = False,

python_3_12_type_alias: bool = False,

allow_tuple_literal: bool = False,

allow_unbound_tvars: bool = False,

allow_placeholder: bool = False,

allow_typed_dict_special_forms: bool = False,

allow_final: bool = True,

allow_param_spec_literals: bool = False,

allow_unpack: bool = False,

report_invalid_types: bool = True,

prohibit_self_type: str | None = None,

prohibit_special_class_field_types: str | None = None,

allowed_alias_tvars: list[TypeVarLikeType] | None = None,

allow_type_any: bool = False,

alias_type_params_names: list[str] | None = None,

) -> None:

self.api = api

self.fail_func = api.fail

self.note_func = api.note

self.tvar_scope = tvar_scope

# Are we analysing a type alias definition rvalue?

self.defining_alias = defining_alias

self.python_3_12_type_alias = python_3_12_type_alias

self.allow_tuple_literal = allow_tuple_literal

# Positive if we are analyzing arguments of another (outer) type

self.nesting_level = 0

# Should we allow new type syntax when targeting older Python versions

# like 'list[int]' or 'X | Y' (allowed in stubs and with `__future__` import)?

self.always_allow_new_syntax = self.api.is_stub_file or self.api.is_future_flag_set(

"annotations"

)

# Should we accept unbound type variables? This is currently used for class bases,

# and alias right hand sides (before they are analyzed as type aliases).

self.allow_unbound_tvars = allow_unbound_tvars

if allowed_alias_tvars is None:

allowed_alias_tvars = []

self.allowed_alias_tvars = allowed_alias_tvars

self.alias_type_params_names = alias_type_params_names

# If false, record incomplete ref if we generate PlaceholderType.

self.allow_placeholder = allow_placeholder

# Are we in a context where Required[] is allowed?

self.allow_typed_dict_special_forms = allow_typed_dict_special_forms

# Set True when we analyze ClassVar else False

self.allow_final = allow_final

# Are we in a context where ParamSpec literals are allowed?

self.allow_param_spec_literals = allow_param_spec_literals

# Are we in context where literal "..." specifically is allowed?

self.allow_ellipsis = False

# Should we report an error whenever we encounter a RawExpressionType outside

# of a Literal context: e.g. whenever we encounter an invalid type? Normally,

# we want to report an error, but the caller may want to do more specialized

# error handling.

self.report_invalid_types = report_invalid_types

self.plugin = plugin

self.options = options

self.cur_mod_node = cur_mod_node

self.is_typeshed_stub = is_typeshed_stub

# Names of type aliases encountered while analysing a type will be collected here.

self.aliases_used: set[str] = set()

self.prohibit_self_type = prohibit_self_type

# Set when we analyze TypedDicts or NamedTuples, since they are special:

self.prohibit_special_class_field_types = prohibit_special_class_field_types

# Allow variables typed as Type[Any] and type (useful for base classes).

self.allow_type_any = allow_type_any

self.allow_type_var_tuple = False

self.allow_unpack = allow_unpack

def lookup_qualified(

self, name: str, ctx: Context, suppress_errors: bool = False

) -> SymbolTableNode | None:

return self.api.lookup_qualified(name, ctx, suppress_errors)

def lookup_fully_qualified(self, fullname: str) -> SymbolTableNode:

return self.api.lookup_fully_qualified(fullname)

def visit_unbound_type(self, t: UnboundType, defining_literal: bool = False) -> Type:

typ = self.visit_unbound_type_nonoptional(t, defining_literal)

if t.optional:

# We don't need to worry about double-wrapping Optionals or

# wrapping Anys: Union simplification will take care of that.

return make_optional_type(typ)

return typ

def not_declared_in_type_params(self, tvar_name: str) -> bool:

return (

self.alias_type_params_names is not None

and tvar_name not in self.alias_type_params_names

)

def visit_unbound_type_nonoptional(self, t: UnboundType, defining_literal: bool) -> Type:

sym = self.lookup_qualified(t.name, t)

param_spec_name = None

if t.name.endswith((".args", ".kwargs")):

param_spec_name = t.name.rsplit(".", 1)[0]

maybe_param_spec = self.lookup_qualified(param_spec_name, t)

if maybe_param_spec and isinstance(maybe_param_spec.node, ParamSpecExpr):

sym = maybe_param_spec

else:

param_spec_name = None

if sym is not None:

node = sym.node

if isinstance(node, PlaceholderNode):

if node.becomes_typeinfo:

# Reference to placeholder type.

if self.api.final_iteration:

self.cannot_resolve_type(t)

return AnyType(TypeOfAny.from_error)

elif self.allow_placeholder:

self.api.defer()

else:

self.api.record_incomplete_ref()

# Always allow ParamSpec for placeholders, if they are actually not valid,

# they will be reported later, after we resolve placeholders.

return PlaceholderType(

node.fullname,

self.anal_array(

t.args,

allow_param_spec=True,

allow_param_spec_literals=True,

allow_unpack=True,

),

t.line,

)

else:

if self.api.final_iteration:

self.cannot_resolve_type(t)

return AnyType(TypeOfAny.from_error)

else:

# Reference to an unknown placeholder node.

self.api.record_incomplete_ref()

return AnyType(TypeOfAny.special_form)

if node is None:

self.fail(f"Internal error (node is None, kind={sym.kind})", t)

return AnyType(TypeOfAny.special_form)

fullname = node.fullname

hook = self.plugin.get_type_analyze_hook(fullname)

if hook is not None:

return hook(AnalyzeTypeContext(t, t, self))

tvar_def = self.tvar_scope.get_binding(sym)

if tvar_def is not None:

# We need to cover special-case explained in get_typevarlike_argument() here,

# since otherwise the deferral will not be triggered if the type variable is

# used in a different module. Using isinstance() should be safe for this purpose.

tvar_params = [tvar_def.upper_bound, tvar_def.default]

if isinstance(tvar_def, TypeVarType):

tvar_params += tvar_def.values

if any(isinstance(tp, PlaceholderType) for tp in tvar_params):

self.api.defer()

if isinstance(sym.node, ParamSpecExpr):

if tvar_def is None:

if self.allow_unbound_tvars:

return t

name = param_spec_name or t.name

if self.defining_alias and self.not_declared_in_type_params(t.name):

msg = f'ParamSpec "{name}" is not included in type_params'

else:

msg = f'ParamSpec "{name}" is unbound'

self.fail(msg, t, code=codes.VALID_TYPE)

return AnyType(TypeOfAny.from_error)

assert isinstance(tvar_def, ParamSpecType)

if len(t.args) > 0:

self.fail(

f'ParamSpec "{t.name}" used with arguments', t, code=codes.VALID_TYPE

)

if param_spec_name is not None and not self.allow_param_spec_literals:

self.fail(

"ParamSpec components are not allowed here", t, code=codes.VALID_TYPE

)

return AnyType(TypeOfAny.from_error)

# Change the line number

return ParamSpecType(

tvar_def.name,

tvar_def.fullname,

tvar_def.id,

tvar_def.flavor,

tvar_def.upper_bound,

tvar_def.default,

line=t.line,

column=t.column,

)

if (

isinstance(sym.node, TypeVarExpr)

and self.defining_alias

and not defining_literal

and (tvar_def is None or tvar_def not in self.allowed_alias_tvars)

):

if self.not_declared_in_type_params(t.name):

if self.python_3_12_type_alias:

msg = message_registry.TYPE_PARAMETERS_SHOULD_BE_DECLARED.format(

f'"{t.name}"'

)

else:

msg = f'Type variable "{t.name}" is not included in type_params'

else:

msg = f'Can\'t use bound type variable "{t.name}" to define generic alias'

self.fail(msg, t, code=codes.VALID_TYPE)

return AnyType(TypeOfAny.from_error)

if isinstance(sym.node, TypeVarExpr) and tvar_def is not None:

assert isinstance(tvar_def, TypeVarType)

if len(t.args) > 0:

self.fail(

f'Type variable "{t.name}" used with arguments', t, code=codes.VALID_TYPE

)

# Change the line number

return tvar_def.copy_modified(line=t.line, column=t.column)

if isinstance(sym.node, TypeVarTupleExpr) and (

tvar_def is not None

and self.defining_alias

and tvar_def not in self.allowed_alias_tvars

):

if self.not_declared_in_type_params(t.name):

msg = f'Type variable "{t.name}" is not included in type_params'

else:

msg = f'Can\'t use bound type variable "{t.name}" to define generic alias'

self.fail(msg, t, code=codes.VALID_TYPE)

return AnyType(TypeOfAny.from_error)

if isinstance(sym.node, TypeVarTupleExpr):

if tvar_def is None:

if self.allow_unbound_tvars:

return t

if self.defining_alias and self.not_declared_in_type_params(t.name):

if self.python_3_12_type_alias:

msg = message_registry.TYPE_PARAMETERS_SHOULD_BE_DECLARED.format(

f'"{t.name}"'

)

else:

msg = f'TypeVarTuple "{t.name}" is not included in type_params'

else:

msg = f'TypeVarTuple "{t.name}" is unbound'

self.fail(msg, t, code=codes.VALID_TYPE)

return AnyType(TypeOfAny.from_error)

assert isinstance(tvar_def, TypeVarTupleType)

if not self.allow_type_var_tuple:

self.fail(

f'TypeVarTuple "{t.name}" is only valid with an unpack',

t,

code=codes.VALID_TYPE,

)

return AnyType(TypeOfAny.from_error)

if len(t.args) > 0:

self.fail(

f'Type variable "{t.name}" used with arguments', t, code=codes.VALID_TYPE

)

# Change the line number

return TypeVarTupleType(

tvar_def.name,

tvar_def.fullname,

tvar_def.id,

tvar_def.upper_bound,

sym.node.tuple_fallback,

tvar_def.default,

line=t.line,

column=t.column,

)

special = self.try_analyze_special_unbound_type(t, fullname)

if special is not None:

return special

if isinstance(node, TypeAlias):

self.aliases_used.add(fullname)

an_args = self.anal_array(

t.args,

allow_param_spec=True,

allow_param_spec_literals=node.has_param_spec_type,

allow_unpack=True, # Fixed length unpacks can be used for non-variadic aliases.

)

if node.has_param_spec_type and len(node.alias_tvars) == 1:

an_args = self.pack_paramspec_args(an_args)

disallow_any = self.options.disallow_any_generics and not self.is_typeshed_stub

res = instantiate_type_alias(

node,

an_args,

self.fail,

node.no_args,

t,

self.options,

unexpanded_type=t,

disallow_any=disallow_any,

empty_tuple_index=t.empty_tuple_index,

)

# The only case where instantiate_type_alias() can return an incorrect instance is

# when it is top-level instance, so no need to recurse.

if (

isinstance(res, ProperType)

and isinstance(res, Instance)

and not (self.defining_alias and self.nesting_level == 0)

and not validate_instance(res, self.fail, t.empty_tuple_index)

):

fix_instance(

res,

self.fail,

self.note,

disallow_any=disallow_any,

options=self.options,

use_generic_error=True,

unexpanded_type=t,

)

if node.eager:

res = get_proper_type(res)

return res

elif isinstance(node, TypeInfo):

return self.analyze_type_with_type_info(node, t.args, t, t.empty_tuple_index)

elif node.fullname in TYPE_ALIAS_NAMES:

return AnyType(TypeOfAny.special_form)

# Concatenate is an operator, no need for a proper type

elif node.fullname in CONCATENATE_TYPE_NAMES:

# We check the return type further up the stack for valid use locations

return self.apply_concatenate_operator(t)

else:

return self.analyze_unbound_type_without_type_info(t, sym, defining_literal)

else: # sym is None

return AnyType(TypeOfAny.special_form)

def pack_paramspec_args(self, an_args: Sequence[Type]) -> list[Type]:

# "Aesthetic" ParamSpec literals for single ParamSpec: C[int, str] -> C[[int, str]].

# These do not support mypy_extensions VarArgs, etc. as they were already analyzed

# TODO: should these be re-analyzed to get rid of this inconsistency?

count = len(an_args)

if count == 0:

return []

if count == 1 and isinstance(get_proper_type(an_args[0]), AnyType):

# Single Any is interpreted as ..., rather that a single argument with Any type.

# I didn't find this in the PEP, but it sounds reasonable.

return list(an_args)

if any(isinstance(a, (Parameters, ParamSpecType)) for a in an_args):

if len(an_args) > 1:

first_wrong = next(

arg for arg in an_args if isinstance(arg, (Parameters, ParamSpecType))

)

self.fail(

"Nested parameter specifications are not allowed",

first_wrong,

code=codes.VALID_TYPE,

)

return [AnyType(TypeOfAny.from_error)]

return list(an_args)

first = an_args[0]

return [

Parameters(

an_args, [ARG_POS] * count, [None] * count, line=first.line, column=first.column

)

]

def cannot_resolve_type(self, t: UnboundType) -> None:

# TODO: Move error message generation to messages.py. We'd first

# need access to MessageBuilder here. Also move the similar

# message generation logic in semanal.py.

self.api.fail(f'Cannot resolve name "{t.name}" (possible cyclic definition)', t)

if self.api.is_func_scope():

self.note("Recursive types are not allowed at function scope", t)

def apply_concatenate_operator(self, t: UnboundType) -> Type:

if len(t.args) == 0:

self.api.fail("Concatenate needs type arguments", t, code=codes.VALID_TYPE)

return AnyType(TypeOfAny.from_error)

# Last argument has to be ParamSpec or Ellipsis.

ps = self.anal_type(t.args[-1], allow_param_spec=True, allow_ellipsis=True)

if not isinstance(ps, (ParamSpecType, Parameters)):

if isinstance(ps, UnboundType) and self.allow_unbound_tvars:

sym = self.lookup_qualified(ps.name, t)

if sym is not None and isinstance(sym.node, ParamSpecExpr):

return ps

self.api.fail(

"The last parameter to Concatenate needs to be a ParamSpec",

t,

code=codes.VALID_TYPE,

)

return AnyType(TypeOfAny.from_error)

elif isinstance(ps, ParamSpecType) and ps.prefix.arg_types:

self.api.fail("Nested Concatenates are invalid", t, code=codes.VALID_TYPE)

args = self.anal_array(t.args[:-1])

pre = ps.prefix if isinstance(ps, ParamSpecType) else ps

# mypy can't infer this :(

names: list[str | None] = [None] * len(args)

pre = Parameters(

args + pre.arg_types,

[ARG_POS] * len(args) + pre.arg_kinds,

names + pre.arg_names,

line=t.line,

column=t.column,

)

return ps.copy_modified(prefix=pre) if isinstance(ps, ParamSpecType) else pre

def try_analyze_special_unbound_type(self, t: UnboundType, fullname: str) -> Type | None:

"""Bind special type that is recognized through magic name such as 'typing.Any'.

Return the bound type if successful, and return None if the type is a normal type.

"""

if fullname == "builtins.None":

return NoneType()

elif fullname == "typing.Any":

return AnyType(TypeOfAny.explicit, line=t.line, column=t.column)

elif fullname in FINAL_TYPE_NAMES:

if self.prohibit_special_class_field_types:

self.fail(

f"Final[...] can't be used inside a {self.prohibit_special_class_field_types}",

t,

code=codes.VALID_TYPE,

)

else:

if not self.allow_final:

self.fail(

"Final can be only used as an outermost qualifier in a variable annotation",

t,

code=codes.VALID_TYPE,

)

return AnyType(TypeOfAny.from_error)

elif fullname in TUPLE_NAMES:

# Tuple is special because it is involved in builtin import cycle

# and may be not ready when used.

sym = self.api.lookup_fully_qualified_or_none("builtins.tuple")

if not sym or isinstance(sym.node, PlaceholderNode):

if self.api.is_incomplete_namespace("builtins"):

self.api.record_incomplete_ref()

else:

self.fail('Name "tuple" is not defined', t)

return AnyType(TypeOfAny.special_form)

if len(t.args) == 0 and not t.empty_tuple_index:

# Bare 'Tuple' is same as 'tuple'

any_type = self.get_omitted_any(t)

return self.named_type("builtins.tuple", [any_type], line=t.line, column=t.column)

if len(t.args) == 2 and isinstance(t.args[1], EllipsisType):

# Tuple[T, ...] (uniform, variable-length tuple)

instance = self.named_type("builtins.tuple", [self.anal_type(t.args[0])])

instance.line = t.line

return instance

return self.tuple_type(

self.anal_array(t.args, allow_unpack=True), line=t.line, column=t.column

)

elif fullname == "typing.Union":

items = self.anal_array(t.args)

return UnionType.make_union(items, line=t.line, column=t.column)

elif fullname == "typing.Optional":

if len(t.args) != 1:

self.fail(

"Optional[...] must have exactly one type argument", t, code=codes.VALID_TYPE

)

return AnyType(TypeOfAny.from_error)

item = self.anal_type(t.args[0])

return make_optional_type(item)

elif fullname == "typing.Callable":

return self.analyze_callable_type(t)

elif fullname in TYPE_NAMES:

if len(t.args) == 0:

if fullname == "typing.Type":

any_type = self.get_omitted_any(t)

return TypeType(any_type, line=t.line, column=t.column)

else:

# To prevent assignment of 'builtins.type' inferred as 'builtins.object'

# See https://github.com/python/mypy/issues/9476 for more information

return None

type_str = "Type[...]" if fullname == "typing.Type" else "type[...]"

if len(t.args) != 1:

self.fail(

f"{type_str} must have exactly one type argument", t, code=codes.VALID_TYPE

)

item = self.anal_type(t.args[0])

bad_item_name = get_bad_type_type_item(item)

if bad_item_name:

self.fail(f'{type_str} can\'t contain "{bad_item_name}"', t, code=codes.VALID_TYPE)

item = AnyType(TypeOfAny.from_error)

return TypeType.make_normalized(item, line=t.line, column=t.column)

elif fullname in ("typing_extensions.TypeForm", "typing.TypeForm"):

if TYPE_FORM not in self.options.enable_incomplete_feature:

self.fail(

"TypeForm is experimental,"

" must be enabled with --enable-incomplete-feature=TypeForm",

t,

)

if len(t.args) == 0:

any_type = self.get_omitted_any(t)

return TypeType(any_type, line=t.line, column=t.column, is_type_form=True)

if len(t.args) != 1:

type_str = "TypeForm[...]"

self.fail(

type_str + " must have exactly one type argument", t, code=codes.VALID_TYPE

)

item = self.anal_type(t.args[0])

return TypeType.make_normalized(item, line=t.line, column=t.column, is_type_form=True)

elif fullname == "typing.ClassVar":

if self.nesting_level > 0:

self.fail(

"Invalid type: ClassVar nested inside other type", t, code=codes.VALID_TYPE

)

if self.prohibit_special_class_field_types:

self.fail(

f"ClassVar[...] can't be used inside a {self.prohibit_special_class_field_types}",

t,

code=codes.VALID_TYPE,

)

if self.defining_alias:

self.fail(

"ClassVar[...] can't be used inside a type alias", t, code=codes.VALID_TYPE

)

if len(t.args) == 0:

return AnyType(TypeOfAny.from_omitted_generics, line=t.line, column=t.column)

if len(t.args) != 1:

self.fail(

"ClassVar[...] must have at most one type argument", t, code=codes.VALID_TYPE

)

return AnyType(TypeOfAny.from_error)

return self.anal_type(t.args[0], allow_final=self.options.python_version >= (3, 13))

elif fullname in NEVER_NAMES:

return UninhabitedType()

elif fullname in LITERAL_TYPE_NAMES:

return self.analyze_literal_type(t)

elif fullname in ANNOTATED_TYPE_NAMES:

if len(t.args) < 2:

self.fail(

"Annotated[...] must have exactly one type argument"

" and at least one annotation",

t,

code=codes.VALID_TYPE,

)

return AnyType(TypeOfAny.from_error)

return self.anal_type(

t.args[0], allow_typed_dict_special_forms=self.allow_typed_dict_special_forms

)

elif fullname in ("typing_extensions.Required", "typing.Required"):

if not self.allow_typed_dict_special_forms:

self.fail(

"Required[] can be only used in a TypedDict definition",

t,

code=codes.VALID_TYPE,

)

return AnyType(TypeOfAny.from_error)

if len(t.args) != 1:

self.fail(

"Required[] must have exactly one type argument", t, code=codes.VALID_TYPE

)

return AnyType(TypeOfAny.from_error)

return RequiredType(

self.anal_type(t.args[0], allow_typed_dict_special_forms=True), required=True

)

elif fullname in ("typing_extensions.NotRequired", "typing.NotRequired"):

if not self.allow_typed_dict_special_forms:

self.fail(

"NotRequired[] can be only used in a TypedDict definition",

t,

code=codes.VALID_TYPE,

)

return AnyType(TypeOfAny.from_error)

if len(t.args) != 1:

self.fail(

"NotRequired[] must have exactly one type argument", t, code=codes.VALID_TYPE

)

return AnyType(TypeOfAny.from_error)

return RequiredType(

self.anal_type(t.args[0], allow_typed_dict_special_forms=True), required=False

)

elif fullname in ("typing_extensions.ReadOnly", "typing.ReadOnly"):

if not self.allow_typed_dict_special_forms:

self.fail(

"ReadOnly[] can be only used in a TypedDict definition",

t,

code=codes.VALID_TYPE,

)

return AnyType(TypeOfAny.from_error)

if len(t.args) != 1:

self.fail(

'"ReadOnly[]" must have exactly one type argument', t, code=codes.VALID_TYPE

)

return AnyType(TypeOfAny.from_error)

return ReadOnlyType(self.anal_type(t.args[0], allow_typed_dict_special_forms=True))

elif (

self.anal_type_guard_arg(t, fullname) is not None

or self.anal_type_is_arg(t, fullname) is not None

):

# In most contexts, TypeGuard[...] acts as an alias for bool (ignoring its args)

return self.named_type("builtins.bool")

elif fullname in UNPACK_TYPE_NAMES:

if len(t.args) != 1:

self.fail("Unpack[...] requires exactly one type argument", t)

return AnyType(TypeOfAny.from_error)

if not self.allow_unpack:

self.fail(message_registry.INVALID_UNPACK_POSITION, t, code=codes.VALID_TYPE)

return AnyType(TypeOfAny.from_error)

self.allow_type_var_tuple = True

result = UnpackType(self.anal_type(t.args[0]), line=t.line, column=t.column)

self.allow_type_var_tuple = False

return result

elif fullname in SELF_TYPE_NAMES:

if t.args:

self.fail("Self type cannot have type arguments", t)

if self.prohibit_self_type is not None:

self.fail(f"Self type cannot be used in {self.prohibit_self_type}", t)

return AnyType(TypeOfAny.from_error)

if self.api.type is None:

self.fail("Self type is only allowed in annotations within class definition", t)

return AnyType(TypeOfAny.from_error)

if self.api.type.has_base("builtins.type"):

self.fail("Self type cannot be used in a metaclass", t)

if self.api.type.self_type is not None:

if self.api.type.is_final or self.api.type.is_enum and self.api.type.enum_members:

return fill_typevars(self.api.type)

return self.api.type.self_type.copy_modified(line=t.line, column=t.column)

# TODO: verify this is unreachable and replace with an assert?

self.fail("Unexpected Self type", t)

return AnyType(TypeOfAny.from_error)

return None

def get_omitted_any(self, typ: Type, fullname: str | None = None) -> AnyType:

disallow_any = not self.is_typeshed_stub and self.options.disallow_any_generics

return get_omitted_any(disallow_any, self.fail, self.note, typ, self.options, fullname)

def check_and_warn_deprecated(self, info: TypeInfo, ctx: Context) -> None:

"""Similar logic to `TypeChecker.check_deprecated` and `TypeChecker.warn_deprecated."""

if (

(deprecated := info.deprecated)

and not self.is_typeshed_stub

and not (self.api.type and (self.api.type.fullname == info.fullname))

and not any(

info.fullname == p or info.fullname.startswith(f"{p}.")

for p in self.options.deprecated_calls_exclude

)

):

for imp in self.cur_mod_node.imports:

if isinstance(imp, ImportFrom) and any(info.name == n[0] for n in imp.names):

break

else:

warn = self.note if self.options.report_deprecated_as_note else self.fail

warn(deprecated, ctx, code=codes.DEPRECATED)

def analyze_type_with_type_info(

self, info: TypeInfo, args: Sequence[Type], ctx: Context, empty_tuple_index: bool

) -> Type:

"""Bind unbound type when were able to find target TypeInfo.

This handles simple cases like 'int', 'modname.UserClass[str]', etc.

"""

self.check_and_warn_deprecated(info, ctx)

if len(args) > 0 and info.fullname == "builtins.tuple":

fallback = Instance(info, [AnyType(TypeOfAny.special_form)], ctx.line)

return TupleType(self.anal_array(args, allow_unpack=True), fallback, ctx.line)

# Analyze arguments and (usually) construct Instance type. The

# number of type arguments and their values are

# checked only later, since we do not always know the

# valid count at this point. Thus we may construct an

# Instance with an invalid number of type arguments.

#

# We allow ParamSpec literals based on a heuristic: it will be

# checked later anyways but the error message may be worse.

instance = Instance(

info,

self.anal_array(

args,

allow_param_spec=True,

allow_param_spec_literals=info.has_param_spec_type,

allow_unpack=True, # Fixed length tuples can be used for non-variadic types.

),

ctx.line,

ctx.column,

)

instance.end_line = ctx.end_line

instance.end_column = ctx.end_column

if len(info.type_vars) == 1 and info.has_param_spec_type:

instance.args = tuple(self.pack_paramspec_args(instance.args))

# Check type argument count.

instance.args = tuple(flatten_nested_tuples(instance.args))

if not (self.defining_alias and self.nesting_level == 0) and not validate_instance(

instance, self.fail, empty_tuple_index

):

fix_instance(

instance,

self.fail,

self.note,

disallow_any=self.options.disallow_any_generics and not self.is_typeshed_stub,

options=self.options,

)

tup = info.tuple_type

if tup is not None:

# The class has a Tuple[...] base class so it will be

# represented as a tuple type.

if info.special_alias:

return instantiate_type_alias(

info.special_alias,

# TODO: should we allow NamedTuples generic in ParamSpec?

self.anal_array(args, allow_unpack=True),

self.fail,

False,

ctx,

self.options,

use_standard_error=True,

)

return tup.copy_modified(

items=self.anal_array(tup.items, allow_unpack=True), fallback=instance

)

td = info.typeddict_type

if td is not None:

# The class has a TypedDict[...] base class so it will be

# represented as a typeddict type.

if info.special_alias:

return instantiate_type_alias(

info.special_alias,

# TODO: should we allow TypedDicts generic in ParamSpec?

self.anal_array(args, allow_unpack=True),

self.fail,

False,

ctx,

self.options,

use_standard_error=True,

)

# Create a named TypedDictType

return td.copy_modified(

item_types=self.anal_array(list(td.items.values())), fallback=instance

)

if info.fullname == "types.NoneType":

self.fail(

"NoneType should not be used as a type, please use None instead",

ctx,

code=codes.NONETYPE_TYPE,

)

return NoneType(ctx.line, ctx.column)

return instance

def analyze_unbound_type_without_type_info(

self, t: UnboundType, sym: SymbolTableNode, defining_literal: bool

) -> Type:

"""Figure out what an unbound type that doesn't refer to a TypeInfo node means.

This is something unusual. We try our best to find out what it is.

"""

name = sym.fullname

if name is None:

assert sym.node is not None

name = sym.node.name

# Option 1:

# Something with an Any type -- make it an alias for Any in a type

# context. This is slightly problematic as it allows using the type 'Any'

# as a base class -- however, this will fail soon at runtime so the problem

# is pretty minor.

if isinstance(sym.node, Var):

typ = get_proper_type(sym.node.type)

if isinstance(typ, AnyType):

return AnyType(

TypeOfAny.from_unimported_type, missing_import_name=typ.missing_import_name

)

elif self.allow_type_any:

if isinstance(typ, Instance) and typ.type.fullname == "builtins.type":

return AnyType(TypeOfAny.special_form)

if isinstance(typ, TypeType) and isinstance(typ.item, AnyType):

return AnyType(TypeOfAny.from_another_any, source_any=typ.item)

# Option 2:

# Unbound type variable. Currently these may be still valid,

# for example when defining a generic type alias.

unbound_tvar = (

isinstance(sym.node, (TypeVarExpr, TypeVarTupleExpr))

and self.tvar_scope.get_binding(sym) is None

)

if self.allow_unbound_tvars and unbound_tvar:

return t

# Option 3:

# Enum value. Note: we only want to return a LiteralType when

# we're using this enum value specifically within context of

# a "Literal[...]" type. So, if `defining_literal` is not set,

# we bail out early with an error.

#

# If, in the distant future, we decide to permit things like

# `def foo(x: Color.RED) -> None: ...`, we can remove that

# check entirely.

if (

isinstance(sym.node, Var)

and sym.node.info

and sym.node.info.is_enum

and not sym.node.name.startswith("__")

):

value = sym.node.name

base_enum_short_name = sym.node.info.name

if not defining_literal:

msg = message_registry.INVALID_TYPE_RAW_ENUM_VALUE.format(

base_enum_short_name, value

)

self.fail(msg.value, t, code=msg.code)

return AnyType(TypeOfAny.from_error)

return LiteralType(

value=value,

fallback=Instance(sym.node.info, [], line=t.line, column=t.column),