/// The name of this symbol table. Often the name of the class or function.

pub name: String,

/// The type of symbol table

pub typ: CompilerScope,

/// The line number in the source code where this symboltable begins.

pub line_number: u32,

// Return True if the block is a nested class or function

pub is_nested: bool,

/// A set of symbols present on this scope level.

pub symbols: IndexMap<String, Symbol>,

/// A list of sub-scopes in the order as found in the

/// AST nodes.

pub sub_tables: Vec<SymbolTable>,

/// Cursor pointing to the next sub-table to consume during compilation.

pub next_sub_table: usize,

/// Variable names in definition order (parameters first, then locals)

pub varnames: Vec<String>,

/// Whether this class scope needs an implicit __class__ cell

pub needs_class_closure: bool,

/// Whether this class scope needs an implicit __classdict__ cell

pub needs_classdict: bool,

/// Whether this type param scope can see the parent class scope

pub can_see_class_scope: bool,

/// Whether this comprehension scope should be inlined (PEP 709)

/// True for list/set/dict comprehensions in non-generator expressions

pub comp_inlined: bool,

/// PEP 649: Reference to annotation scope for this block

/// Annotations are compiled as a separate `__annotate__` function

pub annotation_block: Option<Box<SymbolTable>>,

/// PEP 649: Whether this scope has conditional annotations

/// (annotations inside if/for/while/etc. blocks or at module level)

pub has_conditional_annotations: bool,

/// Whether `from __future__ import annotations` is active

pub future_annotations: bool,

/// Names of type parameters that should still be mangled in type param scopes.

/// When Some, only names in this set are mangled; other names are left unmangled.

/// Set on type param blocks for generic classes; inherited by non-class child scopes.

pub mangled_names: Option<IndexSet<String>>,

fn new(name: String, typ: CompilerScope, line_number: u32, is_nested: bool) -> Self {

Self {

name,

typ,

line_number,

is_nested,

symbols: IndexMap::default(),

sub_tables: vec![],

next_sub_table: 0,

varnames: Vec::new(),

needs_class_closure: false,

needs_classdict: false,

can_see_class_scope: false,

comp_inlined: false,

annotation_block: None,

has_conditional_annotations: false,

future_annotations: false,

mangled_names: None,

}

}

pub fn scan_program(

program: &ast::ModModule,

source_file: SourceFile,

) -> SymbolTableResult<Self> {

let mut builder = SymbolTableBuilder::new(source_file);

builder.scan_statements(program.body.as_ref())?;

builder.finish()

}

pub fn scan_expr(

expr: &ast::ModExpression,

source_file: SourceFile,

) -> SymbolTableResult<Self> {

let mut builder = SymbolTableBuilder::new(source_file);

builder.scan_expression(expr.body.as_ref(), ExpressionContext::Load)?;

builder.finish()

}

pub fn lookup(&self, name: &str) -> Option<&Symbol> {

self.symbols.get(name)

}

Module,

Class,

Function,

AsyncFunction,

Lambda,

Comprehension,

TypeParams,

/// PEP 649: Annotation scope for deferred evaluation

Annotation,

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {

match self {

Self::Module => write!(f, "module"),

Self::Class => write!(f, "class"),

Self::Function => write!(f, "function"),

Self::AsyncFunction => write!(f, "async function"),

Self::Lambda => write!(f, "lambda"),

Self::Comprehension => write!(f, "comprehension"),

Self::TypeParams => write!(f, "type parameter"),

Self::Annotation => write!(f, "annotation"),

// TODO missing types from the C implementation

// if self._table.type == _symtable.TYPE_TYPE_VAR_BOUND:

// return "TypeVar bound"

// if self._table.type == _symtable.TYPE_TYPE_ALIAS:

// return "type alias"

}

}

Unknown,

Local,

GlobalExplicit,

GlobalImplicit,

Free,

Cell,

pub name: String,

pub scope: SymbolScope,

pub flags: SymbolFlags,

fn new(name: &str) -> Self {

Self {

name: name.to_owned(),

// table,

scope: SymbolScope::Unknown,

flags: SymbolFlags::empty(),

}

}

pub const fn is_global(&self) -> bool {

matches!(

self.scope,

SymbolScope::GlobalExplicit | SymbolScope::GlobalImplicit

)

}

pub const fn is_local(&self) -> bool {

matches!(self.scope, SymbolScope::Local | SymbolScope::Cell)

}

pub const fn is_bound(&self) -> bool {

self.flags.intersects(SymbolFlags::BOUND)

}

pub fn into_codegen_error(self, source_path: String) -> CodegenError {

CodegenError {

location: self.location,

error: CodegenErrorType::SyntaxError(self.error),

source_path,

}

}

fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {

write!(

f,

"SymbolTable({:?} symbols, {:?} sub scopes)",

self.symbols.len(),

self.sub_tables.len()

)

}

let mut analyzer = SymbolTableAnalyzer::default();

// Discard the newfree set at the top level - it's only needed for propagation

// Pass None for class_entry at top level

let _newfree = analyzer.analyze_symbol_table(symbol_table, None)?;

Ok(())

// Check if __class__ is in the free variables collected from children

// If found, it means a child scope (method) references __class__

if newfree.shift_remove("__class__") {

symbol_table.needs_class_closure = true;

}

// Check if __classdict__ is in the free variables collected from children

if newfree.shift_remove("__classdict__") {

symbol_table.needs_classdict = true;

}

// Check if __conditional_annotations__ is in the free variables collected from children

// Remove it from free set - it's handled specially in class scope

if newfree.shift_remove("__conditional_annotations__") {

symbol_table.has_conditional_annotations = true;

}

use alloc::vec::Vec;

use core::ptr::NonNull;

pub struct StackStack<T> {

v: Vec<NonNull<T>>,

}

impl<T> Default for StackStack<T> {

fn default() -> Self {

Self { v: Vec::new() }

}

}

impl<T> StackStack<T> {

/// Appends a reference to this stack for the duration of the function `f`. When `f`

/// returns, the reference will be popped off the stack.

#[cfg(feature = "std")]

pub fn with_append<F, R>(&mut self, x: &mut T, f: F) -> R

where

F: FnOnce(&mut Self) -> R,

{

self.v.push(x.into());

let res = std::panic::catch_unwind(core::panic::AssertUnwindSafe(|| f(self)));

self.v.pop();

res.unwrap_or_else(|x| std::panic::resume_unwind(x))

}

/// Appends a reference to this stack for the duration of the function `f`. When `f`

/// returns, the reference will be popped off the stack.

///

/// Without std, panic cleanup is not guaranteed (no catch_unwind).

#[cfg(not(feature = "std"))]

pub fn with_append<F, R>(&mut self, x: &mut T, f: F) -> R

where

F: FnOnce(&mut Self) -> R,

{

self.v.push(x.into());

let result = f(self);

self.v.pop();

result

}

pub fn iter(&self) -> impl DoubleEndedIterator<Item = &T> + '_ {

self.as_ref().iter().copied()

}

pub fn iter_mut(&mut self) -> impl DoubleEndedIterator<Item = &mut T> + '_ {

self.as_mut().iter_mut().map(|x| &mut **x)

}

// pub fn top(&self) -> Option<&T> {

// self.as_ref().last().copied()

// }

// pub fn top_mut(&mut self) -> Option<&mut T> {

// self.as_mut().last_mut().map(|x| &mut **x)

// }

pub fn len(&self) -> usize {

self.v.len()

}

pub fn is_empty(&self) -> bool {

self.len() == 0

}

pub fn as_ref(&self) -> &[&T] {

unsafe { &*(self.v.as_slice() as *const [NonNull<T>] as *const [&T]) }

}

pub fn as_mut(&mut self) -> &mut [&mut T] {

unsafe { &mut *(self.v.as_mut_slice() as *mut [NonNull<T>] as *mut [&mut T]) }

}

}

/// Analyze a symbol table and return the set of free variables.

/// See symtable.c analyze_block().

/// class_entry: PEP 649 - enclosing class symbols for annotation scopes

fn analyze_symbol_table(

&mut self,

symbol_table: &mut SymbolTable,

class_entry: Option<&SymbolMap>,

) -> SymbolTableResult<IndexSet<String>> {

let symbols = core::mem::take(&mut symbol_table.symbols);

let sub_tables = &mut *symbol_table.sub_tables;

// Collect free variables from all child scopes

let mut newfree = IndexSet::default();

let annotation_block = &mut symbol_table.annotation_block;

// PEP 649: Determine class_entry to pass to children

// If current scope is a class with annotation block that can_see_class_scope,

// we need to pass class symbols to the annotation scope

let is_class = symbol_table.typ == CompilerScope::Class;

// Clone class symbols if needed for child scopes with can_see_class_scope

let needs_class_symbols = (is_class

&& (sub_tables.iter().any(|st| st.can_see_class_scope)

|| annotation_block

.as_ref()

.is_some_and(|b| b.can_see_class_scope)))

|| (!is_class

&& class_entry.is_some()

&& sub_tables.iter().any(|st| st.can_see_class_scope));

let class_symbols_clone = if is_class && needs_class_symbols {

Some(symbols.clone())

} else {

None

};

let mut info = (symbols, symbol_table.typ);

self.tables.with_append(&mut info, |list| {

let inner_scope = unsafe { &mut *(list as *mut _ as *mut Self) };

// Analyze sub scopes and collect their free variables

for sub_table in sub_tables.iter_mut() {

// Pass class_entry to sub-scopes that can see the class scope

let child_class_entry = if sub_table.can_see_class_scope {

if is_class {

class_symbols_clone.as_ref()

} else {

class_entry

}

} else {

None

};

let child_free = inner_scope.analyze_symbol_table(sub_table, child_class_entry)?;

// Propagate child's free variables to this scope

newfree.extend(child_free);

}

// PEP 649: Analyze annotation block if present

if let Some(annotation_table) = annotation_block {

// Pass class symbols to annotation scope if can_see_class_scope

let ann_class_entry = if annotation_table.can_see_class_scope {

if is_class {

class_symbols_clone.as_ref()

} else {

class_entry

}

} else {

None

};

let child_free =

inner_scope.analyze_symbol_table(annotation_table, ann_class_entry)?;

// Propagate annotation's free variables to this scope

newfree.extend(child_free);

}

Ok(())

})?;

symbol_table.symbols = info.0;

// PEP 709: Merge symbols from inlined comprehensions into parent scope

// Only merge symbols that are actually bound in the comprehension,

// not references to outer scope variables (Free symbols).

const BOUND_FLAGS: SymbolFlags = SymbolFlags::ASSIGNED

.union(SymbolFlags::PARAMETER)

.union(SymbolFlags::ITER)

.union(SymbolFlags::ASSIGNED_IN_COMPREHENSION);

for sub_table in sub_tables.iter() {

if sub_table.comp_inlined {

for (name, sub_symbol) in &sub_table.symbols {

// Skip the .0 parameter - it's internal to the comprehension

if name == ".0" {

continue;

}

// Only merge symbols that are bound in the comprehension

// Skip Free references to outer scope variables

if !sub_symbol.flags.intersects(BOUND_FLAGS) {

continue;

}

// If the symbol doesn't exist in parent, add it

if !symbol_table.symbols.contains_key(name) {

let mut symbol = sub_symbol.clone();

// Mark as local in parent scope

symbol.scope = SymbolScope::Local;

symbol_table.symbols.insert(name.clone(), symbol);

}

}

}

}

// Analyze symbols in current scope

for symbol in symbol_table.symbols.values_mut() {

self.analyze_symbol(symbol, symbol_table.typ, sub_tables, class_entry)?;

// Collect free variables from this scope

// These will be propagated to the parent scope

if symbol.scope == SymbolScope::Free || symbol.flags.contains(SymbolFlags::FREE_CLASS) {

newfree.insert(symbol.name.clone());

}

}

// Handle class-specific implicit cells

// This removes __class__ and __classdict__ from newfree if present

// and sets the corresponding flags on the symbol table

if symbol_table.typ == CompilerScope::Class {

drop_class_free(symbol_table, &mut newfree);

}

Ok(newfree)

}

fn analyze_symbol(

&mut self,

symbol: &mut Symbol,

st_typ: CompilerScope,

sub_tables: &[SymbolTable],

class_entry: Option<&SymbolMap>,

) -> SymbolTableResult {

if symbol

.flags

.contains(SymbolFlags::ASSIGNED_IN_COMPREHENSION)

&& st_typ == CompilerScope::Comprehension

{

// propagate symbol to next higher level that can hold it,

// i.e., function or module. Comprehension is skipped and

// Class is not allowed and detected as error.

//symbol.scope = SymbolScope::Nonlocal;

self.analyze_symbol_comprehension(symbol, 0)?

} else {

match symbol.scope {

SymbolScope::Free => {

if !self.tables.as_ref().is_empty() {

let scope_depth = self.tables.as_ref().len();

// check if the name is already defined in any outer scope

if scope_depth < 2

|| self.found_in_outer_scope(&symbol.name, st_typ)

!= Some(SymbolScope::Free)

{

return Err(SymbolTableError {

error: format!("no binding for nonlocal '{}' found", symbol.name),

// TODO: accurate location info, somehow

location: None,

});

}

// Check if the nonlocal binding refers to a type parameter

if symbol.flags.contains(SymbolFlags::NONLOCAL) {

for (symbols, _typ) in self.tables.iter().rev() {

if let Some(sym) = symbols.get(&symbol.name) {

if sym.flags.contains(SymbolFlags::TYPE_PARAM) {

return Err(SymbolTableError {

error: format!(

"nonlocal binding not allowed for type parameter '{}'",

symbol.name

),

location: None,

});

}

if sym.is_bound() {

break;

}

}

}

}

} else {

return Err(SymbolTableError {

error: format!(

"nonlocal {} defined at place without an enclosing scope",

symbol.name

),

// TODO: accurate location info, somehow

location: None,

});

}

}

SymbolScope::GlobalExplicit | SymbolScope::GlobalImplicit => {

// TODO: add more checks for globals?

}

SymbolScope::Local | SymbolScope::Cell => {

// all is well

}

SymbolScope::Unknown => {

// Try hard to figure out what the scope of this symbol is.

let scope = if symbol.is_bound() {

self.found_in_inner_scope(sub_tables, &symbol.name, st_typ)

.unwrap_or(SymbolScope::Local)

} else if let Some(scope) = self.found_in_outer_scope(&symbol.name, st_typ) {

// If found in enclosing scope (function/TypeParams), use that

scope

} else if let Some(class_symbols) = class_entry

&& let Some(class_sym) = class_symbols.get(&symbol.name)

&& class_sym.is_bound()

&& class_sym.scope != SymbolScope::Free

{

// If name is bound in enclosing class, use GlobalImplicit

// so it can be accessed via __classdict__

SymbolScope::GlobalImplicit

} else if self.tables.is_empty() {

// Don't make assumptions when we don't know.

SymbolScope::Unknown

} else {

// If there are scopes above we assume global.

SymbolScope::GlobalImplicit

};

symbol.scope = scope;

}

}

}

Ok(())

}

fn found_in_outer_scope(&mut self, name: &str, st_typ: CompilerScope) -> Option<SymbolScope> {

let mut decl_depth = None;

for (i, (symbols, typ)) in self.tables.iter().rev().enumerate() {

if matches!(typ, CompilerScope::Module)

|| matches!(typ, CompilerScope::Class if name != "__class__" && name != "__classdict__" && name != "__conditional_annotations__")

{

continue;

}

// PEP 649: Annotation scope is conceptually a sibling of the function,

// not a child. Skip the immediate parent function scope when looking

// for outer variables from annotation scope.

if st_typ == CompilerScope::Annotation

&& i == 0

&& matches!(

typ,

CompilerScope::Function | CompilerScope::AsyncFunction | CompilerScope::Lambda

)

{

continue;

}

// __class__ and __classdict__ are implicitly declared in class scope

// This handles the case where nested scopes reference them

if (name == "__class__" || name == "__classdict__")

&& matches!(typ, CompilerScope::Class)

{

decl_depth = Some(i);

break;

}

// __conditional_annotations__ is implicitly declared in class scope

// for classes with conditional annotations

if name == "__conditional_annotations__" && matches!(typ, CompilerScope::Class) {

decl_depth = Some(i);

break;

}

if let Some(sym) = symbols.get(name) {

match sym.scope {

SymbolScope::GlobalExplicit => return Some(SymbolScope::GlobalExplicit),

SymbolScope::GlobalImplicit => {}

_ => {

if sym.is_bound() {

decl_depth = Some(i);

break;

}

}

}

}

}

if let Some(decl_depth) = decl_depth {

// decl_depth is the number of tables between the current one and

// the one that declared the cell var

for (table, typ) in self.tables.iter_mut().rev().take(decl_depth) {

if let CompilerScope::Class = typ {

if let Some(free_class) = table.get_mut(name) {

free_class.flags.insert(SymbolFlags::FREE_CLASS)

} else {

let mut symbol = Symbol::new(name);

symbol.flags.insert(SymbolFlags::FREE_CLASS);

symbol.scope = SymbolScope::Free;

table.insert(name.to_owned(), symbol);

}

} else if !table.contains_key(name) {

let mut symbol = Symbol::new(name);

symbol.scope = SymbolScope::Free;

// symbol.is_referenced = true;

table.insert(name.to_owned(), symbol);

}

}

}

decl_depth.map(|_| SymbolScope::Free)

}

fn found_in_inner_scope(

&self,

sub_tables: &[SymbolTable],

name: &str,

st_typ: CompilerScope,

) -> Option<SymbolScope> {

sub_tables.iter().find_map(|st| {

let sym = st.symbols.get(name)?;

if sym.scope == SymbolScope::Free || sym.flags.contains(SymbolFlags::FREE_CLASS) {

if st_typ == CompilerScope::Class && name != "__class__" {

None

} else {

Some(SymbolScope::Cell)

}

} else if sym.scope == SymbolScope::GlobalExplicit && self.tables.is_empty() {

// the symbol is defined on the module level, and an inner scope declares

// a global that points to it

Some(SymbolScope::GlobalExplicit)

} else {

None

}

})

}

// Implements the symbol analysis and scope extension for names

// assigned by a named expression in a comprehension. See:

// https://github.com/python/cpython/blob/7b78e7f9fd77bb3280ee39fb74b86772a7d46a70/Python/symtable.c#L1435

fn analyze_symbol_comprehension(

&mut self,

symbol: &mut Symbol,

parent_offset: usize,

) -> SymbolTableResult {

// when this is called, we expect to be in the direct parent scope of the scope that contains 'symbol'

let last = self.tables.iter_mut().rev().nth(parent_offset).unwrap();

let symbols = &mut last.0;

let table_type = last.1;

// it is not allowed to use an iterator variable as assignee in a named expression

if symbol.flags.contains(SymbolFlags::ITER) {

return Err(SymbolTableError {

error: format!(

"assignment expression cannot rebind comprehension iteration variable {}",

symbol.name

),

// TODO: accurate location info, somehow

location: None,

});

}

match table_type {

CompilerScope::Module => {

symbol.scope = SymbolScope::GlobalImplicit;

}

CompilerScope::Class => {

// named expressions are forbidden in comprehensions on class scope

return Err(SymbolTableError {

error: "assignment expression within a comprehension cannot be used in a class body".to_string(),

// TODO: accurate location info, somehow

location: None,

});

}

CompilerScope::Function | CompilerScope::AsyncFunction | CompilerScope::Lambda => {

if let Some(parent_symbol) = symbols.get_mut(&symbol.name) {

if let SymbolScope::Unknown = parent_symbol.scope {

// this information is new, as the assignment is done in inner scope

parent_symbol.flags.insert(SymbolFlags::ASSIGNED);

}

symbol.scope = if parent_symbol.is_global() {

parent_symbol.scope

} else {

SymbolScope::Free

};

} else {

let mut cloned_sym = symbol.clone();

cloned_sym.scope = SymbolScope::Cell;

last.0.insert(cloned_sym.name.to_owned(), cloned_sym);

}

}

CompilerScope::Comprehension => {

// TODO check for conflicts - requires more context information about variables

match symbols.get_mut(&symbol.name) {

Some(parent_symbol) => {

// check if assignee is an iterator in top scope

if parent_symbol.flags.contains(SymbolFlags::ITER) {

return Err(SymbolTableError {

error: format!(

"assignment expression cannot rebind comprehension iteration variable {}",

symbol.name

),

location: None,

});

}

// we synthesize the assignment to the symbol from inner scope

parent_symbol.flags.insert(SymbolFlags::ASSIGNED); // more checks are required

}

None => {

// extend the scope of the inner symbol

// as we are in a nested comprehension, we expect that the symbol is needed

// outside, too, and set it therefore to non-local scope. I.e., we expect to

// find a definition on a higher level

let mut cloned_sym = symbol.clone();

cloned_sym.scope = SymbolScope::Free;

last.0.insert(cloned_sym.name.to_owned(), cloned_sym);

}

}

self.analyze_symbol_comprehension(symbol, parent_offset + 1)?;

}

CompilerScope::TypeParams => {

// Named expression in comprehension cannot be used in type params

return Err(SymbolTableError {

error: "assignment expression within a comprehension cannot be used within the definition of a generic".to_string(),

location: None,

});

}

CompilerScope::Annotation => {

// Named expression is not allowed in annotation scope

return Err(SymbolTableError {

error: "named expression cannot be used within an annotation".to_string(),

location: None,

});

}

}

Ok(())

}

Global,

Nonlocal,

Used,

Assigned,

Imported,

AnnotationAssigned,

Parameter,

AnnotationParameter,

AssignedNamedExprInComprehension,

Iter,

TypeParam,

class_name: Option<String>,

// Scope stack.

tables: Vec<SymbolTable>,

future_annotations: bool,

source_file: SourceFile,

// Current scope's varnames being collected (temporary storage)

current_varnames: Vec<String>,

// Stack to preserve parent varnames when entering nested scopes

varnames_stack: Vec<Vec<String>>,

// Track if we're inside an iterable definition expression (for nested comprehensions)

in_iter_def_exp: bool,

// Track if we're inside an annotation (yield/await/named expr not allowed)

in_annotation: bool,

// Track if we're inside a type alias (yield/await/named expr not allowed)

in_type_alias: bool,

// Track if we're scanning an inner loop iteration target (not the first generator)

in_comp_inner_loop_target: bool,

// Scope info for error messages (e.g., "a TypeVar bound")

scope_info: Option<&'static str>,

// PEP 649: Track if we're inside a conditional block (if/for/while/etc.)

in_conditional_block: bool,

Load,

Store,

Delete,

Iter,

IterDefinitionExp,

fn new(source_file: SourceFile) -> Self {

let mut this = Self {

class_name: None,

tables: vec![],

future_annotations: false,

source_file,

current_varnames: Vec::new(),

varnames_stack: Vec::new(),

in_iter_def_exp: false,

in_annotation: false,

in_type_alias: false,

in_comp_inner_loop_target: false,

scope_info: None,

in_conditional_block: false,

};

this.enter_scope("top", CompilerScope::Module, 0);

this

}

fn finish(mut self) -> Result<SymbolTable, SymbolTableError> {

assert_eq!(self.tables.len(), 1);

let mut symbol_table = self.tables.pop().unwrap();

// Save varnames for the top-level module scope

symbol_table.varnames = self.current_varnames;

// Propagate future_annotations to the symbol table

symbol_table.future_annotations = self.future_annotations;

analyze_symbol_table(&mut symbol_table)?;

Ok(symbol_table)

}

fn enter_scope(&mut self, name: &str, typ: CompilerScope, line_number: u32) {

let is_nested = self

.tables

.last()

.map(|table| {

table.is_nested

|| matches!(

table.typ,

CompilerScope::Function | CompilerScope::AsyncFunction

)

})

.unwrap_or(false);

// Inherit mangled_names from parent for non-class scopes

let inherited_mangled_names = self

.tables

.last()

.and_then(|t| t.mangled_names.clone())

.filter(|_| typ != CompilerScope::Class);

let mut table = SymbolTable::new(name.to_owned(), typ, line_number, is_nested);

table.mangled_names = inherited_mangled_names;

self.tables.push(table);

// Save parent's varnames and start fresh for the new scope

self.varnames_stack

.push(core::mem::take(&mut self.current_varnames));

}

fn enter_type_param_block(

&mut self,

name: &str,

line_number: u32,

for_class: bool,

) -> SymbolTableResult {

// Check if we're in a class scope

let in_class = self

.tables

.last()

.is_some_and(|t| t.typ == CompilerScope::Class);

self.enter_scope(name, CompilerScope::TypeParams, line_number);

// Set properties on the newly created type param scope

if let Some(table) = self.tables.last_mut() {

table.can_see_class_scope = in_class;