router::state_machine::RouterStateMachine¶

Public Functions¶

	Name
None	init(self self, Dict sm_definition[str, Any], Optional]] rule_handlers[Dict[str, Callable[..., Any] =None)
RouterStateMachine	load_definition(cls cls, Path json_path, Optional]] rule_handlers[Dict[str, Callable[..., Any] =None)
None	trigger(self self, str event_name, Any args, *Any kwargs)
str	state(self self)
bool	is_built(self self)

Protected Functions¶

	Name
None	_build(self self)
None	_validate_definition(self self)
str	_find_start_state(self self)

Protected Attributes¶

	Name
dict	_ROUTER_CLASSIFIER_DEFINITION
	_machine
	_definition

Detailed Description¶

class router::state_machine::RouterStateMachine;

GQHSM-compatible state machine runtime wrapping ``transitions``.

Consumes a JSON state machine definition (matching
``GQHSM_JSON_SCHEMA``) and builds a ``transitions.Machine`` from it.
Rule handler callbacks are registered via *rule_handlers*, mapping
callback name strings from the JSON definition to Python callables.

The machine is built lazily — the constructor validates the JSON
structure but defers ``transitions`` instantiation until
:meth:`trigger` is first called.  This allows the module to be
imported even when ``transitions`` is not yet installed.

Args:
    sm_definition: GQHSM-compatible state machine JSON as a dict.
    rule_handlers: Optional dict mapping callback names (e.g.,
        ``"run_keyword_triggers"``) to Python callables.  Only needed
        if the JSON definition references entry/exit/guard/action
        callbacks.

Raises:
    ValueError: If *sm_definition* does not contain the required
        ``stateMachineInfo``, ``states``, and ``transitions`` keys.

Public Functions Documentation¶

function init¶

None __init__(
    self self,
    Dict sm_definition[str, Any],
    Optional]] rule_handlers[Dict[str, Callable[..., Any] =None
)

function load_definition¶

RouterStateMachine load_definition(
    cls cls,
    Path json_path,
    Optional]] rule_handlers[Dict[str, Callable[..., Any] =None
)

Load a GQHSM-compatible JSON definition from *json_path*.

Args:
    json_path: Path to a JSON state machine definition file.
    rule_handlers: Optional callback name → callable mapping.

Returns:
    A ``RouterStateMachine`` ready to trigger events.

Raises:
    FileNotFoundError: If *json_path* does not exist.
    json.JSONDecodeError: If the file is not valid JSON.

function trigger¶

None trigger(
    self self,
    str event_name,
    *Any args,
    **Any kwargs
)

Dispatch an event signal to the state machine.

Building the ``transitions.Machine`` is deferred until the first
trigger call (lazy initialization).

Args:
    event_name: The event signal name matching a transition's
        ``eventSignal`` in the JSON definition.
    *args: Positional arguments passed to guard/action callbacks.
    **kwargs: Keyword arguments passed to guard/action callbacks.

Raises:
    ImportError: If ``transitions`` is not installed.
    AttributeError: If *event_name* does not match any trigger.

function state¶

str state(
    self self
)

Return the current state name (from the initial state if not yet built).```


### function is_built

```python
bool is_built(
    self self
)

True if the ``transitions`` machine has been constructed.```


## Protected Functions Documentation

### function _build

```python
None _build(
    self self
)

Build the ``transitions.Machine`` from the JSON definition.```


### function _validate_definition

```python
None _validate_definition(
    self self
)

function _find_start_state¶

str _find_start_state(
    self self
)

Return the name of the start state from the JSON definition.```


## Protected Attributes Documentation

### variable _ROUTER_CLASSIFIER_DEFINITION

```python
static dict _ROUTER_CLASSIFIER_DEFINITION;

variable _machine¶

_machine;

variable _definition¶

_definition;

Updated on 2026-10-09 at 03:59:43 +0000