pyfcstm.simulate.context

Read-only execution context for abstract function handlers.

This module provides the ReadOnlyExecutionContext class that gives abstract function handlers read-only access to the current execution state including the active state path and variable values.

The module contains the following main components:

ReadOnlyExecutionContext - Immutable context passed to abstract handlers.

Example:

>>> from pyfcstm.simulate import ReadOnlyExecutionContext
>>> def my_handler(ctx: ReadOnlyExecutionContext):
...     print(f"State: {ctx.get_full_state_path()}")
...     print(f"Counter: {ctx.get_var('counter')}")

ReadOnlyExecutionContext

class pyfcstm.simulate.context.ReadOnlyExecutionContext(state_path: Tuple[str, ...], vars: Dict[str, int | float], action_name: str, action_stage: str)[source]

Read-only execution context for abstract function handlers.

Provides immutable access to current state and variable values without allowing modifications. This context is passed to registered abstract handlers during execution.

Parameters:

state_path (Tuple[str, ...]) – Current active state path from root to leaf
vars (Dict[str, Union[int, float]]) – Snapshot of current variable values (immutable copy)
action_name (str) – Full path name of the abstract action being executed
action_stage (str) – Lifecycle stage (‘enter’, ‘during’, ‘exit’)

Example:

>>> ctx = ReadOnlyExecutionContext(
...     state_path=('System', 'Active'),
...     vars={'counter': 10, 'temperature': 25.5},
...     action_name='System.Active.Monitor',
...     action_stage='during'
... )
>>> ctx.get_state_name()
'Active'
>>> ctx.get_var('counter')
10

get_full_state_path() → str[source]

Get full state path as dot-separated string.

Returns:: Full state path
Return type:: str

Example:

>>> ctx.get_full_state_path()
'System.Active'

get_state_name() → str[source]

Get current state name (last component of path).

Returns:: State name, or empty string if no state is active
Return type:: str

Example:

>>> ctx.get_state_name()
'Active'

get_var(name: str) → int | float[source]

Get variable value by name.

Parameters:: name (str) – Variable name
Returns:: Variable value
Return type:: Union[int, float]
Raises:: KeyError – If variable does not exist

Example:

>>> ctx.get_var('counter')
10

has_var(name: str) → bool[source]

Check if a variable exists.

Parameters:: name (str) – Variable name
Returns:: True if variable exists
Return type:: bool

Example:

>>> ctx.has_var('counter')
True
>>> ctx.has_var('nonexistent')
False