"""The semantic analyzer.

Bind names to definitions and do various other simple consistency

checks. Populate symbol tables. The semantic analyzer also detects

special forms which reuse generic syntax such as NamedTuple and

cast(). Multiple analysis iterations may be needed to analyze forward

references and import cycles. Each iteration "fills in" additional

bindings and references until everything has been bound.

For example, consider this program:

x = 1

y = x

Here semantic analysis would detect that the assignment 'x = 1'

defines a new variable, the type of which is to be inferred (in a

later pass; type inference or type checking is not part of semantic

analysis). Also, it would bind both references to 'x' to the same

module-level variable (Var) node. The second assignment would also

be analyzed, and the type of 'y' marked as being inferred.

Semantic analysis of types is implemented in typeanal.py.

See semanal_main.py for the top-level logic.

Some important properties:

* After semantic analysis is complete, no PlaceholderNode and

PlaceholderType instances should remain. During semantic analysis,

if we encounter one of these, the current target should be deferred.

* A TypeInfo is only created once we know certain basic information about

a type, such as the MRO, existence of a Tuple base class (e.g., for named

tuples), and whether we have a TypedDict. We use a temporary

PlaceholderNode node in the symbol table if some such information is

missing.

* For assignments, we only add a non-placeholder symbol table entry once

we know the sort of thing being defined (variable, NamedTuple, type alias,

etc.).

* Every part of the analysis step must support multiple iterations over

the same AST nodes, and each iteration must be able to fill in arbitrary

things that were missing or incomplete in previous iterations.

* Changes performed by the analysis need to be reversible, since mypy

daemon strips and reuses existing ASTs (to improve performance and/or

reduce memory use).

"""

from __future__ import annotations

import re

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

from contextlib import contextmanager

from typing import Any, Final, TypeAlias as _TypeAlias, TypeGuard, TypeVar, cast

from typing_extensions import assert_never

from mypy import errorcodes as codes, message_registry

from mypy.constant_fold import constant_fold_expr

from mypy.errorcodes import PROPERTY_DECORATOR, ErrorCode

from mypy.errors import Errors, report_internal_error

from mypy.exprtotype import TypeTranslationError, expr_to_unanalyzed_type

from mypy.message_registry import CANNOT_DECLARE_TYPE_OF_SPECIAL_FORM, ErrorMessage

from mypy.messages import (

SUGGESTED_TEST_FIXTURES,

TYPES_FOR_UNIMPORTED_HINTS,

MessageBuilder,

best_matches,

pretty_seq,

)

from mypy.mro import MroError, calculate_mro

from mypy.nodes import (

ARG_NAMED,

ARG_POS,

ARG_STAR2,

CONTRAVARIANT,

COVARIANT,

GDEF,

IMPLICITLY_ABSTRACT,

INVARIANT,

IS_ABSTRACT,

LDEF,

MDEF,

NOT_ABSTRACT,

PARAM_SPEC_KIND,

REVEAL_LOCALS,

REVEAL_TYPE,

RUNTIME_PROTOCOL_DECOS,

SYMBOL_FUNCBASE_TYPES,

TYPE_VAR_KIND,

TYPE_VAR_TUPLE_KIND,

VARIANCE_NOT_READY,

ArgKind,

AssertStmt,

AssertTypeExpr,

AssignmentExpr,

AssignmentStmt,

AwaitExpr,

Block,

BreakStmt,

BytesExpr,

CallExpr,

CastExpr,

ClassDef,

ComparisonExpr,

ComplexExpr,

ConditionalExpr,

Context,

ContinueStmt,

DataclassTransformSpec,

Decorator,

DelStmt,

DictExpr,

DictionaryComprehension,

EllipsisExpr,

EnumCallExpr,

Expression,

ExpressionStmt,

FakeExpression,

FloatExpr,

ForStmt,

FuncBase,

FuncDef,

FuncItem,

GeneratorExpr,

GlobalDecl,

IfStmt,

Import,

ImportAll,

ImportBase,

ImportFrom,

IndexExpr,

IntExpr,

LambdaExpr,

ListComprehension,

ListExpr,

Lvalue,

MatchStmt,

MaybeTypeExpression,

MemberExpr,

MypyFile,

NamedTupleExpr,

NameExpr,

Node,

NonlocalDecl,

OperatorAssignmentStmt,

OpExpr,

OverloadedFuncDef,

OverloadPart,

ParamSpecExpr,

PassStmt,

PlaceholderNode,

PromoteExpr,

RaiseStmt,

RefExpr,

ReturnStmt,

RevealExpr,

SetComprehension,

SetExpr,

SliceExpr,

SplittingVisitor,

StarExpr,

Statement,

StrExpr,

SuperExpr,

SymbolNode,

SymbolTable,

SymbolTableNode,

TemplateStrExpr,

TempNode,

TryStmt,

TupleExpr,

TypeAlias,

TypeAliasExpr,

TypeAliasStmt,

TypeApplication,

TypedDictExpr,

TypeFormExpr,

TypeInfo,

TypeParam,

TypeVarExpr,

TypeVarLikeExpr,

TypeVarTupleExpr,

UnaryExpr,

Var,

WhileStmt,

WithStmt,

YieldExpr,

YieldFromExpr,

func_scoped_name,

get_member_expr_fullname,

implicit_module_attrs,

inline_base,

is_final_node,

type_aliases,

type_aliases_source_versions,

typing_extensions_aliases,

)

from mypy.options import Options

from mypy.patterns import (

AsPattern,

ClassPattern,

MappingPattern,

OrPattern,

SequencePattern,

SingletonPattern,

StarredPattern,

ValuePattern,

)

from mypy.plugin import (

ClassDefContext,

DynamicClassDefContext,

Plugin,

SemanticAnalyzerPluginInterface,

)

from mypy.plugins import dataclasses as dataclasses_plugin

from mypy.reachability import (

ALWAYS_FALSE,

ALWAYS_TRUE,

MYPY_FALSE,

MYPY_TRUE,

infer_condition_value,

infer_reachability_of_if_statement,

infer_reachability_of_match_statement,

)

from mypy.scope import Scope

from mypy.semanal_enum import EnumCallAnalyzer

from mypy.semanal_namedtuple import NamedTupleAnalyzer

from mypy.semanal_newtype import NewTypeAnalyzer

from mypy.semanal_shared import (

ALLOW_INCOMPATIBLE_OVERRIDE,

PRIORITY_FALLBACKS,

SemanticAnalyzerInterface,

calculate_tuple_fallback,

find_dataclass_transform_spec,

has_placeholder,

parse_bool,

require_bool_literal_argument,

set_callable_name as set_callable_name,

)

from mypy.semanal_typeddict import TypedDictAnalyzer

from mypy.tvar_scope import TypeVarLikeScope

from mypy.typeanal import (

SELF_TYPE_NAMES,

FindTypeVarVisitor,

TypeAnalyser,

TypeVarDefaultTranslator,

TypeVarLikeList,

analyze_type_alias,

check_for_explicit_any,

check_vec_type_args,

detect_diverging_alias,

find_self_type,

fix_instance,

has_any_from_unimported_type,

type_constructors,

validate_instance,

)

from mypy.typeops import function_type, get_type_vars, try_getting_str_literals_from_type

from mypy.types import (

ANNOTATED_TYPE_NAMES,

ASSERT_TYPE_NAMES,

DATACLASS_TRANSFORM_NAMES,

DEPRECATED_TYPE_NAMES,

DISJOINT_BASE_DECORATOR_NAMES,

FINAL_DECORATOR_NAMES,

FINAL_TYPE_NAMES,

IMPORTED_REVEAL_TYPE_NAMES,

NEVER_NAMES,

OVERLOAD_NAMES,

OVERRIDE_DECORATOR_NAMES,

PROTOCOL_NAMES,

REVEAL_TYPE_NAMES,

SENTINEL_TYPE_NAMES,

TPDICT_NAMES,

TYPE_ALIAS_NAMES,

TYPE_CHECK_ONLY_NAMES,

TYPE_NAMES,

TYPE_VAR_LIKE_NAMES,

TYPED_NAMEDTUPLE_NAMES,

UNPACK_TYPE_NAMES,

AnyType,

CallableType,

FunctionLike,

Instance,

LiteralType,

NoneType,

Overloaded,

Parameters,

ParamSpecType,

PlaceholderType,

ProperType,

SentinelValue,

TrivialSyntheticTypeTranslator,

TupleType,

Type,

TypeAliasType,

TypedDictType,

TypeOfAny,

TypeStrVisitor,

TypeType,

TypeVarId,

TypeVarLikeType,

TypeVarTupleType,

TypeVarType,

UnboundType,

UnionType,

UnpackType,

flatten_nested_tuples,

get_proper_type,

get_proper_types,

has_type_vars,

is_named_instance,

remove_dups,

type_vars_as_args,

)

from mypy.types_utils import is_invalid_recursive_alias, store_argument_type

from mypy.typevars import fill_typevars

from mypy.util import correct_relative_import, is_dunder, module_prefix, unmangle, unnamed_function

from mypy.visitor import NodeVisitor

T = TypeVar("T")

# Whether to print diagnostic information for failed full parses

# in SemanticAnalyzer.try_parse_as_type_expression().

#

# See also: misc/analyze_typeform_stats.py

DEBUG_TYPE_EXPRESSION_FULL_PARSE_FAILURES: Final = False

FUTURE_IMPORTS: Final = {

"__future__.nested_scopes": "nested_scopes",

"__future__.generators": "generators",

"__future__.division": "division",

"__future__.absolute_import": "absolute_import",

"__future__.with_statement": "with_statement",

"__future__.print_function": "print_function",

"__future__.unicode_literals": "unicode_literals",

"__future__.barry_as_FLUFL": "barry_as_FLUFL",

"__future__.generator_stop": "generator_stop",

"__future__.annotations": "annotations",

}

# Special cased built-in classes that are needed for basic functionality and need to be

# available very early on.

CORE_BUILTIN_CLASSES: Final = ["object", "bool", "function"]

# Python has several different scope/namespace kinds with subtly different semantics.

SCOPE_GLOBAL: Final = 0 # Module top level

SCOPE_CLASS: Final = 1 # Class body

SCOPE_FUNC: Final = 2 # Function or lambda

SCOPE_COMPREHENSION: Final = 3 # Comprehension or generator expression

SCOPE_ANNOTATION: Final = 4 # Annotation scopes for type parameters and aliases (PEP 695)

# Used for tracking incomplete references

Tag: _TypeAlias = int

# Matches two words separated by whitespace, where each word lacks

# any symbols which have special meaning in a type expression.

#

# Any string literal matching this common pattern cannot be a valid

# type expression and can be ignored quickly when attempting to parse a

# string literal as a type expression.

_MULTIPLE_WORDS_NONTYPE_RE = re.compile(r'\s*[^\s.\'"|\[]+\s+[^\s.\'"|\[]')

# Characters which never appear in a valid type expression.

# NOTE: Allows '*' for (PEP 646 Unpack) and '+' for (Literal[+N])

# NOTE: Stored as a tuple of single-character strings (rather than a str)

# so that iterating it does not allocate a new string per character

# when compiled with mypyc.

_NONTYPE_CHARS: Final = tuple("!:/<>@%$^?;&~`\\")

class SemanticAnalyzer(

NodeVisitor[None], SemanticAnalyzerInterface, SemanticAnalyzerPluginInterface, SplittingVisitor

):

"""Semantically analyze parsed mypy files.

The analyzer binds names and does various consistency checks for an

AST. Note that type checking is performed as a separate pass.

"""

__deletable__ = ["patches", "options", "cur_mod_node"]

# Module name space

modules: dict[str, MypyFile]

# Global name space for current module

globals: SymbolTable

# Names declared using "global" (separate set for each scope)

global_decls: list[set[str]]

# Names declared using "nonlocal" (separate set for each scope)

nonlocal_decls: list[set[str]]

# Local names of function scopes; None for non-function scopes.

locals: list[SymbolTable | None]

# Type of each scope (SCOPE_*, indexes match locals)

scope_stack: list[int]

# Nested block depths of scopes

block_depth: list[int]

# TypeInfo of directly enclosing class (or None)

_type: TypeInfo | None = None

# Stack of outer classes (the second tuple item contains tvars).

type_stack: list[TypeInfo | None]

# Type variables bound by the current scope, be it class or function

tvar_scope: TypeVarLikeScope

# Per-module options

options: Options

# Stack of functions being analyzed

function_stack: list[FuncItem]

# Set to True if semantic analysis defines a name, or replaces a

# placeholder definition. If some iteration makes no progress,

# there can be at most one additional final iteration (see below).

progress = False

deferred = False # Set to true if another analysis pass is needed

incomplete = False # Set to true if current module namespace is missing things

# Is this the final iteration of semantic analysis (where we report

# unbound names due to cyclic definitions and should not defer)?

_final_iteration = False

# These names couldn't be added to the symbol table due to incomplete deps.

# Note that missing names are per module, _not_ per namespace. This means that e.g.

# a missing name at global scope will block adding same name at a class scope.

# This should not affect correctness and is purely a performance issue,

# since it can cause unnecessary deferrals. These are represented as

# PlaceholderNodes in the symbol table. We use this to ensure that the first

# definition takes precedence even if it's incomplete.

#

# Note that a star import adds a special name '*' to the set, this blocks

# adding _any_ names in the current file.

missing_names: list[set[str]]

# Callbacks that will be called after semantic analysis to tweak things.

patches: list[tuple[int, Callable[[], None]]]

loop_depth: list[int] # Depth of breakable loops

cur_mod_id = "" # Current module id (or None) (phase 2)

_is_stub_file = False # Are we analyzing a stub file?

_is_typeshed_stub_file = False # Are we analyzing a typeshed stub file?

imports: set[str] # Imported modules (during phase 2 analysis)

# Note: some imports (and therefore dependencies) might

# not be found in phase 1, for example due to * imports.

errors: Errors # Keeps track of generated errors

plugin: Plugin # Mypy plugin for special casing of library features

statement: Statement | None = None # Statement/definition being analyzed

# Mapping from 'async def' function definitions to their return type wrapped as a

# 'Coroutine[Any, Any, T]'. Used to keep track of whether a function definition's

# return type has already been wrapped, by checking if the function definition's

# type is stored in this mapping and that it still matches.

wrapped_coro_return_types: dict[FuncDef, Type] = {}

def __init__(

self,

modules: dict[str, MypyFile],

missing_modules: dict[str, int],

incomplete_namespaces: set[str],

errors: Errors,

plugin: Plugin,

import_map: dict[str, set[str]],

) -> None:

"""Construct semantic analyzer.

We reuse the same semantic analyzer instance across multiple modules.

Args:

modules: Global modules dictionary

missing_modules: Modules that could not be imported encountered so far

incomplete_namespaces: Namespaces that are being populated during semantic analysis

(can contain modules and classes within the current SCC; mutated by the caller)

errors: Report analysis errors using this instance

"""

self.locals = [None]

self.scope_stack = [SCOPE_GLOBAL]

# Saved namespaces from previous iteration. Every top-level function/method body is

# analyzed in several iterations until all names are resolved. We need to save

# the local namespaces for the top level function and all nested functions between

# these iterations. See also semanal_main.process_top_level_function().

self.saved_locals: dict[

FuncItem | GeneratorExpr | DictionaryComprehension, SymbolTable

] = {}

self.imports = set()

self._type = None

self.type_stack = []

# Are the namespaces of classes being processed complete?

self.incomplete_type_stack: list[bool] = []

self.tvar_scope = TypeVarLikeScope()

self.function_stack = []

self.block_depth = [0]

self.loop_depth = [0]

self.errors = errors

self.modules = modules

self.import_map = import_map

self.msg = MessageBuilder(errors, modules)

self.missing_modules = missing_modules

self.missing_names = [set()]

# These namespaces are still in process of being populated. If we encounter a

# missing name in these namespaces, we need to defer the current analysis target,

# since it's possible that the name will be there once the namespace is complete.

self.incomplete_namespaces = incomplete_namespaces

self.all_exports: list[str] = []

self.plugin = plugin

self.recurse_into_functions = True

self.scope = Scope()

# Trace line numbers for every file where deferral happened during analysis of

# current SCC or top-level function.

self.deferral_debug_context: list[tuple[str, int]] = []

# This is needed to properly support recursive type aliases. The problem is that

# Foo[Bar] could mean three things depending on context: a target for type alias,

# a normal index expression (including enum index), or a type application.

# The latter is particularly problematic as it can falsely create incomplete

# refs while analysing rvalues of type aliases. To avoid this we first analyse

# rvalues while temporarily setting this to True.

self.basic_type_applications = False

# Used to temporarily enable unbound type variables in some contexts. Namely,

# in base class expressions, and in right hand sides of type aliases. Do not add

# new uses of this, as this may cause leaking `UnboundType`s to type checking.

self.allow_unbound_tvars = False

# Used to pass information about current overload index to visit_func_def().

self.current_overload_item: int | None = None

# Used to track whether currently inside an except* block. This helps

# to invoke errors when continue/break/return is used inside except* block.

self.inside_except_star_block: bool = False

# Used to track edge case when return is still inside except* if it enters a loop

self.return_stmt_inside_except_star_block: bool = False

self._str_type: Instance | None = None

self._function_type: Instance | None = None

self._object_type: Instance | None = None

# TypeForm profiling counters

self.type_expression_parse_count: int = 0 # Total try_parse_as_type_expression calls

self.type_expression_full_parse_success_count: int = 0 # Successful full parses

self.type_expression_full_parse_failure_count: int = 0 # Failed full parses

# Imports of submodules transitively visible from given module.

# This is needed to support patterns like this

# [a.py]

# import b

# import foo

# foo.bar # <- this should work even if bar is not re-exported in foo

# [b.py]

# import foo.bar

self.transitive_submodule_imports: dict[str, set[str]] = {}

# Instances and type aliases that were fixed using default values of type

# variables. This can be used on-demand by type analyzer. Use record_fixed_type()

# to create the set lazily.

self.types_fixed: set[TypeInfo | TypeAlias] | None = None

# Stack of type variables that have been removed from current class because they

# cannot be bound unambiguously. This can happen if a (regular) type variable

# with a default follows a type variable tuple.

self.removed_type_vars: list[list[TypeVarType]] = [[]]

# mypyc doesn't properly handle implementing an abstractproperty

# with a regular attribute, so we make them properties

@property

def type(self) -> TypeInfo | None:

return self._type

@property

def is_stub_file(self) -> bool:

return self._is_stub_file

@property

def is_typeshed_stub_file(self) -> bool:

return self._is_typeshed_stub_file

@property

def final_iteration(self) -> bool:

return self._final_iteration

@contextmanager

def allow_unbound_tvars_set(self) -> Iterator[None]:

old = self.allow_unbound_tvars

self.allow_unbound_tvars = True

try:

yield

finally:

self.allow_unbound_tvars = old

@contextmanager

def inside_except_star_block_set(

self, value: bool, entering_loop: bool = False

) -> Iterator[None]:

old = self.inside_except_star_block

self.inside_except_star_block = value

# Return statement would still be in except* scope if entering loops

if not entering_loop:

old_return_stmt_flag = self.return_stmt_inside_except_star_block

self.return_stmt_inside_except_star_block = value

try:

yield

finally:

self.inside_except_star_block = old

if not entering_loop:

self.return_stmt_inside_except_star_block = old_return_stmt_flag

#

# Preparing module (performed before semantic analysis)

#

def prepare_file(self, file_node: MypyFile) -> None:

"""Prepare a freshly parsed file for semantic analysis."""

if "builtins" in self.modules:

file_node.names["__builtins__"] = SymbolTableNode(GDEF, self.modules["builtins"])

if file_node.fullname == "builtins":

self.prepare_builtins_namespace(file_node)

if file_node.fullname == "typing":

self.prepare_typing_namespace(file_node, type_aliases)

if file_node.fullname == "typing_extensions":

self.prepare_typing_namespace(file_node, typing_extensions_aliases)

def prepare_typing_namespace(self, file_node: MypyFile, aliases: dict[str, str]) -> None:

"""Remove dummy alias definitions such as List = TypeAlias(object) from typing.

They will be replaced with real aliases when corresponding targets are ready.

"""

# This is all pretty unfortunate. typeshed now has a

# sys.version_info check for OrderedDict, and we shouldn't

# take it out, because it is correct and a typechecker should

# use that as a source of truth. But instead we rummage

# through IfStmts to remove the info first. (I tried to

# remove this whole machinery and ran into issues with the

# builtins/typing import cycle.)

def helper(defs: list[Statement]) -> None:

for stmt in defs.copy():

if isinstance(stmt, IfStmt):

for body in stmt.body:

helper(body.body)

if stmt.else_body:

helper(stmt.else_body.body)

if (

isinstance(stmt, AssignmentStmt)

and len(stmt.lvalues) == 1

and isinstance(stmt.lvalues[0], NameExpr)

):

# Assignment to a simple name, remove it if it is a dummy alias.

if f"{file_node.fullname}.{stmt.lvalues[0].name}" in aliases:

defs.remove(stmt)

helper(file_node.defs)

def prepare_builtins_namespace(self, file_node: MypyFile) -> None:

"""Add certain special-cased definitions to the builtins module.

Some definitions are too special or fundamental to be processed

normally from the AST.

"""

names = file_node.names

# Add empty definition for core built-in classes, since they are required for basic

# operation. These will be completed later on.

for name in CORE_BUILTIN_CLASSES:

cdef = ClassDef(name, Block([])) # Dummy ClassDef, will be replaced later

info = TypeInfo(SymbolTable(), cdef, "builtins")

info._fullname = f"builtins.{name}"

names[name] = SymbolTableNode(GDEF, info)

bool_info = names["bool"].node

assert isinstance(bool_info, TypeInfo)

bool_type = Instance(bool_info, [])

special_var_types: list[tuple[str, Type]] = [

("None", NoneType()),

# reveal_type is a mypy-only function that gives an error with

# the type of its arg.

("reveal_type", AnyType(TypeOfAny.special_form)),

# reveal_locals is a mypy-only function that gives an error with the types of

# locals

("reveal_locals", AnyType(TypeOfAny.special_form)),

("True", bool_type),

("False", bool_type),

("__debug__", bool_type),

]

for name, typ in special_var_types:

v = Var(name, typ)

v._fullname = f"builtins.{name}"

file_node.names[name] = SymbolTableNode(GDEF, v)

#

# Analyzing a target

#

def refresh_partial(

self,

node: MypyFile | FuncDef | OverloadedFuncDef,

patches: list[tuple[int, Callable[[], None]]],

final_iteration: bool,

file_node: MypyFile,

options: Options,

active_type: TypeInfo | None = None,

) -> None:

"""Refresh a stale target in fine-grained incremental mode."""

self.patches = patches

self.deferred = False

self.incomplete = False

self._final_iteration = final_iteration

self.missing_names[-1] = set()

with self.file_context(file_node, options, active_type):

if isinstance(node, MypyFile):

self.refresh_top_level(node)

else:

self.recurse_into_functions = True

self.accept(node)

del self.patches

def ad_hoc_error(self, msg: str) -> None:

n = TempNode(AnyType(TypeOfAny.special_form))

n.line = 1

n.column = 0

n.end_line = 1

n.end_column = 0

self.fail(msg, n)

def refresh_top_level(self, file_node: MypyFile) -> None:

"""Reanalyze a stale module top-level in fine-grained incremental mode."""

if self.options.allow_redefinition and not self.options.local_partial_types:

self.ad_hoc_error(

"--local-partial-types must be enabled if using --allow-redefinition"

)

if self.options.allow_redefinition and self.options.allow_redefinition_old:

self.ad_hoc_error(

"--allow-redefinition-old and --allow-redefinition should not be used together"

)

if not self.options.local_partial_types and self.options.num_workers > 0:

self.ad_hoc_error("--local-partial-types must be enabled in parallel mode")

self.recurse_into_functions = False

self.add_implicit_module_attrs(file_node)

for d in file_node.defs:

self.accept(d)

if file_node.fullname == "typing":

self.add_builtin_aliases(file_node)

if file_node.fullname == "typing_extensions":

self.add_typing_extension_aliases(file_node)

self.adjust_public_exports()

self.all_exports = []

def add_implicit_module_attrs(self, file_node: MypyFile) -> None:

"""Manually add implicit definitions of module '__name__' etc."""

str_type: Type | None = self.named_type_or_none("builtins.str")

if str_type is None:

str_type = UnboundType("builtins.str")

inst: Type | None

for name, t in implicit_module_attrs.items():

if name == "__doc__":

typ: Type = str_type

elif name == "__path__":

if not file_node.is_package_init_file():

continue

# Need to construct the type ourselves, to avoid issues with __builtins__.list

# not being subscriptable or typing.List not getting bound

inst = self.named_type_or_none("builtins.list", [str_type])

if inst is None:

assert not self.final_iteration, "Cannot find builtins.list to add __path__"

self.defer()

return

typ = inst

elif name == "__annotations__":

inst = self.named_type_or_none(

"builtins.dict", [str_type, AnyType(TypeOfAny.special_form)]

)

if inst is None:

assert (

not self.final_iteration

), "Cannot find builtins.dict to add __annotations__"

self.defer()

return

typ = inst

elif name == "__spec__":

if self.options.use_builtins_fixtures:

inst = self.named_type_or_none("builtins.object")

else:

inst = self.named_type_or_none("importlib.machinery.ModuleSpec")

if inst is None:

if (

self.final_iteration

or self.options.clone_for_module("importlib.machinery").follow_imports

== "skip"

):

# If we are not allowed to resolve imports from `importlib.machinery`,

# ModuleSpec will not be available at any iteration.

# Use the fallback earlier.

# (see https://github.com/python/mypy/issues/18237)

inst = self.named_type_or_none("builtins.object")

assert inst is not None, "Cannot find builtins.object"

else:

self.defer()

return

if file_node.name == "__main__":

# https://docs.python.org/3/reference/import.html#main-spec

inst = UnionType.make_union([inst, NoneType()])

typ = inst

else:

assert t is not None, f"type should be specified for {name}"

typ = UnboundType(t)

existing = file_node.names.get(name)

if existing is not None and not isinstance(existing.node, PlaceholderNode):

# Already exists.

continue

an_type = self.anal_type(typ)

if an_type:

var = Var(name, an_type)

var._fullname = self.qualified_name(name)

var.is_ready = True

self.add_symbol(name, var, dummy_context())

else:

self.add_symbol(

name,

PlaceholderNode(self.qualified_name(name), file_node, -1),

dummy_context(),

)

def add_builtin_aliases(self, tree: MypyFile) -> None:

"""Add builtin type aliases to typing module.

For historical reasons, the aliases like `List = list` are not defined

in typeshed stubs for typing module. Instead we need to manually add the

corresponding nodes on the fly. We explicitly mark these aliases as normalized,

so that a user can write `typing.List[int]`.

"""

assert tree.fullname == "typing"

for alias, target_name in type_aliases.items():

if (

alias in type_aliases_source_versions

and type_aliases_source_versions[alias] > self.options.python_version

):

# This alias is not available on this Python version.

continue

name = alias.split(".")[-1]

if name in tree.names and not isinstance(tree.names[name].node, PlaceholderNode):

continue

self.create_alias(tree, target_name, alias, name)

def add_typing_extension_aliases(self, tree: MypyFile) -> None:

"""Typing extensions module does contain some type aliases.

We need to analyze them as such, because in typeshed

they are just defined as `_Alias()` call.

Which is not supported natively.

"""

assert tree.fullname == "typing_extensions"

for alias, target_name in typing_extensions_aliases.items():

name = alias.split(".")[-1]

if name in tree.names and isinstance(tree.names[name].node, TypeAlias):

continue # Do not reset TypeAliases on the second pass.

# We need to remove any node that is there at the moment. It is invalid.

tree.names.pop(name, None)

# Now, create a new alias.

self.create_alias(tree, target_name, alias, name)

def create_alias(self, tree: MypyFile, target_name: str, alias: str, name: str) -> None:

tag = self.track_incomplete_refs()

n = self.lookup_fully_qualified_or_none(target_name)

if n:

if isinstance(n.node, PlaceholderNode):

self.mark_incomplete(name, tree)

else:

# Found built-in class target. Create alias.

target = self.named_type_or_none(target_name, [])

assert target is not None

# Transform List to List[Any], etc.

fix_instance(

target, self.fail, self.note, disallow_any=False, options=self.options

)

alias_node = TypeAlias(

target,

alias,

tree.fullname,

line=-1,

column=-1, # there is no context

no_args=True,

normalized=True,

)

self.add_symbol(name, alias_node, tree)

elif self.found_incomplete_ref(tag):

# Built-in class target may not ready yet -- defer.

self.mark_incomplete(name, tree)

else:

# Test fixtures may be missing some builtin classes, which is okay.

# Kill the placeholder if there is one.

if name in tree.names:

assert isinstance(tree.names[name].node, PlaceholderNode)

del tree.names[name]

def adjust_public_exports(self) -> None:

"""Adjust the module visibility of globals due to __all__."""

if "__all__" in self.globals:

for name, g in self.globals.items():

# Being included in __all__ explicitly exports and makes public.

if name in self.all_exports:

g.module_public = True

g.module_hidden = False

# But when __all__ is defined, and a symbol is not included in it,

# it cannot be public.

else:

g.module_public = False

@contextmanager

def file_context(

self, file_node: MypyFile, options: Options, active_type: TypeInfo | None = None

) -> Iterator[None]:

"""Configure analyzer for analyzing targets within a file/class.

Args:

file_node: target file

options: options specific to the file

active_type: must be the surrounding class to analyze method targets

"""

scope = self.scope

self.options = options

self.errors.set_file(file_node.path, file_node.fullname, scope=scope, options=options)

self.cur_mod_node = file_node

self.cur_mod_id = file_node.fullname

with scope.module_scope(self.cur_mod_id):

self._is_stub_file = file_node.path.lower().endswith(".pyi")

self._is_typeshed_stub_file = file_node.is_typeshed_file(options)

self.globals = file_node.names

self.tvar_scope = TypeVarLikeScope()

self.named_tuple_analyzer = NamedTupleAnalyzer(options, self, self.msg)

self.typed_dict_analyzer = TypedDictAnalyzer(options, self, self.msg)

self.enum_call_analyzer = EnumCallAnalyzer(options, self)

self.newtype_analyzer = NewTypeAnalyzer(options, self, self.msg)

# Counter that keeps track of references to undefined things potentially caused by

# incomplete namespaces.

self.num_incomplete_refs = 0

if active_type:

enclosing_fullname = active_type.fullname.rsplit(".", 1)[0]

if "." in enclosing_fullname:

enclosing_node = self.lookup_fully_qualified_or_none(enclosing_fullname)

if enclosing_node and isinstance(enclosing_node.node, TypeInfo):

self._type = enclosing_node.node

self.push_type_args(active_type.defn.type_args, active_type.defn)

self.incomplete_type_stack.append(False)

scope.enter_class(active_type)

self.enter_class(active_type.defn.info)

for tvar in active_type.defn.type_vars:

self.tvar_scope.bind_existing(tvar)

yield

if active_type:

scope.leave_class()

self.leave_class()

self._type = None

self.incomplete_type_stack.pop()

self.pop_type_args(active_type.defn.type_args)

del self.options

#

# Functions

#

def visit_func_def(self, defn: FuncDef) -> None:

self.statement = defn

# Visit default values because they may contain assignment expressions.

for arg in defn.arguments:

if arg.initializer:

arg.initializer.accept(self)

defn.is_conditional = self.block_depth[-1] > 0

# Set full names even for those definitions that aren't added

# to a symbol table. For example, for overload items.

defn._fullname = self.qualified_name(defn.name)

# We don't add module top-level functions to symbol tables

# when we analyze their bodies in the second phase on analysis,

# since they were added in the first phase. Nested functions

# get always added, since they aren't separate targets.

if not self.recurse_into_functions or len(self.function_stack) > 0:

if not defn.is_decorated and not defn.is_overload:

self.add_function_to_symbol_table(defn)

if not self.recurse_into_functions and not defn.def_or_infer_vars:

return