feat: implement SCXML donedata support for final states

Parse <donedata> elements (<param> and <content>) from <final> states,
evaluate expressions at runtime, and pass the data correctly to
done.state.* events. Error cases (invalid expr/location) raise
error.execution per SCXML spec.

Fixes W3C conformance tests: 294, 298, 343, 488, 527, 528, 529.

Author: fgmacedo

statemachine/engines/base.py

@@ -590,23 +590,27 @@ def _enter_states(  # noqa: C901
                     parent = target.parent
                     grandparent = parent.parent
 
-                    donedata = {}
+                    donedata_args: tuple = ()
+                    donedata_kwargs: dict = {}
                     for item in on_entry_result:
                         if not item:
                             continue
-                        donedata.update(item)
+                        if isinstance(item, dict):
+                            donedata_kwargs.update(item)
+                        else:
+                            donedata_args = (item,)
 
                     BoundEvent(
                         f"done.state.{parent.id}",
                         _sm=self.sm,
                         internal=True,
-                    ).put(donedata=donedata)
+                    ).put(*donedata_args, **donedata_kwargs)
 
                     if grandparent and grandparent.parallel:
                         if all(self.is_in_final_state(child) for child in grandparent.states):
                             BoundEvent(
                                 f"done.state.{grandparent.id}", _sm=self.sm, internal=True
-                            ).put(donedata=donedata)
+                            ).put(*donedata_args, **donedata_kwargs)
         return result
 
     def compute_entry_set(

statemachine/io/scxml/actions.py

@@ -20,6 +20,7 @@
 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
@@ -138,8 +139,10 @@ def data(self):
             return _Data(self.trigger_data.kwargs)
         elif self.trigger_data.args and len(self.trigger_data.args) == 1:
             return self.trigger_data.args[0]
-        else:
+        elif self.trigger_data.args:
             return self.trigger_data.args
+        else:
+            return None
 
 
 def _eval(expr: str, **kwargs) -> Any:
@@ -502,3 +505,30 @@ def __call__(self, *args, **kwargs):
             action(*args, **kwargs)
 
         machine._processing_loop()
+
+
+class DoneDataCallable(CallableAction):
+    """Evaluates <donedata> params/content and returns the data for done events."""
+
+    def __init__(self, donedata: DoneData):
+        super().__init__()
+        self.action = donedata
+        self.donedata = donedata
+
+    def __call__(self, *args, **kwargs):
+        if self.donedata.content_expr is not None:
+            return _eval(self.donedata.content_expr, **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:
+                location = param.location.strip()
+                try:
+                    result[param.name] = _eval(location, **kwargs)
+                except Exception as e:
+                    raise ValueError(
+                        f"<param> location '{location}' does not resolve to a valid value"
+                    ) from e
+        return result

statemachine/io/scxml/parser.py

@@ -9,6 +9,7 @@
 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 HistoryState
@@ -183,9 +184,32 @@ def parse_state(  # noqa: C901
         child_history_state = parse_history(child_state_elem)
         state.history[child_history_state.id] = child_history_state
 
+    # Parse donedata (only valid on final states)
+    if is_final:
+        donedata_elem = state_elem.find("donedata")
+        if donedata_elem is not None:
+            state.donedata = parse_donedata(donedata_elem)
+
     return state
 
 
+def parse_donedata(element: ET.Element) -> DoneData:
+    """Parse a <donedata> element containing <param> and/or <content> children."""
+    params = []
+    content_expr = None
+    for child in element:
+        if child.tag == "param":
+            name = child.attrib["name"]
+            expr = child.attrib.get("expr")
+            location = child.attrib.get("location")
+            params.append(Param(name=name, expr=expr, location=location))
+        elif child.tag == "content":
+            content_expr = child.attrib.get("expr")
+            if content_expr is None and child.text:
+                content_expr = re.sub(r"\s+", " ", child.text).strip()
+    return DoneData(params=params, content_expr=content_expr)
+
+
 def parse_transition(trans_elem: ET.Element, initial: bool = False) -> Transition:
     target = trans_elem.get("target")
 

statemachine/io/scxml/processor.py

@@ -15,6 +15,7 @@
 from .. import TransitionsList
 from .. import create_machine_class_from_definition
 from .actions import Cond
+from .actions import DoneDataCallable
 from .actions import EventDataWrapper
 from .actions import ExecuteBlock
 from .actions import create_datamodel_action_callable
@@ -149,42 +150,44 @@ def _process_history(self, history: Dict[str, HistoryState]) -> Dict[str, Histor
     def _process_states(self, states: Dict[str, State]) -> Dict[str, StateDefinition]:
         states_dict: Dict[str, StateDefinition] = {}
         for state_id, state in states.items():
-            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
-            if state.onentry:
-                callables = [
-                    ExecuteBlock(content) for content in state.onentry if not content.is_empty
-                ]
-                state_dict["enter"] = callables
-
-            # Process exit actions
-            if state.onexit:
-                callables = [
-                    ExecuteBlock(content) for content in state.onexit if not content.is_empty
-                ]
-                state_dict["exit"] = callables
-
-            # Process transitions
-            if state.transitions:
-                state_dict["transitions"] = self._process_transitions(state.transitions)
-
-            states_dict[state_id] = state_dict
-
-            if state.states:
-                state_dict["states"] = self._process_states(state.states)
-
-            if state.history:
-                state_dict["history"] = self._process_history(state.history)
-
+            states_dict[state_id] = self._process_state(state)
         return states_dict
 
+    def _process_state(self, state: State) -> StateDefinition:
+        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 + donedata
+        enter_callables: list = [
+            ExecuteBlock(content) for content in state.onentry if not content.is_empty
+        ]
+        if state.final and state.donedata:
+            enter_callables.append(DoneDataCallable(state.donedata))
+        if enter_callables:
+            state_dict["enter"] = enter_callables
+
+        # Process exit actions
+        if state.onexit:
+            callables = [ExecuteBlock(content) for content in state.onexit if not content.is_empty]
+            state_dict["exit"] = callables
+
+        # Process transitions
+        if state.transitions:
+            state_dict["transitions"] = self._process_transitions(state.transitions)
+
+        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:

statemachine/io/scxml/schema.py

@@ -110,6 +110,12 @@ class Transition:
     on: "ExecutableContent | None" = None
 
 
+@dataclass
+class DoneData:
+    params: List[Param] = field(default_factory=list)
+    content_expr: "str | None" = None
+
+
 @dataclass
 class State:
     id: str
@@ -121,6 +127,7 @@ class State:
     onexit: List[ExecutableContent] = field(default_factory=list)
     states: Dict[str, "State"] = field(default_factory=dict)
     history: Dict[str, "HistoryState"] = field(default_factory=dict)
+    donedata: "DoneData | None" = None
 
 
 @dataclass