let _span = tracing::trace_span!("semantic_index", ?file).entered();

let module = parsed_module(db, file.python_file(db)).load(db);

SemanticIndexBuilder::new(db, file, &module).build()

let program_file = scope.program_file(db);

let _span = tracing::trace_span!("place_table", scope=?scope.as_id(), ?program_file).entered();

let index = semantic_index(db, program_file);

Arc::clone(&index.place_tables[scope.file_scope_id(db)])

let program_file = scope.program_file(db);

let _span = tracing::trace_span!("use_def_map", scope=?scope.as_id(), ?program_file).entered();

let index = semantic_index(db, program_file);

Arc::clone(&index.use_def_maps[scope.file_scope_id(db)])

fn new() -> Self {

Self {

bindings: FxHashMap::default(),

}

}

fn add_binding(&mut self, place: ScopedPlaceId, binding: LiveBinding) {

self.bindings.entry(place).or_default().push(binding);

}

pub fn bindings_for_place(

&self,

place: ScopedPlaceId,

) -> impl Iterator<Item = LiveBinding> + '_ {

self.bindings

.get(&place)

.map(|v: &SmallVec<[LiveBinding; 1]>| v.iter().copied())

.into_iter()

.flatten()

}

db: &'db dyn Db,

class_body_scope: ScopeId<'db>,

) -> impl Iterator<Item = FileScopeId> + 'db {

let index = semantic_index(db, class_body_scope.program_file(db));

let class_scope_id = class_body_scope.file_scope_id(db);

ChildrenIter::new(&index.scopes, class_scope_id)

.filter_map(move |(child_scope_id, scope)| {

let (function_scope_id, function_scope) =

if scope.node().scope_kind() == ScopeKind::TypeParams {

// This could be a generic method with a type-params scope.

// Go one level deeper to find the function scope. The first

// descendant is the (potential) function scope.

let function_scope_id = scope.descendants().start;

(function_scope_id, index.scope(function_scope_id))

} else {

(child_scope_id, scope)

};

function_scope.node().as_function()?;

Some(function_scope_id)

})

.flat_map(move |func_id| {

// Add any descendent scope that is eager and have eager scopes between the scope

// and the method scope. Since attributes can be defined in this scope.

let nested = index.descendent_scopes(func_id).filter_map(move |(id, s)| {

let is_eager = s.kind().is_eager();

let parents_are_eager = {

let mut all_parents_eager = true;

let mut current = Some(id);

while let Some(scope_id) = current {

if scope_id == func_id {

break;

}

let scope = index.scope(scope_id);

if !scope.is_eager() {

all_parents_eager = false;

break;

}

current = scope.parent();

}

all_parents_eager

};

(parents_are_eager && is_eager).then_some(id)

});

once(func_id).chain(nested)

})

let _span = tracing::trace_span!("global_scope", ?file).entered();

FileScopeId::global().to_scope_id(db, file)

FoundConstraint(ScopedNarrowingConstraint),

FoundBindings(BindingWithConstraintsIterator<'map, 'db>),

NotFound,

NoLongerInEagerContext,

fn from_map(definitions_by_node: FxHashMap<DefinitionNodeKey, Definitions<'db>>) -> Self {

let single_count = definitions_by_node

.values()

.filter(|definitions| definitions.len() == 1)

.count();

let mut single = Vec::with_capacity(single_count);

let mut non_single = Vec::with_capacity(definitions_by_node.len() - single_count);

#[expect(

for (key, definitions) in definitions_by_node {

if definitions.len() == 1 {

single.push((key, definitions[0]));

} else {

non_single.push((key, definitions.into_boxed_slice()));

}

}

Self {

single: FrozenMap::from_entries(single),

non_single: FrozenMap::from_entries(non_single),

}

}

fn get(&self, key: DefinitionNodeKey) -> Option<&[Definition<'db>]> {

self.single

.get(&key)

.map(std::slice::from_ref)

.or_else(|| self.non_single.get(&key).map(AsRef::as_ref))

}

/// List of all place tables in this file, indexed by scope.

place_tables: FrozenIndexVec<FileScopeId, Arc<PlaceTable>>,

/// List of all scopes in this file.

scopes: FrozenIndexVec<FileScopeId, Scope>,

/// Map expressions to their corresponding scope.

scopes_by_expression: ExpressionsScopeMap,

/// Map from a node creating a definition to its definition.

definitions_by_node: DefinitionsByNode<'db>,

/// Map from a standalone expression to its [`Expression`] ingredient.

expressions_by_node: FxHashMap<ExpressionNodeKey, Expression<'db>>,

/// Map from an unpacking target to its [`unpack::Unpack`] ingredient.

unpacks_by_target: FrozenMap<ExpressionNodeKey, unpack::Unpack<'db>>,

/// Map from a standalone statement to its [`Statement`] ingredient.

statements_by_node: FxHashMap<StatementNodeKey, Statement<'db>>,

/// Map from nodes that create a scope to the scope they create.

scopes_by_node: FxHashMap<NodeWithScopeKey, FileScopeId>,

/// Map from a lambda expression to its containing statement.

enclosing_lambda_statements: FrozenMap<ExpressionNodeKey, Statement<'db>>,

// Map from a constraining use of a collection initializer to its definition.

collections_by_use: FrozenMap<ExpressionNodeKey, Definition<'db>>,

// Map from a collection initializer definition to statements containing a constraining use.

uses_by_collection: FrozenMap<Definition<'db>, Box<[(Statement<'db>, ExpressionNodeKey)]>>,

/// Map from the file-local [`FileScopeId`] to the salsa-ingredient [`ScopeId`].

scope_ids_by_scope: FrozenIndexVec<FileScopeId, ScopeId<'db>>,

/// Use-def map for each scope in this file.

use_def_maps: FrozenIndexVec<FileScopeId, Arc<UseDefMap<'db>>>,

/// Lookup table to map between node ids and ast nodes.

///

/// Note: We should not depend on this map when analysing other files or

/// changing a file invalidates all dependents.

ast_ids: AstIds,

/// The set of modules that are imported anywhere within this file.

imported_modules: FrozenSet<ModuleName>,

/// Flags about the global scope (code usage impacting inference)

has_future_annotations: bool,

/// Map of all of the enclosing snapshots that appear in this file.

enclosing_snapshots: FrozenMap<EnclosingSnapshotKey, ScopedEnclosingSnapshotId>,

/// List of all semantic syntax errors in this file.

semantic_syntax_errors: Vec<SemanticSyntaxError>,

/// Set of all generator functions in this file.

generator_functions: FrozenSet<FileScopeId>,

/// Set of all asynchronous comprehensions in this file.

async_comprehensions: FrozenSet<FileScopeId>,

/// Node indices of syntactic annotation roots, sorted in source order. Annotations cannot

/// contain other syntactic annotations, so their ranges do not overlap. Storing only indices

/// avoids duplicating ranges and scopes already available from the AST and expression scope map.

annotations: Box<[NodeIndex]>,

/// Narrowing alias metadata for predicate leaf names.

/// When a predicate references an alias variable (e.g., `is_none` from `is_none = x is None`),

/// the alias Name node is mapped to its aliased expression for constraint-generation time.

narrowing_alias_predicates: FrozenMap<ExpressionNodeKey, NarrowingAliasPredicate<'db>>,

/// Returns the recorded use of an expression, if it loads a tracked place.

pub fn try_expression_use_id(

&self,

expression: ast::ExprRef<'_>,

) -> Option<ast_ids::ScopedUseId> {

self.ast_ids.try_use_id(expression)

}

/// Returns the place table for a specific scope.

///

/// Use the Salsa cached [`place_table()`] query if you only need the

/// place table for a single scope.

#[track_caller]

pub fn place_table(&self, scope_id: FileScopeId) -> &PlaceTable {

&self.place_tables[scope_id]

}

/// Returns alias metadata for an alias Name node in a predicate, if one exists.

pub fn narrowing_alias_predicate(

&self,

key: impl Into<ExpressionNodeKey>,

) -> Option<&NarrowingAliasPredicate<'db>> {

self.narrowing_alias_predicates.get(&key.into())

}

/// Returns the use-def map for a specific scope.

///

/// Use the Salsa cached [`use_def_map()`] query if you only need the

/// use-def map for a single scope.

#[track_caller]

pub fn use_def_map(&self, scope_id: FileScopeId) -> &UseDefMap<'db> {

&self.use_def_maps[scope_id]

}

/// Returns the set of modules that are imported anywhere in this file.

///

/// This set only considers `import` statements, not `from...import` statements.

/// See `ModuleLiteralType::available_submodule_attributes` for discussion

/// of why this analysis is intentionally limited.

pub fn imported_modules(&self) -> impl Iterator<Item = &ModuleName> {

self.imported_modules.iter()

}

#[track_caller]

fn ast_ids(&self) -> &AstIds {

&self.ast_ids

}

/// Returns the ID of the `expression`'s enclosing scope.

#[track_caller]

pub fn expression_scope_id<E>(&self, expression: &E) -> FileScopeId

where

E: HasTrackedScope,

{

self.try_expression_scope_id(expression)

.expect("Expression to be part of a scope if it is from the same module")

}

/// Returns the ID of the `expression`'s enclosing scope.

pub fn try_expression_scope_id<E>(&self, expression: &E) -> Option<FileScopeId>

where

E: HasTrackedScope,

{

self.scopes_by_expression.try_get(expression)

}

/// Returns the scope enclosing the syntactic annotation containing `expression`, if any.

///

/// `module` must correspond to the same file and revision as this index.

///

/// ```python

/// from typing import Annotated

///

/// def example(items: list[int]) -> None:

/// result: Annotated[int, (item for item in items)]

/// ```

///

/// The yielded `item` belongs to the generator's scope, and the iterable `items` belongs to

/// `example`'s scope. This method returns `example`'s scope for both, because both expressions

/// occur in the annotation on `result`.

pub fn annotation_parent_scope_id(

&self,

module: &ParsedModuleRef,

expression: &impl Ranged,

) -> Option<FileScopeId> {

let index = self

.annotations

.partition_point(|index| module.get_by_index(*index).start() <= expression.start())

.checked_sub(1)?;

let ast::AnyRootNodeRef::Expr(annotation) = module.get_by_index(self.annotations[index])

else {

return None;

};

if annotation.range().contains_range(expression.range()) {

self.try_expression_scope_id(annotation)

} else {

None

}

}

/// Returns the [`Scope`] of the `expression`'s enclosing scope.

#[allow(unused)]

#[track_caller]

pub fn expression_scope(&self, expression: &impl HasTrackedScope) -> &Scope {

&self.scopes[self.expression_scope_id(expression)]

}

/// Returns the [`Scope`] with the given id.

#[track_caller]

pub fn scope(&self, id: FileScopeId) -> &Scope {

&self.scopes[id]

}

pub fn scope_ids(&self) -> impl Iterator<Item = ScopeId<'db>> + '_ {

self.scope_ids_by_scope.iter().copied()

}

pub fn symbol_is_global_in_scope(&self, symbol: ScopedSymbolId, scope: FileScopeId) -> bool {

self.place_table(scope).symbol(symbol).is_global()

}

/// Returns `true` if the given symbol in the given scope resolves to the global scope, either

/// because:

///

/// 1. The given scope *is* the global scope.

/// 2. The symbol is explicitly declared `global` in the given scope.

/// 3. The symbol is a free variable in the given scope, and no enclosing function scope

/// defines it.

///

/// The third case requires walking ancestor scopes until we encounter either a binding or a

/// `nonlocal` declaration (those aren't allowed to resolve to the global scope, so we don't

/// need to chase them).

pub fn symbol_resolves_to_global_scope(

&self,

symbol: ScopedSymbolId,

scope: FileScopeId,

) -> bool {

let symbol = self.place_table(scope).symbol(symbol);

let name = symbol.name();

// Note that `visible_ancestor_scopes` includes the starting scope itself.

for (visible_scope_id, _) in self.visible_ancestor_scopes(scope) {

if visible_scope_id.is_global() {

// We return `true` here even if the global variable isn't actually defined. That

// case will be probably a diagnostic elsewhere.

return true;

}

let place_table = self.place_table(visible_scope_id);

let Some(visible_symbol_id) = place_table.symbol_id(name) else {

continue;

};

let visible_symbol = place_table.symbol(visible_symbol_id);

if visible_symbol.is_global() {

return true;

}

if visible_symbol.is_local() || visible_symbol.is_nonlocal() {

return false;

}

}

unreachable!("should return true at the global scope above");

}

/// Returns the id of the parent scope.

pub fn parent_scope_id(&self, scope_id: FileScopeId) -> Option<FileScopeId> {

let scope = self.scope(scope_id);

scope.parent()

}

/// Returns the parent scope of `scope_id`.

#[track_caller]

pub fn parent_scope(&self, scope_id: FileScopeId) -> Option<&Scope> {

Some(&self.scopes[self.parent_scope_id(scope_id)?])

}

/// Return the [`Definition`] of the class enclosing this method, given the

/// method's body scope, or `None` if it is not a method.

pub fn class_definition_of_method(

&self,

function_body_scope: FileScopeId,

) -> Option<Definition<'db>> {

let current_scope = self.scope(function_body_scope);

if current_scope.kind() != ScopeKind::Function {

return None;

}

let parent_scope_id = current_scope.parent()?;

let parent_scope = self.scope(parent_scope_id);

let class_scope = match parent_scope.kind() {

ScopeKind::Class => parent_scope,

ScopeKind::TypeParams => {

let class_scope_id = parent_scope.parent()?;

let potentially_class_scope = self.scope(class_scope_id);

match potentially_class_scope.kind() {

ScopeKind::Class => potentially_class_scope,

_ => return None,

}

}

_ => return None,

};

class_scope

.node()

.as_class()

.map(|node_ref| self.expect_single_definition(node_ref))

}

pub fn enclosing_lambda_statement(&self, lambda: ExpressionNodeKey) -> Option<Statement<'db>> {

self.enclosing_lambda_statements.get(&lambda).copied()

}

/// If this is a potentially constraining use of an unannotated collection initializer, returns

/// its definition.

pub fn unannotated_collection_initializer(

&self,

collection_use: &ast::Expr,

) -> Option<Definition<'db>> {

self.collections_by_use.get(&collection_use.into()).copied()

}

/// Returns all potentially constraining uses of the given unannotated collection initializer.

pub fn constraining_collection_uses(

&self,

collection_def: Definition<'db>,

) -> impl Iterator<Item = (Statement<'db>, ExpressionNodeKey)> {

self.uses_by_collection

.get(&collection_def)

.into_iter()

.flat_map(|uses| uses.iter().copied())

}

pub fn is_in_type_checking_block(&self, scope_id: FileScopeId, range: TextRange) -> bool {

self.ancestor_scopes(scope_id).any(|(scope_id, _)| {

self.use_def_map(scope_id)

.is_range_in_type_checking_block(range)

})

}

/// Return `true` if `expression` is an outermost "boolean test".

///

/// A boolean test is an expression that Python tests for truthiness, such as an `if`

/// condition or the operand of a `not` expression. ty's `redundant-condition` and

/// `redundant-condition-strict` rules can warn when such a test is always true or

/// always false. The rules try hard to avoid emitting duplicate diagnostics on the

/// same boolean test, however: in this case, a naive implementation would emit two

/// diagnostics on the `if` test, since there is both an `if` condition that is always

/// falsy and a `not` operand that is always truthy:

///

/// ```py

/// def func(): ...

///

/// if not func: # one diagnostic, or two?

/// pass

/// ```

///

/// This method returns `true` when passed the expression `not func` in the above

/// example, but `false` for `func`, which is part of a nested boolean test.

///

/// See `SemanticIndexBuilder::visit_boolean_test` for details on how we compute

/// and store the required data for answering this query during semantic indexing.

pub fn is_boolean_test_root(&self, expression: &ast::Expr) -> bool {

self.try_expression_scope_id(expression)

.is_some_and(|scope| {

self.use_def_map(scope)

.is_boolean_test_root(expression.node_index().load())

})

}

/// Returns an iterator over the descendent scopes of `scope`.

fn descendent_scopes(&self, scope: FileScopeId) -> DescendantsIter<'_> {

DescendantsIter::new(&self.scopes, scope)

}

/// Returns an iterator over the direct child scopes of `scope`.

pub fn child_scopes(&self, scope: FileScopeId) -> ChildrenIter<'_> {

ChildrenIter::new(&self.scopes, scope)

}

/// Returns an iterator over all ancestors of `scope`, starting with `scope` itself.

pub fn ancestor_scopes(&self, scope: FileScopeId) -> AncestorsIter<'_> {

AncestorsIter::new(&self.scopes, scope)

}

/// Returns an iterator over ancestors of `scope` that are visible for name resolution,

/// starting with `scope` itself. This follows Python's lexical scoping rules where

/// class scopes are skipped during name resolution (except for the starting scope

/// if it happens to be a class scope).

///

/// For example, in this code:

/// ```python

/// x = 1

/// class A:

/// x = 2

/// def method(self):

/// print(x) # Refers to global x=1, not class x=2

/// ```

/// The `method` function can see the global scope but not the class scope.

pub fn visible_ancestor_scopes(&self, scope: FileScopeId) -> VisibleAncestorsIter<'_> {

VisibleAncestorsIter::new(&self.scopes, scope)

}

/// Returns the [`definition::Definition`] salsa ingredient(s) for `definition_key`.

///

/// There will only ever be >1 `Definition` associated with a `definition_key`

/// if the definitions are created by a wildcard (`*`) import.

#[track_caller]

pub fn definitions(&self, definition_key: impl Into<DefinitionNodeKey>) -> &[Definition<'db>] {

self.definitions_by_node

.get(definition_key.into())

.expect("definition should be present in the semantic index")

}

/// Returns the [`definition::Definition`] salsa ingredient(s) for `definition_node`, if any.

pub fn try_definitions(

&self,

definition_node: ast::AnyNodeRef<'_>,

) -> Option<&[Definition<'db>]> {

let definition_key = DefinitionNodeKey::from_node_ref(definition_node);

self.definitions_by_node.get(definition_key)

}

/// Returns the [`definition::Definition`] salsa ingredient for `definition_key`.

///

/// ## Panics

///

/// If the number of definitions associated with the key is not exactly 1 and

/// the `debug_assertions` feature is enabled, this method will panic.

///

/// It is generally safe to use this method for any AST node that does not

/// correspond to a `*` (wildcard) import, since those are the only situations

/// that can result in multiple definitions being associated with a single AST

/// node.

#[track_caller]

pub fn expect_single_definition(

&self,

definition_key: impl Into<DefinitionNodeKey> + std::fmt::Debug + Copy,

) -> Definition<'db> {

let definitions = self.definitions(definition_key);

debug_assert_eq!(

definitions.len(),

1,

"Expected exactly one definition to be associated with AST node {definition_key:?} but found {}",

definitions.len()

);

definitions[0]

}

pub fn try_definition(

&self,

definition_key: impl Into<DefinitionNodeKey>,

) -> Option<Definition<'db>> {

self.definitions_by_node

.single

.get(&definition_key.into())

.copied()

}

/// Returns the [`Expression`] ingredient for an expression node.

/// Panics if we have no expression ingredient for that node. We can only call this method for

/// standalone-inferable expressions, which we call `add_standalone_expression` for in

/// `SemanticIndexBuilder`.

#[track_caller]

pub fn expression(&self, expression_key: impl Into<ExpressionNodeKey>) -> Expression<'db> {

self.expressions_by_node[&expression_key.into()]

}

pub fn try_expression(

&self,

expression_key: impl Into<ExpressionNodeKey>,

) -> Option<Expression<'db>> {

self.expressions_by_node

.get(&expression_key.into())

.copied()

}

/// Returns the [`unpack::Unpack`] ingredient for an unpacking target, if any.

pub fn try_unpack(&self, target: impl Into<ExpressionNodeKey>) -> Option<unpack::Unpack<'db>> {

self.unpacks_by_target.get(&target.into()).copied()

}

pub fn is_standalone_expression(&self, expression_key: impl Into<ExpressionNodeKey>) -> bool {

self.expressions_by_node

.contains_key(&expression_key.into())

}

pub fn try_statement(

&self,

statement_key: impl Into<StatementNodeKey>,

) -> Option<Statement<'db>> {

self.statements_by_node.get(&statement_key.into()).copied()

}

/// Returns the id of the scope that `node` creates.

/// This is different from [`definition::Definition::scope`] which

/// returns the scope in which that definition is defined in.

#[track_caller]

pub fn node_scope(&self, node: NodeWithScopeRef) -> FileScopeId {

self.scopes_by_node[&node.node_key()]

}

/// Returns the id of the scope that `node` creates, if it exists.

pub fn try_node_scope(&self, node: NodeWithScopeRef) -> Option<FileScopeId> {

self.scopes_by_node.get(&node.node_key()).copied()

}

/// Returns the id of the scope that the node identified by `key` creates.

///

/// This is useful when you have a [`NodeWithScopeKey`] constructed from an

/// [`AstNodeRef`](crate::ast_node_ref::AstNodeRef) and want to avoid loading

/// the parsed module just to look up the scope.

pub fn node_scope_by_key(&self, key: NodeWithScopeKey) -> FileScopeId {

self.scopes_by_node[&key]

}

/// Checks if there is an import of `__future__.annotations` in the global scope, which affects

/// the logic for type inference.

pub fn has_future_annotations(&self) -> bool {

self.has_future_annotations

}

/// Returns

/// * `NoLongerInEagerContext` if the nested scope is no longer in an eager context

/// (that is, not every scope that will be traversed is eager) and no lazy snapshots were found.

/// * an iterator of bindings for a particular nested scope reference if the bindings exist.

/// * a narrowing constraint if there are no bindings, but there is a narrowing constraint for an enclosing scope place.

/// * `NotFound` if the narrowing constraint / bindings do not exist in the nested scope.

pub fn enclosing_snapshot(

&self,

enclosing_scope: FileScopeId,

expr: PlaceExprRef,

nested_scope: FileScopeId,

) -> EnclosingSnapshotResult<'_, 'db> {

for (ancestor_scope_id, ancestor_scope) in self.ancestor_scopes(nested_scope) {

if ancestor_scope_id == enclosing_scope {

break;

}

if !ancestor_scope.is_eager() {

if let PlaceExprRef::Symbol(symbol) = expr

&& let Some(place_id) =

self.place_tables[enclosing_scope].symbol_id(symbol.name())

{

let key = EnclosingSnapshotKey {

enclosing_scope,

enclosing_place: place_id.into(),

nested_scope,

nested_laziness: ScopeLaziness::Lazy,

};

if let Some(id) = self.enclosing_snapshots.get(&key) {

return self.use_def_maps[enclosing_scope]

.enclosing_snapshot(*id, key.nested_laziness);

}

}

return EnclosingSnapshotResult::NoLongerInEagerContext;

}

}

let Some(place_id) = self.place_tables[enclosing_scope].place_id(expr) else {

return EnclosingSnapshotResult::NotFound;

};

let key = EnclosingSnapshotKey {

enclosing_scope,

enclosing_place: place_id,

nested_scope,

nested_laziness: ScopeLaziness::Eager,

};

let Some(id) = self.enclosing_snapshots.get(&key) else {

return EnclosingSnapshotResult::NotFound;

};

self.use_def_maps[enclosing_scope].enclosing_snapshot(*id, key.nested_laziness)

}

pub fn semantic_syntax_errors(&self) -> &[SemanticSyntaxError] {

&self.semantic_syntax_errors

}

fn new(scopes: &'a IndexSlice<FileScopeId, Scope>, start: FileScopeId) -> Self {

Self {

scopes,

next_id: Some(start),

}

}

type Item = (FileScopeId, &'a Scope);

fn next(&mut self) -> Option<Self::Item> {

let current_id = self.next_id?;

let current = &self.scopes[current_id];

self.next_id = current.parent();

Some((current_id, current))

}

inner: AncestorsIter<'a>,

starting_scope_kind: ScopeKind,

yielded_count: usize,

fn new(scopes: &'a IndexSlice<FileScopeId, Scope>, start: FileScopeId) -> Self {

let starting_scope = &scopes[start];

Self {

inner: AncestorsIter::new(scopes, start),

starting_scope_kind: starting_scope.kind(),

yielded_count: 0,

}

}

type Item = (FileScopeId, &'a Scope);

fn next(&mut self) -> Option<Self::Item> {

loop {

let (scope_id, scope) = self.inner.next()?;