/// No live path contains a binding.

Unbound,

/// Some live paths contain a binding and others leave the symbol unbound.

PossiblyBound,

/// Every live path contains a binding.

Bound,

fn bindings_id(self) -> InternedBindingsId {

self.0

}

fn declarations_id(self) -> InternedDeclarationsId {

self.1

}

interned_bindings: RetainedBindingsBuilder,

interned_ids_by_bindings: hashbrown::HashTable<InternedBindingsId>,

interned_declarations: RetainedDeclarationsBuilder,

interned_ids_by_declarations: FxHashMap<Declarations, InternedDeclarationsId>,

// Undeclared states are common and can be interned by their dense constraint IDs.

undeclared_declarations_by_constraint:

IndexVec<ScopedReachabilityConstraintId, Option<InternedDeclarationsId>>,

// These values are extremely common, so avoid repeatedly hashing their small vectors.

always_unbound_bindings: Option<InternedBindingsId>,

always_undeclared_declarations: Option<InternedDeclarationsId>,

fn with_capacity(bindings: usize, declaration_map: usize, declarations: usize) -> Self {

Self {

interned_bindings: RetainedBindingsBuilder::with_capacity(bindings),

interned_ids_by_bindings: hashbrown::HashTable::with_capacity(bindings),

interned_declarations: RetainedDeclarationsBuilder::with_capacity(declarations),

interned_ids_by_declarations: FxHashMap::with_capacity_and_hasher(

declaration_map,

FxBuildHasher,

),

undeclared_declarations_by_constraint: IndexVec::new(),

always_unbound_bindings: None,

always_undeclared_declarations: None,

}

}

fn intern_bindings(&mut self, bindings: &Bindings) -> InternedBindingsId {

if bindings.is_always_unbound() {

if let Some(interned_id) = self.always_unbound_bindings {

return interned_id;

}

let interned_id = self.interned_bindings.push(bindings);

self.always_unbound_bindings = Some(interned_id);

return interned_id;

}

// The retained representation discards the unbound narrowing constraint, so it isn't

// part of the interned identity.

let hash = Self::hash_bindings(bindings.as_slice());

let interned_bindings = &mut self.interned_bindings;

let entry = self.interned_ids_by_bindings.entry(

hash,

|id| interned_bindings.get(*id) == bindings.as_slice(),

|id| Self::hash_bindings(interned_bindings.get(*id)),

);

match entry {

hashbrown::hash_table::Entry::Occupied(entry) => *entry.get(),

hashbrown::hash_table::Entry::Vacant(entry) => {

let interned_id = interned_bindings.push(bindings);

entry.insert(interned_id);

interned_id

}

}

}

fn hash_bindings(live_bindings: &[LiveBinding]) -> u64 {

let mut hasher = FxHasher::default();

live_bindings.hash(&mut hasher);

hasher.finish()

}

fn intern_declarations(&mut self, declarations: Declarations) -> InternedDeclarationsId {

if declarations.is_always_undeclared() {

if let Some(interned_id) = self.always_undeclared_declarations {

return interned_id;

}

let interned_id = self.interned_declarations.push(&declarations);

self.always_undeclared_declarations = Some(interned_id);

return interned_id;

}

if let Some(reachability_constraint) = declarations.undeclared_reachability_constraint()

&& !reachability_constraint.is_terminal()

{

let index = reachability_constraint.index();

let len = self.undeclared_declarations_by_constraint.len();

if index >= len {

self.undeclared_declarations_by_constraint

.resize(index + 1, None);

} else if let Some(interned_id) =

self.undeclared_declarations_by_constraint[reachability_constraint]

{

return interned_id;

}

let interned_id = self.interned_declarations.push(&declarations);

self.undeclared_declarations_by_constraint[reachability_constraint] = Some(interned_id);

return interned_id;

}

match self.interned_ids_by_declarations.entry(declarations) {

Entry::Occupied(entry) => *entry.get(),

Entry::Vacant(entry) => {

let interned_id = self.interned_declarations.push(entry.key());

entry.insert(interned_id);

interned_id

}

}

}

fn intern_place_state(

&mut self,

bindings: &Bindings,

declarations: Declarations,

) -> InternedPlaceStateId {

InternedPlaceStateId(

self.intern_bindings(bindings),

self.intern_declarations(declarations),

)

}

fn retain_place_state(

&mut self,

bindings: &Bindings,

declarations: Declarations,

) -> InternedPlaceStateId {

// Other retained declarations rarely repeat. Keep the compact IDs without hashing every

// declaration vector to find the occasional duplicate.

let declarations_id = if declarations.undeclared_reachability_constraint().is_some() {

self.intern_declarations(declarations)

} else {

self.interned_declarations.push(&declarations)

};

InternedPlaceStateId(self.intern_bindings(bindings), declarations_id)

}

fn with_capacity(bindings: usize) -> Self {

Self {

ends: IndexVec::with_capacity(bindings),

live_bindings: Vec::with_capacity(bindings),

}

}

fn push(&mut self, bindings: &Bindings) -> InternedBindingsId {

// Definition IDs are also 32-bit and a single scope cannot practically approach this

// limit. Keeping one cumulative end offset per state halves the retained range metadata.

self.live_bindings.extend_from_slice(bindings.as_slice());

let end = u32::try_from(self.live_bindings.len())

.expect("Expected live-bindings length to fit into a u32");

self.ends.push(end)

}

fn get(&self, index: InternedBindingsId) -> &[LiveBinding] {

let end = self.ends[index];

let start = if index.index() == 0 {

0

} else {

self.ends[InternedBindingsId::new(index.index() - 1)]

};

&self.live_bindings[start as usize..end as usize]

}

fn finish(

self,

narrowing_constraints: &mut NarrowingConstraintsBuilder,

reachability_constraints: &mut ReachabilityConstraintsBuilder,

) -> RetainedBindings {

for binding in &self.live_bindings {

reachability_constraints.mark_used(binding.reachability_constraint());

narrowing_constraints.mark_used(binding.narrowing_constraint());

}

RetainedBindings {

ends: self.ends.into(),

live_bindings: self.live_bindings.into_boxed_slice(),

}

}

type Output = [LiveBinding];

fn index(&self, index: InternedBindingsId) -> &Self::Output {

let end = self.ends[index];

let start = if index.index() == 0 {

0

} else {

self.ends[InternedBindingsId::new(index.index() - 1)]

};

&self.live_bindings[start as usize..end as usize]

}

/// The exclusive end of each state in `live_declarations`; its start is the previous end.

ends: FrozenIndexVec<InternedDeclarationsId, u32>,

live_declarations: Box<[LiveDeclaration]>,

fn with_capacity(declarations: usize) -> Self {

Self {

ends: IndexVec::with_capacity(declarations),

live_declarations: Vec::with_capacity(declarations),

}

}

fn push(&mut self, declarations: &Declarations) -> InternedDeclarationsId {

self.live_declarations.extend(declarations.iter().cloned());

let end = u32::try_from(self.live_declarations.len())

.expect("Expected live-declarations length to fit into a u32");

self.ends.push(end)

}

fn finish(

self,

reachability_constraints: &mut ReachabilityConstraintsBuilder,

) -> RetainedDeclarations {

for declaration in &self.live_declarations {

reachability_constraints.mark_used(declaration.reachability_constraint);

}

RetainedDeclarations {

ends: self.ends.into(),

live_declarations: self.live_declarations.into_boxed_slice(),

}

}

type Output = [LiveDeclaration];

fn index(&self, index: InternedDeclarationsId) -> &Self::Output {

let end = self.ends[index];

let start = if index.index() == 0 {

0

} else {

self.ends[InternedDeclarationsId::new(index.index() - 1)]

};

&self.live_declarations[start as usize..end as usize]

}

predicates: Predicates<'db>,

predicate_narrowing_targets: PredicateNarrowingTargets,

reachability_constraints: ReachabilityConstraints,

narrowing_constraints: NarrowingConstraints,

fn from_entries(mut entries: Vec<(ScopedPredicateId, ScopedPlaceId)>) -> Self {

entries.sort_unstable_by_key(|&(predicate, place)| (place, predicate));

entries.dedup();

Self(entries.into_boxed_slice())

}

/// Returns whether `predicate` may narrow `place`.

pub fn contains(&self, predicate: ScopedPredicateId, place: ScopedPlaceId) -> bool {

self.0

.binary_search_by_key(&(place, predicate), |&(predicate, place)| {

(place, predicate)

})

.is_ok()

}

/// Returns whether any predicate may narrow `place`.

pub fn contains_place(&self, place: ScopedPlaceId) -> bool {

self.0

.binary_search_by_key(&place, |&(_, target)| target)

.is_ok()

}

/// [`Bindings`] reaching a [`ScopedUseId`].

bindings_by_use: FrozenIndexVec<ScopedUseId, InternedBindingsId>,

/// [`Bindings`] for each member reaching a [`ScopedUseId`].

///

/// This is only used for kwargs expressions, whose corresponding `bindings_by_use` entry

/// is empty.

multi_bindings_by_use: MultiBindingsByUse,

/// Retained [`PlaceState`] values for each member.

member_states: FrozenIndexVec<ScopedMemberId, RetainedPlaceStates<InternedPlaceStateId>>,

/// Snapshots of bindings used to resolve references from nested scopes.

enclosing_snapshots: FrozenIndexVec<ScopedEnclosingSnapshotId, InternedEnclosingSnapshotId>,

/// Completed loop headers in this scope.

loop_headers: FrozenIndexVec<LoopHeaderId, LoopHeader>,

/// The early declaration of a combined definition whose binding is recorded separately.

/// It participates in declaration lookup, but not in binding-usage analysis.

DeclarationPart(Definition<'db>),

/// A binding or standalone declaration with no recorded use.

Unused(Definition<'db>),

Used(Definition<'db>),

Undefined,

Deleted,

fn state(self) -> DefinitionState<'db> {

match self {

Self::DeclarationPart(definition)

| Self::Unused(definition)

| Self::Used(definition) => DefinitionState::Defined(definition),

Self::Undefined => DefinitionState::Undefined,

Self::Deleted => DefinitionState::Deleted,

}

}

fn new(states: IndexVec<ScopedDefinitionId, DefinitionEntry<'db>>) -> Self {

let mut states = states.into_iter();

let unbound_state = states.next();

debug_assert_eq!(unbound_state, Some(DefinitionEntry::Undefined));

Self {

states: states.collect(),

}

}

#[inline]

fn get(&self, id: ScopedDefinitionId) -> DefinitionEntry<'db> {

let index = id.index();

if index == 0 {

DefinitionEntry::Undefined

} else {

self.states[index - 1]

}

}

fn iter_enumerated(

&self,

) -> impl Iterator<Item = (ScopedDefinitionId, DefinitionEntry<'db>)> + '_ {

self.states

.iter()

.copied()

.enumerate()

.map(|(index, entry)| (ScopedDefinitionId::new(index + 1), entry))

}

/// Definition states in this scope, plus an implicit "unbound"/"undeclared" definition at

/// index zero.

all_definitions: RetainedDefinitions<'db>,

/// Constraint lookup tables, absent when all retained constraints are built-in terminal

/// values that require no table lookup.

constraint_tables: Option<Box<ConstraintTables<'db>>>,

/// Interned [`Bindings`] values.

interned_bindings: RetainedBindings,

/// Interned [`Declarations`] values.

interned_declarations: RetainedDeclarations,

/// Tracks the reachability constraint for statements and certain sub-expressions

/// (e.g. ternary branches, boolean operator operands), keyed by their text range.

/// Used to suppress diagnostics in unreachable code.

range_reachability: Box<[(TextRange, RangeInfo)]>,

/// If the definition is a binding (only) -- `x = 1` for example -- then we need

/// [`Declarations`] to know whether this binding is permitted by the live declarations.

///

/// If the definition is both a declaration and a binding -- `x: int = 1` for example -- then

/// we don't actually need anything here, all we'll need to validate is that our own RHS is a

/// valid assignment to our own annotation.

///

/// If the definition is a declaration (only) -- `x: int` for example -- then we need

/// [`Bindings`] to know whether this declaration is consistent with the previously

/// inferred type.

///

/// If we see a binding to a `Final`-qualified symbol, we also need the bindings to find

/// previous bindings to that symbol. If there are any, the assignment is invalid.

///

/// Entries whose prior state is the start-of-scope default (always unbound and, if present,

/// always undeclared) are omitted. Lookups use [`ALWAYS_UNBOUND_BINDINGS`] and

/// [`ALWAYS_UNDECLARED_DECLARATIONS`], which are initialized lazily and shared by every map.

definitions_by_definition: FrozenMap<

Definition<'db>,

DefinitionsAtDefinition<InternedBindingsId, InternedDeclarationsId>,

>,

/// Retained [`PlaceState`] values for each symbol.

symbol_states: FrozenIndexVec<ScopedSymbolId, RetainedPlaceStates<InternedPlaceStateId>>,

/// Collection fields omitted when they would all be empty.

extra: Option<Box<UseDefMapExtra>>,

/// Whether or not the end of the scope is reachable.

///

/// This is used to check if the function can implicitly return `None`.

/// For example:

/// ```py

/// def f(cond: bool) -> int | None:

/// if cond:

/// return 1

///

/// def g() -> int:

/// if True:

/// return 1

/// ```

///

/// Function `f` may implicitly return `None`, but `g` cannot.

///

/// This is used by `can_implicitly_return_none` in the `ty_python_semantic` crate.

end_of_scope_reachability: ScopedReachabilityConstraintId,

fn default() -> Self {

Self {

reachability: ScopedReachabilityConstraintId::ALWAYS_TRUE,

in_type_checking_block: false,

}

}

fn from_map(map: FxHashMap<ScopedUseId, Vec<Bindings>>) -> Self {

let mut entries = map

.into_iter()

.map(|(use_id, bindings)| (use_id, bindings.into_boxed_slice()))

.collect::<Vec<_>>();

entries.sort_unstable_by_key(|(use_id, _)| *use_id);

Self(entries.into_iter().collect())

}

fn get(&self, use_id: ScopedUseId) -> Option<&[Bindings]> {

self.0

.binary_search_by_key(&use_id, |(candidate, _)| *candidate)

.ok()

.map(|index| self.0[index].1.as_ref())

}

fn constraint_tables(&self) -> &ConstraintTables<'db> {

self.constraint_tables

.as_deref()

.map_or(&EMPTY_CONSTRAINT_TABLES, |tables| tables)

}

fn extra(&self) -> &UseDefMapExtra {

self.extra

.as_deref()

.expect("extra use-def data should have been retained")

}

pub fn loop_header(&self, id: LoopHeaderId) -> &LoopHeader {

&self.extra().loop_headers[id]

}

pub fn reachability_constraints(&self) -> &ReachabilityConstraints {

&self.constraint_tables().reachability_constraints

}

pub fn predicates(&self) -> &Predicates<'db> {

&self.constraint_tables().predicates

}

pub fn range_reachability(

&self,

) -> impl Iterator<Item = (TextRange, ScopedReachabilityConstraintId)> + '_ {

self.range_reachability

.iter()

.map(|&(range, RangeInfo { reachability, .. })| (range, reachability))

}

pub fn end_of_scope_reachability(&self) -> ScopedReachabilityConstraintId {

self.end_of_scope_reachability

}

/// Definitions relevant to usage analysis, including standalone declarations.

///

/// The early declaration part of a combined definition is omitted: its later binding entry

/// carries the usage information for that definition.

pub fn definitions_with_usage(

&self,

) -> impl Iterator<Item = (ScopedDefinitionId, Definition<'db>, bool)> + '_ {

self.all_definitions

.iter_enumerated()

.filter_map(|(id, entry)| match entry {

DefinitionEntry::Unused(definition) => Some((id, definition, false)),

DefinitionEntry::Used(definition) => Some((id, definition, true)),

DefinitionEntry::DeclarationPart(_)

| DefinitionEntry::Undefined

| DefinitionEntry::Deleted => None,

})

}

pub fn bindings_at_use(&self, use_id: ScopedUseId) -> BindingWithConstraintsIterator<'_, 'db> {

let bindings_id = self.extra().bindings_by_use[use_id];

self.bindings_iterator(

&self.interned_bindings[bindings_id],

BoundnessAnalysis::BasedOnUnboundVisibility,

)

}

pub fn multi_bindings_at_use(

&self,

use_id: ScopedUseId,

) -> impl Iterator<Item = BindingWithConstraintsIterator<'_, 'db>> {

self.extra

.as_deref()

.and_then(|extra| extra.multi_bindings_by_use.get(use_id))

.map(|member_bindings| {

member_bindings.iter().map(|bindings| {

self.bindings_iterator(

bindings.as_slice(),

BoundnessAnalysis::BasedOnUnboundVisibility,

)

})

})

.into_iter()

.flatten()

}

pub fn applicable_constraints(

&self,

constraint_key: ConstraintKey,

enclosing_scope: FileScopeId,

expr: PlaceExprRef,

index: &'db SemanticIndex,

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

match constraint_key {

ConstraintKey::NarrowingConstraint(constraint) => {

ApplicableConstraints::UnboundBinding(NarrowingEvaluator {

constraint,

constraint_tables: self.constraint_tables(),

})

}

ConstraintKey::NestedScope(nested_scope) => {

let EnclosingSnapshotResult::FoundBindings(bindings) =

index.enclosing_snapshot(enclosing_scope, expr, nested_scope)

else {

unreachable!(

"The result of `SemanticIndex::eager_snapshot` must be `FoundBindings`"

)

};

ApplicableConstraints::ConstrainedBindings(bindings)

}

ConstraintKey::UseId(use_id) => {

ApplicableConstraints::ConstrainedBindings(self.bindings_at_use(use_id))

}

}

}

pub fn definition(&self, id: ScopedDefinitionId) -> DefinitionState<'db> {

self.all_definitions.get(id).state()

}