build_symbol_table

build_symbol_table(module: ModuleType | None, module_name: str, ast_symbols: ASTSymbols, all_exports: set[str] | None = None, include_private: bool = False) → SymbolTable[source]

Build a SymbolTable by merging runtime and AST information.

Live objects from module are matched against the ASTSymbols by name and combined into typed StubSymbol entries. When module is None (AST-only mode), all live_* fields are None.

The symbol table is populated in this order:

  1. TypeAlias / TypeVar declarations (from AST).

  2. Classes — merged with inspect.getmembers when module is available; filtered to symbols whose __module__ matches module_name.

  3. Module-level functions — from AST; live_func set from module.

  4. Overload groups — grouped @overload functions from AST.

  5. Module-level variables — from AST; live_value set from module.

Parameters:

  • module (types.ModuleType or None) – Loaded module from load_module(), or None for AST-only mode.

  • module_name (str) – Synthetic _stubpy_target_* module name used to filter local classes from imported ones.

  • ast_symbols (ASTSymbols) – Output from ast_harvest().

  • all_exports (set of str or None) – When provided, only names in this set are included. None means include all public (non-underscore-prefixed) names unless include_private is True.

  • include_private (bool) – When True, names starting with _ are not filtered out. Defaults to False.

Returns:

SymbolTable – Populated, source-order-preserving symbol table.

Examples

>>> import types as _t
>>> from stubpy.ast_pass import ast_harvest
>>> m = _t.ModuleType("_stubpy_target_ex")
>>> class Foo: pass
>>> Foo.__module__ = "_stubpy_target_ex"
>>> m.Foo = Foo
>>> syms = ast_harvest("class Foo: pass")
>>> tbl = build_symbol_table(m, "_stubpy_target_ex", syms)
>>> tbl.get("Foo").kind.value
'class'

See also

Public API reference — overview of all public names.