session

Track the reachable parsed-module graph, import edges, diagnostics, and visible bindings for one multi-module analysis run.

Classes:

• CompilationSession –

CompilationSession dataclass

CompilationSession(
    root: ParsedModule,
    resolver: ImportResolver,
    modules: dict[ModuleKey, ParsedModule] = dict(),
    graph: dict[ModuleKey, set[ModuleKey]] = dict(),
    load_order: list[ModuleKey] = list(),
    diagnostics: DiagnosticBag = DiagnosticBag(),
    visible_bindings: dict[
        ModuleKey, dict[str, SemanticBinding]
    ] = dict(),
    _resolution_cache: dict[
        tuple[ModuleKey, str], ParsedModule | None
    ] = dict(),
    _probe_cache: dict[
        tuple[ModuleKey, str], ParsedModule | None
    ] = dict(),
)

Own the loaded module graph and cross-module binding state that analysis and lowering share for one compilation. attributes: root: type: ParsedModule resolver: type: ImportResolver modules: type: dict[ModuleKey, ParsedModule] graph: type: dict[ModuleKey, set[ModuleKey]] load_order: type: list[ModuleKey] diagnostics: type: DiagnosticBag visible_bindings: type: dict[ModuleKey, dict[str, SemanticBinding]] _resolution_cache: type: dict[tuple[ModuleKey, str], ParsedModule | None] _probe_cache: type: dict[tuple[ModuleKey, str], ParsedModule | None]

Methods:

• expand_graph –
• module –
• ordered_modules –
• probe_import_specifier –
• register_module –
• resolve_import_from_name –
• resolve_import_specifier –

expand_graph

expand_graph() -> None

Walk top-level imports from the root module, load every reachable dependency, and reject cycles.

Source code in packages/irx/src/irx/analysis/session.py

def expand_graph(self) -> None:
    """
    title: Expand the reachable import graph from the root module.
    summary: >-
      Walk top-level imports from the root module, load every reachable
      dependency, and reject cycles.
    """
    self.load_order.clear()
    temporary: list[ModuleKey] = []
    temporary_lookup: set[ModuleKey] = set()
    permanent: set[ModuleKey] = set()
    importable_names: dict[ModuleKey, set[str]] = {}

    def dfs(module_key: ModuleKey) -> set[str]:
        """
        title: Visit one reachable module during graph expansion.
        summary: >-
          Depth-first walk one module, record its outgoing edges, append it
          to the stable load order after its dependencies, and track which
          names later from-import statements may bind directly from that
          module.
        parameters:
          module_key:
            type: ModuleKey
        returns:
          type: set[str]
        """
        if module_key in permanent:
            return importable_names[module_key]
        if module_key in temporary_lookup:
            cycle_start = temporary.index(module_key)
            cycle_path = [*temporary[cycle_start:], module_key]
            cycle_str = " -> ".join(str(item) for item in cycle_path)
            self.diagnostics.add(
                f"Cyclic import detected: {cycle_str}",
                node=self.modules[module_key].ast,
                module_key=module_key,
            )
            return importable_names.get(module_key, set())

        temporary.append(module_key)
        temporary_lookup.add(module_key)

        parsed_module = self.modules[module_key]
        dependencies: list[ModuleKey] = []
        module_importable_names = importable_names.setdefault(
            module_key,
            _declared_importable_names(parsed_module.ast),
        )
        for node in parsed_module.ast.nodes:
            if isinstance(node, astx.ImportStmt):
                for alias in node.names:
                    resolved = self.resolve_import_specifier(
                        module_key,
                        node,
                        alias.name,
                    )
                    if resolved is None:
                        continue
                    self.graph.setdefault(module_key, set()).add(
                        resolved.key
                    )
                    dependencies.append(resolved.key)
            elif isinstance(node, astx.ImportFromStmt):
                resolved_parent = self.resolve_import_specifier(
                    module_key,
                    node,
                    _module_import_specifier(node),
                )
                if resolved_parent is None:
                    continue
                self.graph.setdefault(module_key, set()).add(
                    resolved_parent.key
                )
                dependencies.append(resolved_parent.key)
                parent_importable_names = dfs(resolved_parent.key)

                for alias in node.names:
                    if alias.name == "*":
                        continue

                    local_name = alias.asname or alias.name
                    if alias.name in parent_importable_names:
                        module_importable_names.add(local_name)
                        continue

                    resolved_child = self.probe_import_specifier(
                        module_key,
                        node,
                        f"{resolved_parent.key}.{alias.name}",
                    )
                    if resolved_child is None:
                        continue
                    self.graph.setdefault(module_key, set()).add(
                        resolved_child.key
                    )
                    dependencies.append(resolved_child.key)

        for dependency_key in dependencies:
            dfs(dependency_key)

        temporary.pop()
        temporary_lookup.remove(module_key)
        permanent.add(module_key)
        self.load_order.append(module_key)
        return module_importable_names

    dfs(self.root.key)

module

module(module_key: ModuleKey) -> ParsedModule

Look up a previously-registered parsed module by its canonical host key. parameters: module_key: type: ModuleKey returns: type: ParsedModule

Source code in packages/irx/src/irx/analysis/session.py

def module(self, module_key: ModuleKey) -> ParsedModule:
    """
    title: Return a parsed module by key.
    summary: >-
      Look up a previously-registered parsed module by its canonical host
      key.
    parameters:
      module_key:
        type: ModuleKey
    returns:
      type: ParsedModule
    """
    return self.modules[module_key]

ordered_modules

ordered_modules() -> list[ParsedModule]

Materialize the dependency-ordered module list used by later semantic and lowering passes. returns: type: list[ParsedModule]

Source code in packages/irx/src/irx/analysis/session.py

def ordered_modules(self) -> list[ParsedModule]:
    """
    title: Return parsed modules in stable dependency order.
    summary: >-
      Materialize the dependency-ordered module list used by later semantic
      and lowering passes.
    returns:
      type: list[ParsedModule]
    """
    return [self.modules[module_key] for module_key in self.load_order]

probe_import_specifier

probe_import_specifier(
    requesting_module_key: ModuleKey,
    import_node: ImportStmt | ImportFromStmt,
    requested_specifier: str,
) -> ParsedModule | None

Try the host resolver for speculative import edges such as child- module fallbacks while keeping expected missing-module probes silent but still surfacing unexpected resolver failures. parameters: requesting_module_key: type: ModuleKey import_node: type: astx.ImportStmt | astx.ImportFromStmt requested_specifier: type: str returns: type: ParsedModule | None

Source code in packages/irx/src/irx/analysis/session.py

def probe_import_specifier(
    self,
    requesting_module_key: ModuleKey,
    import_node: astx.ImportStmt | astx.ImportFromStmt,
    requested_specifier: str,
) -> ParsedModule | None:
    """
    title: Probe one import request without emitting diagnostics.
    summary: >-
      Try the host resolver for speculative import edges such as child-
      module fallbacks while keeping expected missing-module probes silent
      but still surfacing unexpected resolver failures.
    parameters:
      requesting_module_key:
        type: ModuleKey
      import_node:
        type: astx.ImportStmt | astx.ImportFromStmt
      requested_specifier:
        type: str
    returns:
      type: ParsedModule | None
    """
    cache_key = (requesting_module_key, requested_specifier)
    if cache_key in self._probe_cache:
        return self._probe_cache[cache_key]

    try:
        resolved = self.resolver(
            requesting_module_key,
            import_node,
            requested_specifier,
        )
    except LookupError:
        self._probe_cache[cache_key] = None
        return None

    self.register_module(resolved)
    self._probe_cache[cache_key] = resolved
    return resolved

register_module

register_module(
    parsed_module: ParsedModule,
) -> ParsedModule

Cache a parsed module once and initialize its graph and visible binding slots. parameters: parsed_module: type: ParsedModule returns: type: ParsedModule

Source code in packages/irx/src/irx/analysis/session.py

def register_module(self, parsed_module: ParsedModule) -> ParsedModule:
    """
    title: Register one parsed module in the session cache.
    summary: >-
      Cache a parsed module once and initialize its graph and visible
      binding slots.
    parameters:
      parsed_module:
        type: ParsedModule
    returns:
      type: ParsedModule
    """
    existing = self.modules.get(parsed_module.key)
    if existing is not None:
        return existing
    self.modules[parsed_module.key] = parsed_module
    self.graph.setdefault(parsed_module.key, set())
    self.visible_bindings.setdefault(parsed_module.key, {})
    return parsed_module

resolve_import_from_name

resolve_import_from_name(
    requesting_module_key: ModuleKey,
    import_node: ImportFromStmt,
    parent_module_key: ModuleKey,
    imported_name: str,
) -> tuple[SemanticBinding | None, ParsedModule | None]

-

Resolve one import-from name to a direct binding or child module.

Apply symbol-first, child-module-second import-from semantics using the parent module's visible bindings before attempting module namespace fallback. parameters: requesting_module_key: type: ModuleKey import_node: type: astx.ImportFromStmt parent_module_key: type: ModuleKey imported_name: type: str returns: type: tuple[SemanticBinding | None, ParsedModule | None]

Source code in packages/irx/src/irx/analysis/session.py

def resolve_import_from_name(
    self,
    requesting_module_key: ModuleKey,
    import_node: astx.ImportFromStmt,
    parent_module_key: ModuleKey,
    imported_name: str,
) -> tuple[SemanticBinding | None, ParsedModule | None]:
    """
    title: >-
      Resolve one import-from name to a direct binding or child module.
    summary: >-
      Apply symbol-first, child-module-second import-from semantics using
      the parent module's visible bindings before attempting module
      namespace fallback.
    parameters:
      requesting_module_key:
        type: ModuleKey
      import_node:
        type: astx.ImportFromStmt
      parent_module_key:
        type: ModuleKey
      imported_name:
        type: str
    returns:
      type: tuple[SemanticBinding | None, ParsedModule | None]
    """
    target_binding = self.visible_bindings.get(parent_module_key, {}).get(
        imported_name
    )
    if (
        target_binding is not None
        and target_binding.kind in _IMPORTABLE_BINDING_KINDS
    ):
        return target_binding, None

    requested_specifier = f"{parent_module_key}.{imported_name}"
    resolved_child = self.probe_import_specifier(
        requesting_module_key,
        import_node,
        requested_specifier,
    )
    return None, resolved_child

resolve_import_specifier

resolve_import_specifier(
    requesting_module_key: ModuleKey,
    import_node: ImportStmt | ImportFromStmt,
    requested_specifier: str,
) -> ParsedModule | None

Call the host resolver once per import request, memoizing both successes and failures. parameters: requesting_module_key: type: ModuleKey import_node: type: astx.ImportStmt | astx.ImportFromStmt requested_specifier: type: str returns: type: ParsedModule | None

Source code in packages/irx/src/irx/analysis/session.py

def resolve_import_specifier(
    self,
    requesting_module_key: ModuleKey,
    import_node: astx.ImportStmt | astx.ImportFromStmt,
    requested_specifier: str,
) -> ParsedModule | None:
    """
    title: Resolve one import request through the host resolver.
    summary: >-
      Call the host resolver once per import request, memoizing both
      successes and failures.
    parameters:
      requesting_module_key:
        type: ModuleKey
      import_node:
        type: astx.ImportStmt | astx.ImportFromStmt
      requested_specifier:
        type: str
    returns:
      type: ParsedModule | None
    """
    cache_key = (requesting_module_key, requested_specifier)
    if cache_key in self._resolution_cache:
        return self._resolution_cache[cache_key]
    if (
        cache_key in self._probe_cache
        and self._probe_cache[cache_key] is not None
    ):
        resolved = self._probe_cache[cache_key]
        self._resolution_cache[cache_key] = resolved
        return resolved

    try:
        resolved = self.resolver(
            requesting_module_key,
            import_node,
            requested_specifier,
        )
    except Exception as exc:
        self.diagnostics.add(
            f"Unable to resolve module '{requested_specifier}': {exc}",
            node=import_node,
            module_key=requesting_module_key,
        )
        self._resolution_cache[cache_key] = None
        return None

    self.register_module(resolved)
    self._probe_cache[cache_key] = resolved
    self._resolution_cache[cache_key] = resolved
    return resolved