python-statemachine 3.1.2__py3-none-any.whl → 3.2.0__py3-none-any.whl

statemachine/io/builder.py

@@ -0,0 +1,195 @@
+"""Compile the neutral IR into StateChart class keyword arguments.
+
+:class:`DefinitionBuilder` translates a :class:`~statemachine.io.model.StateMachineDefinition`
+into the ``kwargs`` accepted by :func:`~statemachine.io.create_machine_class_from_definition`,
+compiling guards and executable content through an
+:class:`~statemachine.io.evaluators.Evaluator` (secure by default).
+
+It is format-neutral and runtime-agnostic: anything that is a runtime concern
+(system-variable injection, the invoke bootstrap, building invokers) is requested from a
+:class:`RuntimeHooks` collaborator, so the builder never imports the concrete runtime and
+there is no import cycle.
+"""
+
+from typing import Any
+from typing import Protocol
+
+from .actions import Cond
+from .actions import DoneDataCallable
+from .actions import ExecuteBlock
+from .actions import create_datamodel_action_callable
+from .class_factory import HistoryDefinition
+from .class_factory import StateDefinition
+from .class_factory import TransitionDict
+from .class_factory import TransitionsList
+from .evaluators import Evaluator
+from .model import HistoryState
+from .model import InvokeDefinition
+from .model import State
+from .model import StateMachineDefinition
+from .model import Transition
+
+
+class RuntimeHooks(Protocol):
+    """Runtime concerns the builder delegates back to the interpreter."""
+
+    def initial_enter_prefix(
+        self, is_invoked: bool
+    ) -> list:  # pragma: no cover - structural Protocol
+        """Callbacks to insert at the front of the initial state's ``enter`` list."""
+        ...
+
+    def definition_kwargs(self, definition) -> dict:  # pragma: no cover - structural Protocol
+        """Extra kwargs for ``create_machine_class_from_definition`` (e.g. ``prepare_event``)."""
+        ...
+
+    def make_invoker(
+        self, invoke_def: InvokeDefinition
+    ) -> Any:  # pragma: no cover - structural Protocol
+        """Build the invoke handler for an ``<invoke>`` definition."""
+        ...
+
+
+class DefinitionBuilder:
+    """Translates the neutral IR into ``create_machine_class_from_definition`` kwargs."""
+
+    def __init__(self, *, evaluator: Evaluator, hooks: RuntimeHooks):
+        self._evaluator = evaluator
+        self._hooks = hooks
+
+    def build_class_kwargs(self, definition: StateMachineDefinition, *, is_invoked: bool) -> dict:
+        states_dict = self._process_states(definition.states)
+
+        # Find the initial state for inserting init callbacks
+        try:
+            initial_state = next(s for s in iter(states_dict.values()) if s.get("initial"))
+        except StopIteration:
+            initial_state = next(iter(states_dict.values()))
+
+        if "enter" not in initial_state:
+            initial_state["enter"] = []
+
+        insert_pos = 0
+        # Runtime callbacks that must run before the datamodel (e.g. invoke init).
+        for callback in self._hooks.initial_enter_prefix(is_invoked):
+            initial_state["enter"].insert(insert_pos, callback)  # type: ignore[union-attr]
+            insert_pos += 1
+
+        # Process datamodel (initial variables)
+        if definition.datamodel:
+            datamodel = create_datamodel_action_callable(definition.datamodel, self._evaluator)
+            if datamodel:  # pragma: no branch – parse guarantees non-empty
+                if isinstance(  # pragma: no branch – always a list from lines above
+                    initial_state["enter"], list
+                ):
+                    initial_state["enter"].insert(insert_pos, datamodel)  # type: ignore[arg-type]
+
+        return {"states": states_dict, **self._hooks.definition_kwargs(definition)}
+
+    def _process_history(self, history: dict[str, HistoryState]) -> dict[str, HistoryDefinition]:
+        states_dict: dict[str, HistoryDefinition] = {}
+        for state_id, state in history.items():
+            state_dict = HistoryDefinition()
+            state_dict["type"] = state.type
+            if state.transitions:
+                state_dict["transitions"] = self._process_transitions(state.transitions)
+            states_dict[state_id] = state_dict
+        return states_dict
+
+    def _process_states(self, states: dict[str, State]) -> dict[str, StateDefinition]:
+        return {state_id: self._process_state(state) for state_id, state in states.items()}
+
+    def _process_state(self, state: State) -> StateDefinition:  # noqa: C901
+        state_dict = StateDefinition()
+        if state.initial:
+            state_dict["initial"] = True
+        if state.final:
+            state_dict["final"] = True
+        if state.parallel:
+            state_dict["parallel"] = True
+
+        # Process enter actions (executable content first, then callback refs)
+        enter_callables: list = [
+            ExecuteBlock(content, self._evaluator)
+            for content in state.onentry
+            if not content.is_empty
+        ]
+        enter_callables.extend(state.enter_refs)
+        if enter_callables:
+            state_dict["enter"] = enter_callables
+        if state.final and state.donedata:
+            state_dict["donedata"] = DoneDataCallable(state.donedata, self._evaluator)
+
+        # Process exit actions (executable content first, then callback refs)
+        exit_callables: list = [
+            ExecuteBlock(content, self._evaluator)
+            for content in state.onexit
+            if not content.is_empty
+        ]
+        exit_callables.extend(state.exit_refs)
+        if exit_callables:
+            state_dict["exit"] = exit_callables
+
+        # Process transitions
+        if state.transitions:
+            state_dict["transitions"] = self._process_transitions(state.transitions)
+
+        # Process invoke elements (delegated to the runtime)
+        if state.invocations:
+            invokers = [self._hooks.make_invoker(inv) for inv in state.invocations]
+            state_dict["invoke"] = invokers  # type: ignore[typeddict-unknown-key]
+
+        if state.states:
+            state_dict["states"] = self._process_states(state.states)
+
+        if state.history:
+            state_dict["history"] = self._process_history(state.history)
+
+        return state_dict
+
+    def _process_transitions(self, transitions: list[Transition]):
+        result: TransitionsList = []
+        for transition in transitions:
+            event = transition.event or None
+            transition_dict: TransitionDict = {
+                "event": event,
+                "target": transition.target,
+                "internal": transition.internal,
+                "initial": transition.initial,
+            }
+
+            # Process guards (cond / unless) as compiled expressions
+            if transition.cond:
+                transition_dict["cond"] = self._compile_guard(transition.cond)
+            if transition.unless:
+                transition_dict["unless"] = self._compile_guard(transition.unless)
+
+            # Each callback slot is executable content (compiled first) followed by the
+            # callback references. `on` mirrors SCXML; `before`/`after` are native-only
+            # library lifecycle slots that accept the same vocabulary.
+            on = self._lifecycle_callables(transition.on, transition.on_refs)
+            if on:
+                transition_dict["on"] = on if len(on) > 1 else on[0]
+            before = self._lifecycle_callables(transition.before, transition.before_refs)
+            if before:
+                transition_dict["before"] = before if len(before) > 1 else before[0]
+            after = self._lifecycle_callables(transition.after, transition.after_refs)
+            if after:
+                transition_dict["after"] = after if len(after) > 1 else after[0]
+
+            result.append(transition_dict)
+        return result
+
+    def _lifecycle_callables(self, content, refs: list) -> list:
+        """Compose a transition callback slot: executable content (if any) then named refs."""
+        callables: list = []
+        if content and not content.is_empty:
+            callables.append(ExecuteBlock(content, self._evaluator))
+        callables.extend(refs)
+        return callables
+
+    def _compile_guard(self, expr) -> Any:
+        """Compile a guard expression (or list of them) into Cond callables."""
+        if isinstance(expr, (list, tuple)):
+            return [Cond.create(e, self._evaluator) for e in expr]
+        return Cond.create(expr, self._evaluator)

statemachine/io/class_factory.py

@@ -0,0 +1,236 @@
+"""Build a :class:`~statemachine.statemachine.StateChart` class from a dict definition.
+
+This is the lowest layer of the IO stack: it turns a plain mapping (the ``TransitionDict`` /
+``StateDefinition`` schema declared here) into a concrete ``StateChart`` subclass via the
+:class:`~statemachine.factory.StateMachineMetaclass`. The higher layers (the format readers,
+the :class:`~statemachine.io.builder.DefinitionBuilder`, the
+:class:`~statemachine.io.interpreter.Interpreter`) compile their neutral IR down to this
+schema and call :func:`create_machine_class_from_definition`.
+
+It depends only on the core (``factory``/``state``/``statemachine``/``transition``), never on
+the loader stack, so importing it never triggers an import cycle.
+"""
+
+from collections.abc import Mapping
+from collections.abc import Sequence
+from typing import Any
+from typing import Protocol
+from typing import TypedDict
+from typing import cast
+
+from ..factory import StateMachineMetaclass
+from ..state import HistoryState
+from ..state import State
+from ..statemachine import StateChart
+from ..transition import Transition
+from ..transition_list import TransitionList
+
+
+class ActionProtocol(Protocol):  # pragma: no cover
+    def __call__(self, *args, **kwargs) -> Any: ...
+
+
+class TransitionDict(TypedDict, total=False):
+    target: "str | None"
+    event: "str | None"
+    internal: bool
+    initial: bool
+    validators: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
+    cond: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
+    unless: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
+    on: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
+    before: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
+    after: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
+
+
+TransitionsDict = dict["str | None", list[TransitionDict]]
+TransitionsList = list[TransitionDict]
+
+
+class BaseStateKwargs(TypedDict, total=False):
+    name: str
+    value: Any
+    initial: bool
+    final: bool
+    parallel: bool
+    enter: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
+    exit: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
+    donedata: "ActionProtocol | None"
+
+
+class StateKwargs(BaseStateKwargs, total=False):
+    states: list[State]
+    history: list[HistoryState]
+
+
+class HistoryKwargs(TypedDict, total=False):
+    name: str
+    value: Any
+    type: str
+
+
+class HistoryDefinition(HistoryKwargs, total=False):
+    on: TransitionsDict
+    transitions: TransitionsList
+
+
+class StateDefinition(BaseStateKwargs, total=False):
+    states: dict[str, "StateDefinition"]
+    history: dict[str, "HistoryDefinition"]
+    on: TransitionsDict
+    transitions: TransitionsList
+
+
+def _parse_history(
+    states: Mapping[str, "HistoryKwargs |HistoryDefinition"],
+) -> tuple[dict[str, HistoryState], dict[str, dict]]:
+    states_instances: dict[str, HistoryState] = {}
+    events_definitions: dict[str, dict] = {}
+    for state_id, state_definition in states.items():
+        state_definition = cast(HistoryDefinition, state_definition)
+        transition_defs = state_definition.pop("on", {})
+        transition_list = state_definition.pop("transitions", [])
+        if transition_list:
+            transition_defs[None] = transition_list
+
+        if transition_defs:
+            events_definitions[state_id] = transition_defs
+
+        state_definition = cast(HistoryKwargs, state_definition)
+        states_instances[state_id] = HistoryState(**state_definition)
+
+    return (states_instances, events_definitions)
+
+
+def _parse_states(
+    states: Mapping[str, "BaseStateKwargs | StateDefinition"],
+) -> tuple[dict[str, State], dict[str, dict]]:
+    states_instances: dict[str, State] = {}
+    events_definitions: dict[str, dict] = {}
+
+    for state_id, state_definition in states.items():
+        # Process nested states. Replaces `states` as a definition by a list of `State` instances.
+        state_definition = cast(StateDefinition, state_definition)
+
+        # pop the nested states, history and transitions definitions
+        inner_states_defs: dict[str, StateDefinition] = state_definition.pop("states", {})
+        inner_history_defs: dict[str, HistoryDefinition] = state_definition.pop("history", {})
+        transition_defs = state_definition.pop("on", {})
+        transition_list = state_definition.pop("transitions", [])
+        if transition_list:
+            transition_defs[None] = transition_list
+
+        if inner_states_defs:
+            inner_states, inner_events = _parse_states(inner_states_defs)
+
+            top_level_states = [
+                state._set_id(state_id)
+                for state_id, state in inner_states.items()
+                if not state.parent
+            ]
+            state_definition["states"] = top_level_states  # type: ignore
+            states_instances.update(inner_states)
+            events_definitions.update(inner_events)
+
+        if inner_history_defs:
+            inner_history, inner_events = _parse_history(inner_history_defs)
+
+            top_level_history = [
+                state._set_id(state_id)
+                for state_id, state in inner_history.items()
+                if not state.parent
+            ]
+            state_definition["history"] = top_level_history  # type: ignore
+            states_instances.update(inner_history)
+            events_definitions.update(inner_events)
+
+        if transition_defs:
+            events_definitions[state_id] = transition_defs
+
+        state_definition = cast(BaseStateKwargs, state_definition)
+        states_instances[state_id] = State(**state_definition)
+
+    return (states_instances, events_definitions)
+
+
+def create_machine_class_from_definition(
+    name: str, states: Mapping[str, "StateKwargs | StateDefinition"], **definition
+) -> "type[StateChart]":  # noqa: C901
+    """Create a StateChart class dynamically from a dictionary definition.
+
+    Args:
+        name: The class name for the generated state machine.
+        states: A mapping of state IDs to state definitions. Each state definition
+            can include ``initial``, ``final``, ``parallel``, ``name``, ``value``,
+            ``enter``/``exit`` callbacks, ``donedata``, nested ``states``,
+            ``history``, and transitions via ``on`` (event-triggered) or
+            ``transitions`` (eventless).
+        **definition: Additional keyword arguments passed to the metaclass
+            (e.g., ``validate_final_reachability=False``).
+
+    Returns:
+        A new StateChart subclass configured with the given states and transitions.
+
+    Example:
+
+    >>> machine = create_machine_class_from_definition(
+    ...     "TrafficLightMachine",
+    ...     **{
+    ...         "states": {
+    ...             "green": {"initial": True, "on": {"change": [{"target": "yellow"}]}},
+    ...             "yellow": {"on": {"change": [{"target": "red"}]}},
+    ...             "red": {"on": {"change": [{"target": "green"}]}},
+    ...         },
+    ...     }
+    ... )
+
+    """
+    states_instances, events_definitions = _parse_states(states)
+
+    events: dict[str, TransitionList] = {}
+    for state_id, state_events in events_definitions.items():
+        for event_name, transitions_data in state_events.items():
+            for transition_data in transitions_data:
+                source = states_instances[state_id]
+
+                target_state_id = transition_data["target"]
+                transition_event_name = transition_data.get("event")
+                if event_name is not None and transition_event_name is not None:
+                    transition_event_name = f"{event_name} {transition_event_name}"
+                elif event_name is not None:
+                    transition_event_name = event_name
+
+                transition_kwargs = {
+                    "event": transition_event_name,
+                    "internal": transition_data.get("internal"),
+                    "initial": transition_data.get("initial"),
+                    "validators": transition_data.get("validators"),
+                    "cond": transition_data.get("cond"),
+                    "unless": transition_data.get("unless"),
+                    "on": transition_data.get("on"),
+                    "before": transition_data.get("before"),
+                    "after": transition_data.get("after"),
+                }
+
+                # Handle multi-target transitions (space-separated target IDs)
+                if target_state_id and isinstance(target_state_id, str) and " " in target_state_id:
+                    target_ids = target_state_id.split()
+                    targets = [states_instances[tid] for tid in target_ids]
+                    t = Transition(source, target=targets, **transition_kwargs)
+                    source.transitions.add_transitions(t)
+                    transition = TransitionList([t])
+                else:
+                    target = states_instances[target_state_id] if target_state_id else None
+                    transition = source.to(target, **transition_kwargs)
+
+                if event_name in events:
+                    events[event_name] |= transition
+                elif event_name is not None:
+                    events[event_name] = transition
+
+    top_level_states = {
+        state_id: state for state_id, state in states_instances.items() if not state.parent
+    }
+
+    attrs_mapper = {**definition, **top_level_states, **events}
+    return StateMachineMetaclass(name, (StateChart,), attrs_mapper)  # type: ignore[return-value]