pyfcstm.model.load

Convenience model loading helpers for FCSTM sources.

This module provides high-level public entry points that collapse the common workflow:

  1. read or accept FCSTM DSL source text

  2. parse DSL into AST

  3. assemble imports and build the final StateMachine

The helpers here do not replace the lower-level DSL parser or model builder. They only provide a more direct public API for callers that already know they want a fully constructed model object.

The main public helpers are:

Example:

>>> import os
>>> from tempfile import TemporaryDirectory
>>> from pyfcstm.model.load import load_state_machine_from_file
>>> with TemporaryDirectory() as td:
...     file_path = os.path.join(td, 'demo.fcstm')
...     with open(file_path, 'w', encoding='utf-8') as f:
...         _ = f.write('state Root;')
...     model = load_state_machine_from_file(file_path)
...     model.root_state.name
'Root'

Example:

>>> from pyfcstm.model.load import load_state_machine_from_text
>>> model = load_state_machine_from_text('state Root;')
>>> model.root_state.name
'Root'

Example:

>>> import os
>>> from pyfcstm.model.load import load_state_machine_from_text
>>> model = load_state_machine_from_text(
...     'state Root { state Idle; [*] -> Idle; }',
...     path=os.getcwd(),
... )
>>> model.root_state.name
'Root'

__all__

pyfcstm.model.load.__all__ = ['load_state_machine_from_file', 'load_state_machine_from_text']

Built-in mutable sequence.

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

load_state_machine_from_file

pyfcstm.model.load.load_state_machine_from_file(path: str | PathLike) → StateMachine[source]

Load a StateMachine directly from an FCSTM file.

This helper reads the file as bytes, decodes it with pyfcstm.utils.auto_decode(), parses the DSL into AST, and then builds the final import-aware model using the file path as the import resolution context.

Parameters:

path (Union[str, os.PathLike]) – Path to the input .fcstm file.

Returns:

Fully constructed state machine model.

Return type:

StateMachine

Raises:

  • OSError – If the file cannot be read.

  • UnicodeDecodeError – If the file content cannot be decoded.

  • pyfcstm.dsl.error.GrammarParseError – If DSL parsing fails.

  • SyntaxError – If model assembly or validation fails.

Example:

>>> import os
>>> from tempfile import TemporaryDirectory
>>> with TemporaryDirectory() as td:
...     file_path = os.path.join(td, 'demo.fcstm')
...     with open(file_path, 'w', encoding='utf-8') as f:
...         _ = f.write('state Root;')
...     model = load_state_machine_from_file(file_path)
...     model.root_state.name
'Root'

load_state_machine_from_text

pyfcstm.model.load.load_state_machine_from_text(text: str, path: str | PathLike | None = None) → StateMachine[source]

Load a StateMachine directly from FCSTM DSL source text.

This helper parses the given DSL text into AST and then builds the final model. When path is omitted, the current working directory is used as the import resolution context; callers may also pass an explicit file path or directory path to control import resolution.

Parameters:

  • text (str) – FCSTM DSL source text.

  • path (Optional[Union[str, os.PathLike]]) – Optional path contract for import resolution. Defaults to the current working directory when omitted.

Returns:

Fully constructed state machine model.

Return type:

StateMachine

Raises:

Example:

>>> model = load_state_machine_from_text('state Root;')
>>> model.root_state.name
'Root'

Example:

>>> import os
>>> model = load_state_machine_from_text(
...     'state Root { state Idle; [*] -> Idle; }',
...     path=os.getcwd(),
... )
>>> model.root_state.name
'Root'

Example:

>>> import os
>>> from tempfile import TemporaryDirectory
>>> with TemporaryDirectory() as td:
...     child_path = os.path.join(td, 'worker.fcstm')
...     with open(child_path, 'w', encoding='utf-8') as f:
...         _ = f.write('state WorkerRoot { state Idle; [*] -> Idle; }')
...     model = load_state_machine_from_text(
...         'state Root { import "./worker.fcstm" as Worker; [*] -> Worker; }',
...         path=td,
...     )
...     sorted(model.root_state.substates.keys())
['Worker']