pyfcstm.simulate.utils

Naming utilities for simulation runtime logging and diagnostics.

This module provides helper functions for converting runtime objects into human-readable string representations. These utilities are used throughout the simulation runtime for logging execution steps and presenting lifecycle action paths in diagnostic messages.

The module contains the following main components:

These functions are essential for debugging state machine execution, as they provide consistent naming conventions that match the DSL source structure.

Example:

>>> from pyfcstm.simulate.utils import is_state_resolve_event_path
>>> # Check event path syntax
>>> is_state_resolve_event_path('/global.shutdown')
True
>>> is_state_resolve_event_path('.error')
True

Note

For action naming, use the OnStage.func_name or OnAspect.func_name property directly. For event naming, use the Event.path_name property.

is_state_resolve_event_path

pyfcstm.simulate.utils.is_state_resolve_event_path(path: str) → bool[source]

Check if an event path string is definitely for State.resolve_event.

This function determines whether a path string uses State.resolve_event syntax (relative, parent-relative, or absolute notation) based on its grammatical features. It returns True only when the path is definitively a State.resolve_event path, and False when uncertain.

Return Values:

  • True: The path is definitely for State.resolve_event (uses special notation)

  • False: Uncertain - could be either State or StateMachine resolve_event

Detection Rules:

  1. Absolute paths (starting with /): Definitely State.resolve_event

  2. Parent-relative paths (starting with .): Definitely State.resolve_event

  3. Plain paths (no special prefix): Uncertain (could be either)

Parameters:

path (str) – Event path string to check

Returns:

True if definitely State.resolve_event syntax, False if uncertain

Return type:

bool

Example:

>>> from pyfcstm.simulate.utils import is_state_resolve_event_path
>>> # Absolute paths - definitely State.resolve_event
>>> is_state_resolve_event_path('/global.shutdown')
True
>>> # Parent-relative paths - definitely State.resolve_event
>>> is_state_resolve_event_path('.error')
True
>>> is_state_resolve_event_path('..system.error')
True
>>> # Plain paths - uncertain (could be either)
>>> is_state_resolve_event_path('Root.System.error')
False
>>> is_state_resolve_event_path('error.critical')
False

Note

This function only detects paths that are definitely State.resolve_event based on syntax. Plain paths without special notation are considered uncertain because they could be valid for either State or StateMachine resolve_event.