pyfcstm.model.imports

Import assembly helpers for model-layer state-machine construction.

This module implements the model-layer import assembler used by parse_dsl_node_to_state_machine(). The assembler keeps the DSL layer pure: the DSL parser only produces AST nodes, while file loading, recursive import resolution, path handling, cycle detection, variable mapping, and state-tree inlining are all performed here in the model layer.

At the current phase boundary, this module provides:

  • Relative import paths resolve against the declaring file’s directory.

  • Imported files are parsed recursively and inlined as child states.

  • Circular imports and alias conflicts are reported explicitly.

  • Imported root states are renamed to the declared alias and their display-name priority follows the PR79 design.

  • Imported top-level def definitions are merged into the host model using Phase 3 mapping and conflict checks.

  • Variable def mappings support exact / set / pattern / fallback rules, placeholder expansion, default alias-based isolation, and deep variable reference rewriting across definitions, guards, and operation blocks.

  • Module-local absolute paths are rewritten into the final host instance scope so assembled state trees behave like ordinary inlined DSL.

Event mappings support module-absolute event promotion into host-relative or host-absolute event paths, including display-name propagation and conflict checks defined by PR79.

__all__

pyfcstm.model.imports.__all__ = ['assemble_state_machine_imports']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

assemble_state_machine_imports

pyfcstm.model.imports.assemble_state_machine_imports(dnode: StateMachineDSLProgram, path: str | None = None, *, collect_into: DiagnosticSink | None = None) → StateMachineDSLProgram[source]

Assemble import statements in a DSL program into a single inline AST.

Parameters:

  • dnode (dsl_nodes.StateMachineDSLProgram) – Source DSL program AST.

  • path (Optional[str]) – Optional path contract used to resolve import locations. Existing directories are treated as import base directories directly, while other values are treated as file paths whose parent directory is used as the import base.

  • collect_into (pyfcstm.diagnostics.DiagnosticSink, optional) – Optional pyfcstm.diagnostics.DiagnosticSink used to accumulate E_IMPORT_* diagnostics from this assembly pass. When provided in collect=True mode, all detectable import diagnostics are reported on the sink and the assembler continues past errors so subsequent issues can also surface. When None (the default) a fresh strict sink is created — the first error raises pyfcstm.utils.validate.ModelValidationError carrying the structured diagnostic, preserving backward compatibility with except SyntaxError: handlers.

Returns:

A cloned and import-expanded DSL program AST.

Return type:

dsl_nodes.StateMachineDSLProgram

Raises:

pyfcstm.utils.validate.ModelValidationError – If import assembly fails in strict mode (default) due to missing files, circular imports, alias conflicts, or mapping / imported-definition errors. Subclasses SyntaxError for back-compat.