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

statemachine/io/{scxml/actions.py → actions.py}

@@ -1,49 +1,45 @@
-import html
+"""Turn neutral-IR :mod:`~statemachine.io.model` actions into executable callables.
+
+Each :class:`~statemachine.io.model.Action` is compiled into a callable by
+:func:`create_action_callable`, using an :class:`~statemachine.io.evaluators.Evaluator`
+to evaluate the expression/script strings it carries (secure by default). This layer
+is format-neutral: it is shared by the SCXML, JSON and YAML readers.
+"""
+
 import logging
 import re
-from dataclasses import dataclass
+from collections.abc import Callable
 from itertools import chain
 from typing import Any
-from typing import Callable
 from uuid import uuid4
 
-from ...event import BoundEvent
-from ...event import Event
-from ...event import _event_data_kwargs
-from ...spec_parser import InState
-from ...statemachine import StateChart
-from .parser import Action
-from .parser import AssignAction
-from .parser import IfAction
-from .parser import LogAction
-from .parser import RaiseAction
-from .parser import SendAction
-from .schema import CancelAction
-from .schema import DataItem
-from .schema import DataModel
-from .schema import DoneData
-from .schema import ExecutableContent
-from .schema import ForeachAction
-from .schema import Param
-from .schema import ScriptAction
+from ..event import BoundEvent
+from ..event import Event
+from ..statemachine import StateChart
+from .evaluators import Evaluator
+from .evaluators import protected_attrs
+from .model import Action
+from .model import AssignAction
+from .model import CancelAction
+from .model import DataItem
+from .model import DataModel
+from .model import DoneData
+from .model import ExecutableContent
+from .model import ForeachAction
+from .model import IfAction
+from .model import LogAction
+from .model import Param
+from .model import RaiseAction
+from .model import ScriptAction
+from .model import SendAction
 
 logger = logging.getLogger(__name__)
 _debug = logger.debug if logger.isEnabledFor(logging.DEBUG) else lambda *a, **k: None
-protected_attrs = _event_data_kwargs | {"_sessionid", "_ioprocessors", "_name", "_event"}
 
 
 class ParseTime:
-    pattern = re.compile(r"(\d+)?(\.\d+)?(s|ms)")
-
-    @classmethod
-    def parse_delay(cls, delay: "str | None", delayexpr: "str | None", **kwargs):
-        if delay:
-            return cls.time_in_ms(delay)
-        elif delayexpr:
-            delay_expr_expanded = cls.replace(delayexpr)
-            return cls.time_in_ms(_eval(delay_expr_expanded, **kwargs))
-
-        return 0
+    pattern = re.compile(r"(\d+(?:\.\d+)?|\.\d+)(s|ms)")
+    """CSS2 time literal: a number (``5``, ``1.5``, ``.5``) followed by ``s`` or ``ms``."""
 
     @classmethod
     def replace(cls, expr: str) -> str:
@@ -83,102 +79,6 @@ class ParseTime:
                 raise ValueError(f"Invalid time unit in: {expr}") from e
 
 
-@dataclass
-class _Data:
-    kwargs: dict
-
-    def __getattr__(self, name):
-        return self.kwargs.get(name, None)
-
-    def get(self, name, default=None):
-        return self.kwargs.get(name, default)
-
-
-class OriginTypeSCXML(str):
-    """The origintype of the :ref:`Event` as specified by the SCXML namespace."""
-
-    def __eq__(self, other):
-        return other == "http://www.w3.org/TR/scxml/#SCXMLEventProcessor" or other == "scxml"
-
-
-class EventDataWrapper:
-    origin: str = ""
-    origintype: str = OriginTypeSCXML("scxml")
-    """The origintype of the :ref:`Event` as specified by the SCXML namespace."""
-    invokeid: str = ""
-    """If this event is generated from an invoked child process, the SCXML Processor MUST set
-    this field to the invoke id of the invocation that triggered the child process.
-    Otherwise it MUST leave it blank.
-    """
-
-    def __init__(self, event_data=None, *, trigger_data=None):
-        self.event_data = event_data
-        if trigger_data is not None:
-            self.trigger_data = trigger_data
-        elif event_data is not None:
-            self.trigger_data = event_data.trigger_data
-        else:
-            raise ValueError("Either event_data or trigger_data must be provided")
-
-        td = self.trigger_data
-        self.sendid = td.send_id
-        self.invokeid = td.kwargs.get("_invokeid", "")
-        if td.event is None or td.event.internal:
-            if "error.execution" == td.event:
-                self.type = "platform"
-            else:
-                self.type = "internal"
-                self.origintype = ""
-        else:
-            self.type = "external"
-
-    @classmethod
-    def from_trigger_data(cls, trigger_data):
-        """Create an EventDataWrapper directly from a TriggerData (no EventData needed)."""
-        return cls(trigger_data=trigger_data)
-
-    def __getattr__(self, name):
-        if self.event_data is not None:
-            return getattr(self.event_data, name)
-        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
-
-    def __eq__(self, value):
-        "This makes SCXML test 329 pass. It assumes that the event is the same instance"
-        return isinstance(value, EventDataWrapper)
-
-    @property
-    def name(self):
-        if self.event_data is not None:
-            return self.event_data.event
-        return str(self.trigger_data.event) if self.trigger_data.event else None
-
-    @property
-    def data(self):
-        "Property used by the SCXML namespace"
-        td = self.trigger_data
-        if td.kwargs:
-            return _Data(td.kwargs)
-        elif td.args and len(td.args) == 1:
-            return td.args[0]
-        elif td.args:
-            return td.args
-        else:
-            return None
-
-
-def _eval(expr: str, **kwargs) -> Any:
-    if "machine" in kwargs:
-        kwargs.update(
-            **{
-                k: v
-                for k, v in kwargs["machine"].model.__dict__.items()
-                if k not in protected_attrs
-            }
-        )
-        kwargs["In"] = InState(kwargs["machine"])
-    return eval(expr, {}, kwargs)
-
-
 class CallableAction:
     action: Any
 
@@ -207,81 +107,61 @@ class Cond(CallableAction):
     """Evaluates a condition like a predicate and returns True or False."""
 
     @classmethod
-    def create(cls, cond: "str | None", processor=None):
-        cond = cls._normalize(cond)
+    def create(cls, cond: "str | None", evaluator: Evaluator, processor=None):
         if cond is None:
             return None
+        return cls(cond, evaluator, processor)
 
-        return cls(cond, processor)
-
-    def __init__(self, cond: str, processor=None):
+    def __init__(self, cond: str, evaluator: Evaluator, processor=None):
         super().__init__()
         self.action = cond
         self.processor = processor
+        self._cond = evaluator.compile_bool(cond)
 
     def __call__(self, *args, **kwargs):
-        result = _eval(self.action, **kwargs)
+        result = self._cond(*args, **kwargs)
         _debug("Cond %s -> %s", self.action, result)
         return result
 
-    @staticmethod
-    def _normalize(cond: "str | None") -> "str | None":
-        """
-        Normalizes a JavaScript-like condition string to be compatible with Python's eval.
-        """
-        if cond is None:
-            return None
 
-        # Decode HTML entities, to allow XML syntax like `Var1<Var2`
-        cond = html.unescape(cond)
-
-        replacements = {
-            "true": "True",
-            "false": "False",
-            "null": "None",
-            "===": "==",
-            "!==": "!=",
-            "&&": "and",
-            "||": "or",
-        }
-
-        # Use regex to replace each JavaScript-like token with its Python equivalent
-        pattern = re.compile(r"\b(?:true|false|null)\b|===|!==|&&|\|\|")
-        return pattern.sub(lambda match: replacements[match.group(0)], cond)
-
-
-def create_action_callable(action: Action) -> Callable:
-    if isinstance(action, RaiseAction):
-        return create_raise_action_callable(action)
-    elif isinstance(action, AssignAction):
-        return Assign(action)
-    elif isinstance(action, LogAction):
-        return Log(action)
-    elif isinstance(action, IfAction):
-        return create_if_action_callable(action)
-    elif isinstance(action, ForeachAction):
-        return create_foreach_action_callable(action)
-    elif isinstance(action, SendAction):
-        return create_send_action_callable(action)
-    elif isinstance(action, CancelAction):
-        return create_cancel_action_callable(action)
-    elif isinstance(action, ScriptAction):
-        return create_script_action_callable(action)
-    else:
-        raise ValueError(f"Unknown action type: {type(action)}")
+def create_action_callable(action: Action, evaluator: Evaluator) -> Callable:
+    match action:
+        case RaiseAction():
+            return create_raise_action_callable(action)
+        case AssignAction():
+            return Assign(action, evaluator)
+        case LogAction():
+            return Log(action, evaluator)
+        case IfAction():
+            return create_if_action_callable(action, evaluator)
+        case ForeachAction():
+            return create_foreach_action_callable(action, evaluator)
+        case SendAction():
+            return create_send_action_callable(action, evaluator)
+        case CancelAction():
+            return create_cancel_action_callable(action, evaluator)
+        case ScriptAction():
+            return create_script_action_callable(action, evaluator)
+        case _:
+            raise ValueError(f"Unknown action type: {type(action)}")
 
 
 class Assign(CallableAction):
-    def __init__(self, action: AssignAction):
+    def __init__(self, action: AssignAction, evaluator: Evaluator):
         super().__init__()
         self.action = action
+        self._expr = (
+            evaluator.compile_value(action.expr)
+            if action.child_xml is None and action.expr is not None
+            else None
+        )
 
     def __call__(self, *args, **kwargs):
         machine: StateChart = kwargs["machine"]
         if self.action.child_xml is not None:
             value = self.action.child_xml
         else:
-            value = _eval(self.action.expr, **kwargs)
+            value = self._expr(*args, **kwargs)  # type: ignore[misc]
 
         *path, attr = self.action.location.split(".")
         obj = machine.model
@@ -303,12 +183,13 @@ class Assign(CallableAction):
 
 
 class Log(CallableAction):
-    def __init__(self, action: LogAction):
+    def __init__(self, action: LogAction, evaluator: Evaluator):
         super().__init__()
         self.action = action
+        self._expr = evaluator.compile_value(action.expr) if action.expr else None
 
     def __call__(self, *args, **kwargs):
-        value = _eval(self.action.expr, **kwargs) if self.action.expr else None
+        value = self._expr(*args, **kwargs) if self._expr else None
 
         if self.action.label and self.action.expr is not None:
             msg = f"{self.action.label}: {value!r}"
@@ -319,11 +200,11 @@ class Log(CallableAction):
         print(msg)
 
 
-def create_if_action_callable(action: IfAction) -> Callable:
+def create_if_action_callable(action: IfAction, evaluator: Evaluator) -> Callable:
     branches = [
         (
-            Cond.create(branch.cond),
-            [create_action_callable(action) for action in branch.actions],
+            Cond.create(branch.cond, evaluator),
+            [create_action_callable(action, evaluator) for action in branch.actions],
         )
         for branch in action.branches
     ]
@@ -349,14 +230,15 @@ def create_if_action_callable(action: IfAction) -> Callable:
     return if_action
 
 
-def create_foreach_action_callable(action: ForeachAction) -> Callable:
-    child_actions = [create_action_callable(act) for act in action.content.actions]
+def create_foreach_action_callable(action: ForeachAction, evaluator: Evaluator) -> Callable:
+    child_actions = [create_action_callable(act, evaluator) for act in action.content.actions]
+    array_expr = evaluator.compile_value(action.array)
 
     def foreach_action(*args, **kwargs):
         machine: StateChart = kwargs["machine"]
         try:
             # Evaluate the array expression to get the iterable
-            array = _eval(action.array, **kwargs)
+            array = array_expr(*args, **kwargs)
         except Exception as e:
             raise ValueError(f"Error evaluating <foreach> 'array' expression: {e}") from e
 
@@ -388,17 +270,10 @@ def create_raise_action_callable(action: RaiseAction) -> Callable:
     return raise_action
 
 
-def _send_to_parent(action: SendAction, **kwargs):
-    """Route a <send target="#_parent"> to the parent machine via _invoke_session."""
+def _resolve_event_and_params(action: SendAction, evaluator: Evaluator, **kwargs):
+    """Evaluate the event name, namelist and params for a <send> at call time."""
     machine = kwargs["machine"]
-    session = getattr(machine, "_invoke_session", None)
-    if session is None:
-        logger.warning(
-            "<send target='#_parent'> ignored: machine %r has no _invoke_session",
-            machine.name,
-        )
-        return
-    event = action.event or _eval(action.eventexpr, **kwargs)  # type: ignore[arg-type]
+    event = action.event or evaluator.compile_value(action.eventexpr)(**kwargs)  # type: ignore[arg-type]
     names = []
     for name in (action.namelist or "").strip().split():
         if not hasattr(machine.model, name):
@@ -408,41 +283,46 @@ def _send_to_parent(action: SendAction, **kwargs):
     for param in chain(names, action.params):
         if param.expr is None:
             continue
-        params_values[param.name] = _eval(param.expr, **kwargs)
+        params_values[param.name] = evaluator.compile_value(param.expr)(**kwargs)
+    return event, params_values
+
+
+def _send_to_parent(action: SendAction, evaluator: Evaluator, **kwargs):
+    """Route a <send target="#_parent"> to the parent machine via _invoke_session."""
+    machine = kwargs["machine"]
+    session = getattr(machine, "_invoke_session", None)
+    if session is None:
+        logger.warning(
+            "<send target='#_parent'> ignored: machine %r has no _invoke_session",
+            machine.name,
+        )
+        return
+    event, params_values = _resolve_event_and_params(action, evaluator, **kwargs)
     session.send_to_parent(event, **params_values)
 
 
-def _send_to_invoke(action: SendAction, invokeid: str, **kwargs):
+def _send_to_invoke(action: SendAction, invokeid: str, evaluator: Evaluator, **kwargs):
     """Route a <send target="#_<invokeid>"> to the invoked child session."""
     machine: StateChart = kwargs["machine"]
-    event = action.event or _eval(action.eventexpr, **kwargs)  # type: ignore[arg-type]
-    names = []
-    for name in (action.namelist or "").strip().split():
-        if not hasattr(machine.model, name):
-            raise NameError(f"Namelist variable '{name}' not found on model")
-        names.append(Param(name=name, expr=name))
-    params_values = {}
-    for param in chain(names, action.params):
-        if param.expr is None:
-            continue
-        params_values[param.name] = _eval(param.expr, **kwargs)
+    event, params_values = _resolve_event_and_params(action, evaluator, **kwargs)
     if not machine._engine._invoke_manager.send_to_child(invokeid, event, **params_values):
         # Per SCXML spec: if target is not reachable → error.communication
         BoundEvent("error.communication", internal=True, _sm=machine).put()
 
 
-def create_send_action_callable(action: SendAction) -> Callable:  # noqa: C901
+def create_send_action_callable(  # noqa: C901
+    action: SendAction, evaluator: Evaluator
+) -> Callable:
     content: Any = ()
     _valid_targets = (None, "#_internal", "internal", "#_parent", "parent")
     if action.content:
-        try:
-            content = (eval(action.content, {}, {}),)
-        except (NameError, SyntaxError, TypeError):
-            content = (action.content,)
+        content = (evaluator.eval_literal(action.content),)
+    delay_expr = (
+        evaluator.compile_value(ParseTime.replace(action.delayexpr)) if action.delayexpr else None
+    )
 
     def send_action(*args, **kwargs):  # noqa: C901
         machine: StateChart = kwargs["machine"]
-        event = action.event or _eval(action.eventexpr, **kwargs)  # type: ignore[arg-type]
         target = action.target if action.target else None
 
         if action.type and action.type != "http://www.w3.org/TR/scxml/#SCXMLEventProcessor":
@@ -457,7 +337,7 @@ def create_send_action_callable(action: SendAction) -> Callable:  # noqa: C901
                 BoundEvent("error.communication", internal=True, _sm=machine).put()
             elif target and target.startswith("#_"):
                 # #_<invokeid> → route to invoked child session
-                _send_to_invoke(action, target[2:], **kwargs)
+                _send_to_invoke(action, target[2:], evaluator, **kwargs)
             else:
                 # Invalid target expression → error.execution (raised as exception)
                 raise ValueError(f"Invalid target: {target}. Must be one of {_valid_targets}")
@@ -465,7 +345,7 @@ def create_send_action_callable(action: SendAction) -> Callable:  # noqa: C901
 
         # Handle #_parent target — route to parent via _invoke_session
         if target == "#_parent":
-            _send_to_parent(action, **kwargs)
+            _send_to_parent(action, evaluator, **kwargs)
             return
 
         internal = target in ("#_internal", "internal")
@@ -477,20 +357,15 @@ def create_send_action_callable(action: SendAction) -> Callable:  # noqa: C901
             send_id = uuid4().hex
             setattr(machine.model, action.idlocation, send_id)
 
-        delay = ParseTime.parse_delay(action.delay, action.delayexpr, **kwargs)
+        delay = 0.0
+        if action.delay:
+            delay = ParseTime.time_in_ms(action.delay)
+        elif delay_expr is not None:
+            delay = ParseTime.time_in_ms(delay_expr(**kwargs))
 
         # Per SCXML spec, if namelist evaluation causes an error (e.g., variable not found),
         # the send MUST NOT be dispatched and error.execution is raised.
-        names = []
-        for name in (action.namelist or "").strip().split():
-            if not hasattr(machine.model, name):
-                raise NameError(f"Namelist variable '{name}' not found on model")
-            names.append(Param(name=name, expr=name))
-        params_values = {}
-        for param in chain(names, action.params):
-            if param.expr is None:
-                continue
-            params_values[param.name] = _eval(param.expr, **kwargs)
+        event, params_values = _resolve_event_and_params(action, evaluator, **kwargs)
 
         Event(id=event, delay=delay, internal=internal, _sm=machine).put(
             *content,
@@ -502,13 +377,15 @@ def create_send_action_callable(action: SendAction) -> Callable:  # noqa: C901
     return send_action
 
 
-def create_cancel_action_callable(action: CancelAction) -> Callable:
+def create_cancel_action_callable(action: CancelAction, evaluator: Evaluator) -> Callable:
+    sendidexpr = evaluator.compile_value(action.sendidexpr) if action.sendidexpr else None
+
     def cancel_action(*args, **kwargs):
         machine: StateChart = kwargs["machine"]
         if action.sendid:
             send_id = action.sendid
-        elif action.sendidexpr:
-            send_id = _eval(action.sendidexpr, **kwargs)
+        elif sendidexpr is not None:
+            send_id = sendidexpr(*args, **kwargs)
         else:
             raise ValueError("CancelAction must have either 'sendid' or 'sendidexpr'")
         # Implement cancel logic if necessary
@@ -519,47 +396,22 @@ def create_cancel_action_callable(action: CancelAction) -> Callable:
     return cancel_action
 
 
-def create_script_action_callable(action: ScriptAction) -> Callable:
-    def script_action(*args, **kwargs):
-        machine: StateChart = kwargs["machine"]
-        local_vars = {
-            **machine.model.__dict__,
-        }
-        exec(action.content, {}, local_vars)
+def create_script_action_callable(action: ScriptAction, evaluator: Evaluator) -> Callable:
+    # In the restricted (default) evaluator this raises InvalidDefinition at parse
+    # time; <script> only runs under trusted=True.
+    script = evaluator.compile_script(action.content)
 
-        # Assign the resulting variables to the state machine's model
-        for var_name, value in local_vars.items():
-            setattr(machine.model, var_name, value)
+    def script_action(*args, **kwargs):
+        script(*args, **kwargs)
 
     script_action.action = action  # type: ignore[attr-defined]
     return script_action
 
 
-def create_invoke_init_callable() -> Callable:
-    """Create a callback that extracts invoke-specific kwargs and stores them on the machine.
-
-    This is always inserted at position 0 in the initial state's onentry list by the
-    SCXML processor, so that ``_invoke_session`` and ``_invoke_params`` are handled
-    before any other callbacks run — even for SMs without a ``<datamodel>``.
-    """
-    initialized = False
-
-    def invoke_init(*args, **kwargs):
-        nonlocal initialized
-        if initialized:
-            return
-        initialized = True
-        machine = kwargs.get("machine")
-        if machine is not None:
-            # Use get() not pop(): each callback receives a copy of kwargs
-            # (via EventData.extended_kwargs), so pop would be misleading.
-            machine._invoke_params = kwargs.get("_invoke_params")
-            machine._invoke_session = kwargs.get("_invoke_session")
-
-    return invoke_init
-
+def _create_dataitem_callable(action: DataItem, evaluator: Evaluator) -> Callable:
+    expr_fn = evaluator.compile_value(action.expr) if action.expr else None
+    content_fn = evaluator.compile_value(action.content) if action.content else None
 
-def _create_dataitem_callable(action: DataItem) -> Callable:
     def data_initializer(**kwargs):
         machine: StateChart = kwargs["machine"]
 
@@ -569,16 +421,16 @@ def _create_dataitem_callable(action: DataItem) -> Callable:
             setattr(machine.model, action.id, invoke_params[action.id])
             return
 
-        if action.expr:
+        if expr_fn is not None:
             try:
-                value = _eval(action.expr, **kwargs)
+                value = expr_fn(**kwargs)
             except Exception:
                 setattr(machine.model, action.id, None)
                 raise
 
-        elif action.content:
+        elif content_fn is not None:
             try:
-                value = _eval(action.content, **kwargs)
+                value = content_fn(**kwargs)
             except Exception:
                 value = action.content
         else:
@@ -589,9 +441,11 @@ def _create_dataitem_callable(action: DataItem) -> Callable:
     return data_initializer
 
 
-def create_datamodel_action_callable(action: DataModel) -> "Callable | None":
-    data_elements = [_create_dataitem_callable(item) for item in action.data]
-    data_elements.extend([create_script_action_callable(script) for script in action.scripts])
+def create_datamodel_action_callable(action: DataModel, evaluator: Evaluator) -> "Callable | None":
+    data_elements = [_create_dataitem_callable(item, evaluator) for item in action.data]
+    data_elements.extend(
+        [create_script_action_callable(script, evaluator) for script in action.scripts]
+    )
 
     if not data_elements:
         return None
@@ -613,10 +467,12 @@ def create_datamodel_action_callable(action: DataModel) -> "Callable | None":
 class ExecuteBlock(CallableAction):
     """Parses the children as <executable> content XML into a callable."""
 
-    def __init__(self, content: ExecutableContent):
+    def __init__(self, content: ExecutableContent, evaluator: Evaluator):
         super().__init__()
         self.action = content
-        self.action_callables = [create_action_callable(action) for action in content.actions]
+        self.action_callables = [
+            create_action_callable(action, evaluator) for action in content.actions
+        ]
 
     def __call__(self, *args, **kwargs):
         for action in self.action_callables:
@@ -626,25 +482,39 @@ class ExecuteBlock(CallableAction):
 class DoneDataCallable(CallableAction):
     """Evaluates <donedata> params/content and returns the data for done events."""
 
-    def __init__(self, donedata: DoneData):
+    def __init__(self, donedata: DoneData, evaluator: Evaluator):
         super().__init__()
         self.action = donedata
         self.donedata = donedata
+        self._content_expr = (
+            evaluator.compile_value(donedata.content_expr)
+            if donedata.content_expr is not None
+            else None
+        )
+        self._params = [
+            (
+                param.name,
+                evaluator.compile_value(param.expr)
+                if param.expr is not None
+                else evaluator.compile_value(param.location.strip()),  # type: ignore[union-attr]
+                param.location,
+            )
+            for param in donedata.params
+        ]
 
     def __call__(self, *args, **kwargs):
-        if self.donedata.content_expr is not None:
-            return _eval(self.donedata.content_expr, **kwargs)
+        if self._content_expr is not None:
+            return self._content_expr(*args, **kwargs)
 
         result = {}
-        for param in self.donedata.params:
-            if param.expr is not None:
-                result[param.name] = _eval(param.expr, **kwargs)
-            elif param.location is not None:  # pragma: no branch
-                location = param.location.strip()
+        for name, fn, location in self._params:
+            if location is None:
+                result[name] = fn(*args, **kwargs)
+            else:
                 try:
-                    result[param.name] = _eval(location, **kwargs)
+                    result[name] = fn(*args, **kwargs)
                 except Exception as e:
                     raise ValueError(
-                        f"<param> location '{location}' does not resolve to a valid value"
+                        f"<param> location '{location.strip()}' does not resolve to a valid value"
                     ) from e
         return result