diff --git a/docs/api.md b/docs/api.md index 51c51a9..52f8f6b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -159,3 +159,17 @@ class MyMachine(StateChart): ```{eval-rst} .. autofunction:: statemachine.contrib.timeout.timeout ``` + +## DataVar + +```{eval-rst} +.. autoclass:: statemachine.state_data.DataVar + :members: +``` + +## DataChangeInfo + +```{eval-rst} +.. autoclass:: statemachine.state_data.DataChangeInfo + :members: +``` diff --git a/docs/states.md b/docs/states.md index 1694a2b..3b26a71 100644 --- a/docs/states.md +++ b/docs/states.md @@ -41,6 +41,7 @@ True | `enter` | `None` | Callback(s) to run when entering this state. See {ref}`state-actions`. | | `exit` | `None` | Callback(s) to run when leaving this state. See {ref}`state-actions`. | | `invoke` | `None` | Background work spawned on entry, cancelled on exit. See {ref}`invoke-actions`. | +| `data` | `None` | Mapping of string keys to defaults owned by this state. See {ref}`state-data`. | ```py >>> class CampaignMachine(StateChart): @@ -228,3 +229,65 @@ For this, use {ref}`States (class)` to convert your `Enum` type to a list of {re ```{seealso} See the example {ref}`sphx_glr_auto_examples_enum_campaign_machine.py`. ``` + +(state-data)= + +## State data + +Each state can own a private data bag. Values are created when the state is +entered and discarded when it is exited. Re-entering a state always starts +from a fresh copy of the defaults — unless a history state restores a saved +snapshot. + +```py +>>> from statemachine import State, StateChart, DataVar + +>>> class Counter(StateChart): +... idle = State(initial=True) +... running = State(data={"count": 0, "items": list}) +... +... start = idle.to(running) +... tick = running.to.itself() +... stop = running.to(idle) +... +... def on_enter_running(self, state_data): +... state_data["count"] += 1 + +>>> sm = Counter() +>>> sm.send("start") +>>> sm.get_state_data(sm.running)["count"] +1 +>>> sm.send("stop") +>>> sm.get_state_data(sm.running) is None +True + +``` + +Use {class}`~statemachine.state_data.DataVar` for type checks or a factory: + +```py +>>> running = State(data={ +... "count": DataVar(default=0, type=int), +... "seen": DataVar(factory=set), +... }) + +``` + +Callbacks receive a merged ``state_data`` mapping: ancestor keys are visible +and a child key shadows a parent key with the same name. Parallel regions do +not share data with each other. + +Inspect and update data from outside callbacks with +{meth}`~statemachine.statemachine.StateChart.get_state_data`, +{meth}`~statemachine.statemachine.StateChart.set_state_data`, +{attr}`~statemachine.statemachine.StateChart.state_data_values`, and +{meth}`~statemachine.statemachine.StateChart.get_data_changes`. + +Compound and parallel states accept ``data`` as a metaclass keyword: + +```py +>>> class Session(State.Compound, data={"user": None}): +... browsing = State(initial=True) +... checkout = State() + +``` diff --git a/statemachine/__init__.py b/statemachine/__init__.py index 7e0deac..a434c1f 100644 --- a/statemachine/__init__.py +++ b/statemachine/__init__.py @@ -2,6 +2,8 @@ from .event import Event from .state import HistoryState from .state import HistoryType from .state import State +from .state_data import DataChangeInfo +from .state_data import DataVar from .statemachine import StateChart from .statemachine import StateMachine from .statemachine import TModel @@ -18,4 +20,6 @@ __all__ = [ "HistoryType", "Event", "TModel", + "DataVar", + "DataChangeInfo", ] diff --git a/statemachine/contrib/diagram/extract.py b/statemachine/contrib/diagram/extract.py index 15a1f2d..bcbf54e 100644 --- a/statemachine/contrib/diagram/extract.py +++ b/statemachine/contrib/diagram/extract.py @@ -3,6 +3,7 @@ from typing import List from typing import Set from typing import Union +from ...state_data import format_data_var from .model import ActionType from .model import DiagramAction from .model import DiagramGraph @@ -89,6 +90,9 @@ def _extract_state( children.append(_extract_state(history_state, machine, getter, active_values)) actions = _extract_state_actions(state, getter) + data_vars = [ + format_data_var(key, spec) for key, spec in (getattr(state, "data", None) or {}).items() + ] return DiagramState( id=state.id, @@ -99,6 +103,7 @@ def _extract_state( is_active=is_active, is_parallel_area=is_parallel_area, is_initial=getattr(state, "initial", False), + data_vars=data_vars, ) diff --git a/statemachine/contrib/diagram/model.py b/statemachine/contrib/diagram/model.py index 3770bba..83ce86d 100644 --- a/statemachine/contrib/diagram/model.py +++ b/statemachine/contrib/diagram/model.py @@ -41,6 +41,7 @@ class DiagramState: is_active: bool = False is_parallel_area: bool = False is_initial: bool = False + data_vars: List[str] = field(default_factory=list) @dataclass diff --git a/statemachine/contrib/diagram/renderers/dot.py b/statemachine/contrib/diagram/renderers/dot.py index a33db79..bd6260c 100644 --- a/statemachine/contrib/diagram/renderers/dot.py +++ b/statemachine/contrib/diagram/renderers/dot.py @@ -271,7 +271,7 @@ class DotRenderer: fillcolor = self.config.state_active_fillcolor if state.is_active else "white" penwidth = self.config.state_active_penwidth if state.is_active else 2 - if not actions: + if not actions and not state.data_vars: # Simple state: native rounded rectangle node = pydot.Node( state.id, @@ -318,10 +318,15 @@ class DotRenderer: font_size = self.config.state_font_size action_font_size = self.config.transition_font_size - action_lines = "
".join( + extra_lines = [ f'{_escape_html(self._format_action(a))}' for a in actions + ] + extra_lines.extend( + f'{_escape_html(var)}' + for var in state.data_vars ) + action_lines = "
".join(extra_lines) return ( f'' @@ -415,10 +420,17 @@ class DotRenderer: """Build HTML label for a compound/parallel subgraph.""" name = _escape_html(state.name) if state.type == StateType.PARALLEL: - return f"{name} ☷" + if not state.data_vars: + return f"{name} ☷" + rows = [f"{name} ☷"] + for var in state.data_vars: + rows.append( + f'{_escape_html(var)}' + ) + return "
".join(rows) actions = [a for a in state.actions if a.type != ActionType.INTERNAL or a.body] - if not actions: + if not actions and not state.data_vars: return f"{name}" rows = [f"{name}"] @@ -427,6 +439,10 @@ class DotRenderer: rows.append( f'{action_text}' ) + for var in state.data_vars: + rows.append( + f'{_escape_html(var)}' + ) return "
".join(rows) def _add_transitions_for_state( diff --git a/statemachine/contrib/diagram/renderers/mermaid.py b/statemachine/contrib/diagram/renderers/mermaid.py index 15ba61d..dc0a86a 100644 --- a/statemachine/contrib/diagram/renderers/mermaid.py +++ b/statemachine/contrib/diagram/renderers/mermaid.py @@ -179,6 +179,8 @@ class MermaidRenderer: if actions: for action in actions: lines.append(f"{pad}{state.id} : {self._format_action(action)}") + for var in state.data_vars: + lines.append(f"{pad}{state.id} : {var}") if state.is_active: self._active_ids.append(state.id) @@ -194,6 +196,8 @@ class MermaidRenderer: if state.type == StateType.PARALLEL: lines.append(f'{pad}state "{state.name}" as {state.id} {{') + for var in state.data_vars: + lines.append(f"{pad} {state.id} : {var}") regions = [c for c in state.children if c.is_parallel_area or c.children] for i, region in enumerate(regions): if i > 0: @@ -207,6 +211,9 @@ class MermaidRenderer: else: lines.append(f"{pad}state {state.id} {{") + for var in state.data_vars: + lines.append(f"{pad} {state.id} : {var}") + initial_child = next((c for c in state.children if c.is_initial), None) if initial_child: lines.append(f"{pad} [*] --> {initial_child.id}") diff --git a/statemachine/engines/async_.py b/statemachine/engines/async_.py index 9e05561..07adecf 100644 --- a/statemachine/engines/async_.py +++ b/statemachine/engines/async_.py @@ -72,26 +72,31 @@ class AsyncEngine(BaseEngine): # --- Callback dispatch overrides (async versions of BaseEngine methods) --- async def _get_args_kwargs( - self, transition: "Transition", trigger_data: TriggerData, target: "State | None" = None + self, + transition: "Transition", + trigger_data: TriggerData, + target: "State | None" = None, + scope_state: "State | None" = None, ): cache_key = (id(transition), id(trigger_data), id(target)) if cache_key in self._cache: - return self._cache[cache_key] + args, kwargs = self._cache[cache_key] + else: + event_data = EventData(trigger_data=trigger_data, transition=transition) + if target: + event_data.state = target + event_data.target = target - event_data = EventData(trigger_data=trigger_data, transition=transition) - if target: - event_data.state = target - event_data.target = target + args, kwargs = event_data.args, event_data.extended_kwargs - args, kwargs = event_data.args, event_data.extended_kwargs + result = await self.sm._callbacks.async_call(self.sm.prepare.key, *args, **kwargs) + for new_kwargs in result: + kwargs.update(new_kwargs) - result = await self.sm._callbacks.async_call(self.sm.prepare.key, *args, **kwargs) - for new_kwargs in result: - kwargs.update(new_kwargs) + self._cache[cache_key] = (args, kwargs) - self._cache[cache_key] = (args, kwargs) - return args, kwargs + return args, self._with_state_data(kwargs, scope_state or target or transition.source) async def _conditions_match(self, transition: "Transition", trigger_data: TriggerData): args, kwargs = await self._get_args_kwargs(transition, trigger_data) @@ -174,7 +179,9 @@ class AsyncEngine(BaseEngine): if info.state is not None: # pragma: no branch self._invoke_manager.cancel_for_state(info.state) - args, kwargs = await self._get_args_kwargs(info.transition, trigger_data) + args, kwargs = await self._get_args_kwargs( + info.transition, trigger_data, scope_state=info.state + ) if info.state is not None: # pragma: no branch self._debug("%s Exiting state: %s", self._log_id, info.state) @@ -183,6 +190,8 @@ class AsyncEngine(BaseEngine): ) self._remove_state_from_configuration(info.state) + if info.state is not None: # pragma: no branch + self.sm._data_manager.exit_state(info.state) return result @@ -233,6 +242,7 @@ class AsyncEngine(BaseEngine): ) self._debug("%s Entering state: %s", self._log_id, target) + self.sm._data_manager.enter_state(target) self._add_state_to_configuration(target) on_entry_result = await self.sm._callbacks.async_call( @@ -280,6 +290,8 @@ class AsyncEngine(BaseEngine): transitions, ) previous_configuration = self.sm.configuration + data_snapshot = self.sm._data_manager.snapshot() + self.sm._data_manager.clear_pending_restore() try: result = await self._execute_transition_content( transitions, trigger_data, lambda t: t.before.key @@ -291,9 +303,11 @@ class AsyncEngine(BaseEngine): ) except InvalidDefinition: self.sm.configuration = previous_configuration + self.sm._data_manager.restore_snapshot(data_snapshot) raise except Exception as e: self.sm.configuration = previous_configuration + self.sm._data_manager.restore_snapshot(data_snapshot) self._handle_error(e, trigger_data) return None @@ -423,7 +437,7 @@ class AsyncEngine(BaseEngine): # transitions can be processed while we wait. break - self._macrostep_count += 1 + self._begin_macrostep() self._microstep_count = 0 self._debug( "%s macrostep %d: event=%s", diff --git a/statemachine/engines/base.py b/statemachine/engines/base.py index 360398d..e4ee1ca 100644 --- a/statemachine/engines/base.py +++ b/statemachine/engines/base.py @@ -384,6 +384,8 @@ class BaseEngine: transitions, ) previous_configuration = self.sm.configuration + data_snapshot = self.sm._data_manager.snapshot() + self.sm._data_manager.clear_pending_restore() try: result = self._execute_transition_content( transitions, trigger_data, lambda t: t.before.key @@ -395,9 +397,11 @@ class BaseEngine: ) except InvalidDefinition: self.sm.configuration = previous_configuration + self.sm._data_manager.restore_snapshot(data_snapshot) raise except Exception as e: self.sm.configuration = previous_configuration + self.sm._data_manager.restore_snapshot(data_snapshot) self._handle_error(e, trigger_data) return None @@ -421,29 +425,43 @@ class BaseEngine: return result def _get_args_kwargs( - self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None + self, + transition: Transition, + trigger_data: TriggerData, + target: "State | None" = None, + scope_state: "State | None" = None, ): # Generate a unique key for the cache, the cache is invalidated once per loop cache_key = (id(transition), id(trigger_data), id(target)) # Check the cache for existing results if cache_key in self._cache: - return self._cache[cache_key] + args, kwargs = self._cache[cache_key] + else: + event_data = EventData(trigger_data=trigger_data, transition=transition) + if target: + event_data.state = target + event_data.target = target + + args, kwargs = event_data.args, event_data.extended_kwargs - event_data = EventData(trigger_data=trigger_data, transition=transition) - if target: - event_data.state = target - event_data.target = target + result = self.sm._callbacks.call(self.sm.prepare.key, *args, **kwargs) + for new_kwargs in result: + kwargs.update(new_kwargs) - args, kwargs = event_data.args, event_data.extended_kwargs + # Store the result in the cache (without the live state_data view) + self._cache[cache_key] = (args, kwargs) - result = self.sm._callbacks.call(self.sm.prepare.key, *args, **kwargs) - for new_kwargs in result: - kwargs.update(new_kwargs) + return args, self._with_state_data(kwargs, scope_state or target or transition.source) - # Store the result in the cache - self._cache[cache_key] = (args, kwargs) - return args, kwargs + def _with_state_data(self, kwargs: dict, state: "State | None") -> dict: + kwargs = dict(kwargs) + kwargs["state_data"] = self.sm._data_manager.scoped(state) + return kwargs + + def _begin_macrostep(self) -> None: + self._macrostep_count += 1 + self.sm._data_manager.begin_macrostep() def _conditions_match(self, transition: Transition, trigger_data: TriggerData): args, kwargs = self._get_args_kwargs(transition, trigger_data) @@ -482,6 +500,7 @@ class BaseEngine: [s.id for s in history_value], ) self.sm.history_values[history.id] = history_value + self.sm._data_manager.save_history(history.id, history_value) return ordered_states, result @@ -502,7 +521,9 @@ class BaseEngine: if info.state is not None: # pragma: no branch self._invoke_manager.cancel_for_state(info.state) - args, kwargs = self._get_args_kwargs(info.transition, trigger_data) + args, kwargs = self._get_args_kwargs( + info.transition, trigger_data, scope_state=info.state + ) # Execute `onexit` handlers — same per-block error isolation as onentry. if info.state is not None: # pragma: no branch @@ -510,6 +531,8 @@ class BaseEngine: self.sm._callbacks.call(info.state.exit.key, *args, on_error=on_error, **kwargs) self._remove_state_from_configuration(info.state) + if info.state is not None: # pragma: no branch + self.sm._data_manager.exit_state(info.state) return result @@ -672,6 +695,7 @@ class BaseEngine: ) self._debug("%s Entering state: %s", self._log_id, target) + self.sm._data_manager.enter_state(target) self._add_state_to_configuration(target) # Execute `onentry` handlers — each handler is a separate block per @@ -771,6 +795,7 @@ class BaseEngine: parent_id = state.parent and state.parent.id default_history_content[parent_id] = [info] if state.id in self.sm.history_values: + self.sm._data_manager.queue_restore(state.id) self._debug( "%s History state '%s.%s' %s restoring: '%s'", self._log_id, diff --git a/statemachine/engines/sync.py b/statemachine/engines/sync.py index 627b51a..5216007 100644 --- a/statemachine/engines/sync.py +++ b/statemachine/engines/sync.py @@ -140,7 +140,7 @@ class SyncEngine(BaseEngine): # transitions can be processed while we wait. break - self._macrostep_count += 1 + self._begin_macrostep() self._microstep_count = 0 self._debug( "%s macrostep %d: event=%s", diff --git a/statemachine/io/__init__.py b/statemachine/io/__init__.py index 41d947e..ff4d8b6 100644 --- a/statemachine/io/__init__.py +++ b/statemachine/io/__init__.py @@ -46,6 +46,7 @@ class BaseStateKwargs(TypedDict, total=False): enter: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]" exit: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]" donedata: "ActionProtocol | None" + data: dict class StateKwargs(BaseStateKwargs, total=False): diff --git a/statemachine/io/scxml/parser.py b/statemachine/io/scxml/parser.py index 227955e..3b8fa6f 100644 --- a/statemachine/io/scxml/parser.py +++ b/statemachine/io/scxml/parser.py @@ -1,3 +1,4 @@ +import ast import re import xml.etree.ElementTree as ET from typing import List @@ -229,9 +230,34 @@ def parse_state( # noqa: C901 if donedata_elem is not None: state.donedata = parse_donedata(donedata_elem) + state.data = parse_state_data(state_elem) + return state +def parse_state_data(state_elem: ET.Element) -> "dict | None": + """Parse a state's into a ``data`` dict of Python literals.""" + datamodel_elem = state_elem.find("datamodel") + if datamodel_elem is None: + return None + + data: dict = {} + for data_elem in datamodel_elem.findall("data"): + key = data_elem.attrib.get("id") + if not key: + continue + expr = data_elem.attrib.get("expr") + if expr is None: + data[key] = None + continue + try: + data[key] = ast.literal_eval(expr) + except (ValueError, SyntaxError): + # Non-literal expressions stay on the existing machine datamodel. + continue + return data or None + + def parse_donedata(element: ET.Element) -> DoneData: """Parse a element containing and/or children.""" params = [] diff --git a/statemachine/io/scxml/processor.py b/statemachine/io/scxml/processor.py index 52ed83f..d9bb4fc 100644 --- a/statemachine/io/scxml/processor.py +++ b/statemachine/io/scxml/processor.py @@ -207,6 +207,9 @@ class SCXMLProcessor: if state.history: state_dict["history"] = self._process_history(state.history) + if state.data: + state_dict["data"] = state.data + return state_dict def _process_invocation(self, invoke_def: InvokeDefinition) -> SCXMLInvoker: diff --git a/statemachine/io/scxml/schema.py b/statemachine/io/scxml/schema.py index 0b25a77..9be5942 100644 --- a/statemachine/io/scxml/schema.py +++ b/statemachine/io/scxml/schema.py @@ -144,6 +144,7 @@ class State: history: Dict[str, "HistoryState"] = field(default_factory=dict) donedata: "DoneData | None" = None invocations: List[InvokeDefinition] = field(default_factory=list) + data: "dict | None" = None @dataclass diff --git a/statemachine/state.py b/statemachine/state.py index e8aa572..5888681 100644 --- a/statemachine/state.py +++ b/statemachine/state.py @@ -13,6 +13,7 @@ from .event import _expand_event_id from .exceptions import InvalidDefinition from .i18n import _ from .invoke import normalize_invoke_callbacks +from .state_data import normalize_data from .transition import Transition from .transition_list import TransitionList @@ -134,6 +135,10 @@ class State: See :ref:`actions`. exit: One or more callbacks assigned to be executed when the state is exited. See :ref:`actions`. + data: Optional mapping of string keys to default values owned by this + state. Values may be literals, callables (used as factories), or + :class:`~statemachine.state_data.DataVar` instances. Data is created + on entry and discarded on exit. State is a core component on how this library implements an expressive API to declare StateMachines. @@ -214,6 +219,7 @@ class State: exit: Any = None, invoke: Any = None, donedata: Any = None, + data: Any = None, _callbacks: Any = None, ): self.name = name @@ -227,6 +233,7 @@ class State: self.is_active = False self._id: str = "" self._callbacks = _callbacks + self.data = normalize_data(data) self.parent: "State | None" = None self.transitions = TransitionList() self._specs = CallbackSpecList() diff --git a/statemachine/state_data.py b/statemachine/state_data.py new file mode 100644 index 0000000..64f6cde --- /dev/null +++ b/statemachine/state_data.py @@ -0,0 +1,286 @@ +"""Per-state data ownership, scoping, and change tracking.""" + +from collections.abc import Iterator +from collections.abc import MutableMapping +from copy import deepcopy +from dataclasses import dataclass +from typing import TYPE_CHECKING +from typing import Any +from typing import Callable +from typing import Dict +from typing import List + +from .exceptions import InvalidDefinition +from .i18n import _ + +if TYPE_CHECKING: + from .state import State + from .statemachine import StateChart + +_MISSING = object() + + +class DataVar: + """Declare a typed or factory-produced state data variable. + + Args: + default: A concrete default value. Mutually exclusive with ``factory``. + factory: A zero-argument callable that produces a fresh value on each + state entry. Mutually exclusive with ``default``. + type: Optional type used to validate assignments via + :meth:`StateChart.set_state_data`. + """ + + def __init__( + self, + default: Any = _MISSING, + factory: "Callable[[], Any] | None" = None, + type: Any = None, + ): + if default is not _MISSING and factory is not None: + raise InvalidDefinition(_("DataVar cannot have both 'default' and 'factory'.")) + self.default = None if default is _MISSING else default + self.factory = factory + self.type = type + + def produce(self) -> Any: + """Return a fresh value for a new state entry.""" + if self.factory is not None: + return self.factory() + return deepcopy(self.default) + + +@dataclass +class DataChangeInfo: + """A single assignment recorded during the current macrostep.""" + + state_id: str + key: str + old_value: Any + new_value: Any + + +def normalize_data(data: Any) -> Dict[str, Any]: + """Validate and copy a state ``data`` declaration.""" + if data is None: + return {} + if not isinstance(data, dict) or not all(isinstance(key, str) for key in data): + raise InvalidDefinition(_("data requires a dict with string keys.")) + return dict(data) + + +def produce_value(spec: Any) -> Any: + """Produce a fresh value from a declaration entry.""" + if isinstance(spec, DataVar): + return spec.produce() + if callable(spec): + return spec() + return deepcopy(spec) + + +def produce_all(declaration: Dict[str, Any]) -> Dict[str, Any]: + """Produce a fresh data dict from a full declaration.""" + return {key: produce_value(spec) for key, spec in declaration.items()} + + +def format_data_var(key: str, spec: Any) -> str: + """Human-readable annotation for diagrams.""" + if isinstance(spec, DataVar): + type_name = getattr(spec.type, "__name__", None) if spec.type is not None else None + if spec.factory is not None: + factory_name = getattr(spec.factory, "__name__", repr(spec.factory)) + rendered = f"{key} = {factory_name}()" + else: + rendered = f"{key} = {spec.default!r}" + if type_name: + return f"{rendered} : {type_name}" + return rendered + if callable(spec): + name = getattr(spec, "__name__", repr(spec)) + return f"{key} = {name}()" + return f"{key} = {spec!r}" + + +def _unwrap_state(state: Any) -> Any: + return getattr(state, "_state", state) + + +class _StateDataView(MutableMapping): + """Live hierarchical view of a state's data plus ancestor data. + + Child keys shadow parent keys. Writes update the nearest owning state, or + the current state when the key is new. Parallel siblings are not visible + because the chain follows ``parent`` pointers only. + """ + + def __init__(self, manager: "StateDataManager", state: Any): + self._manager = manager + self._state = state + + def _chain(self) -> List[tuple]: + return self._manager.scope_chain(self._state) + + def __getitem__(self, key: str) -> Any: + for _state_id, data in self._chain(): + if key in data: + return data[key] + raise KeyError(key) + + def __setitem__(self, key: str, value: Any) -> None: + for state_id, data in self._chain(): + if key in data: + self._manager.assign(state_id, key, value) + return + state_id = self._state.id + if state_id not in self._manager.active: + self._manager.active[state_id] = {} + self._manager.assign(state_id, key, value) + + def __delitem__(self, key: str) -> None: + for state_id, data in self._chain(): + if key in data: + old = data[key] + del data[key] + self._manager.record(state_id, key, old, None) + return + raise KeyError(key) + + def __iter__(self) -> Iterator[str]: + seen = set() + for _state_id, data in self._chain(): + for key in data: + if key not in seen: + seen.add(key) + yield key + + def __len__(self) -> int: + return len(set(self)) + + def __repr__(self) -> str: + return f"{{ {', '.join(f'{k!r}: {self[k]!r}' for k in self)} }}" + + +class StateDataManager: + """Instance-level storage for state-owned data.""" + + def __init__(self) -> None: + self.active: Dict[str, Dict[str, Any]] = {} + self.history: Dict[str, Dict[str, Dict[str, Any]]] = {} + self.changes: List[DataChangeInfo] = [] + self.pending_restore: Dict[str, Dict[str, Any]] = {} + + def begin_macrostep(self) -> None: + self.changes = [] + + def clear_pending_restore(self) -> None: + self.pending_restore = {} + + def snapshot(self) -> Dict[str, Dict[str, Any]]: + return {state_id: dict(values) for state_id, values in self.active.items()} + + def restore_snapshot(self, snapshot: Dict[str, Dict[str, Any]]) -> None: + self.active = {state_id: dict(values) for state_id, values in snapshot.items()} + + def declaration_of(self, state: Any) -> Dict[str, Any]: + return getattr(_unwrap_state(state), "data", None) or {} + + def scope_chain(self, state: Any) -> List[tuple]: + chain: List[tuple] = [] + current = state + seen = set() + while current is not None: + state_id = getattr(current, "id", None) + if not state_id or state_id in seen: + break + seen.add(state_id) + data = self.active.get(state_id) + if data is not None: + chain.append((state_id, data)) + current = getattr(current, "parent", None) + return chain + + def scoped(self, state: Any) -> _StateDataView: + if state is None: + state = type("AnonymousState", (), {"id": "", "parent": None})() + return _StateDataView(self, state) + + def enter_state(self, state: Any) -> None: + state_id = state.id + if state_id in self.pending_restore: + self.active[state_id] = self.pending_restore.pop(state_id) + return + declaration = self.declaration_of(state) + if declaration: + self.active[state_id] = produce_all(declaration) + + def exit_state(self, state: Any) -> None: + self.active.pop(getattr(state, "id", None), None) + + def save_history(self, history_id: str, states: List[Any]) -> None: + snapshot: Dict[str, Dict[str, Any]] = {} + for state in states: + data = self.active.get(state.id) + if data is not None: + snapshot[state.id] = deepcopy(dict(data)) + self.history[history_id] = snapshot + + def queue_restore(self, history_id: str) -> None: + snapshot = self.history.get(history_id) + if snapshot: + self.pending_restore.update(deepcopy(snapshot)) + + def record(self, state_id: str, key: str, old_value: Any, new_value: Any) -> None: + self.changes.append( + DataChangeInfo( + state_id=state_id, + key=key, + old_value=old_value, + new_value=new_value, + ) + ) + + def assign(self, state_id: str, key: str, value: Any) -> None: + data = self.active.setdefault(state_id, {}) + old_value = data.get(key, _MISSING) + data[key] = value + self.record(state_id, key, None if old_value is _MISSING else old_value, value) + + def values_snapshot(self) -> Dict[str, Dict[str, Any]]: + return {state_id: dict(values) for state_id, values in self.active.items()} + + def get_state_data(self, state: Any) -> "dict | None": + state_id = state if isinstance(state, str) else state.id + data = self.active.get(state_id) + if data is None: + return None + return data + + def set_state_data(self, sm: "StateChart", state: Any, key: str, value: Any) -> None: + resolved = _resolve_state(sm, state) + state_id = resolved.id + if state_id not in self.active: + raise InvalidDefinition( + _("Cannot set data on inactive state {0!r}.").format(state_id) + ) + declaration = self.declaration_of(resolved) + if key not in declaration: + raise InvalidDefinition( + _("Key {0!r} is not declared in state {1!r} data.").format(key, state_id) + ) + spec = declaration[key] + if isinstance(spec, DataVar) and spec.type is not None and not isinstance(value, spec.type): + raise InvalidDefinition( + _("Value {0!r} is not an instance of {1} for key {2!r}.").format( + value, spec.type, key + ) + ) + self.assign(state_id, key, value) + + +def _resolve_state(sm: "StateChart", state: Any) -> "State": + if isinstance(state, str): + for candidate in sm.states_map.values(): + if candidate.id == state: + return candidate + raise InvalidDefinition(_("Unknown state {0!r}.").format(state)) + return _unwrap_state(state) diff --git a/statemachine/statemachine.py b/statemachine/statemachine.py index d33ea12..2949581 100644 --- a/statemachine/statemachine.py +++ b/statemachine/statemachine.py @@ -33,6 +33,7 @@ from .i18n import _ from .model import Model from .signature import SignatureAdapter from .state import InstanceState +from .state_data import StateDataManager from .utils import run_async_from_sync if TYPE_CHECKING: @@ -148,6 +149,7 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass): self.history_values: Dict[ str, List[State] ] = {} # Mapping of compound states to last active state(s). + self._data_manager = StateDataManager() self.state_field = state_field self.start_configuration_values = ( [start_value] if start_value is not None else list(self.start_configuration_values) @@ -498,6 +500,37 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass): """Cancel all the delayed events with the given ``send_id``.""" self._engine.cancel_event(send_id) + def get_state_data(self, state: "State | str"): + """Return the active data dict for ``state``, or ``None``. + + ``state`` may be a :class:`~statemachine.state.State` instance or a + state identifier. Data exists only while the state is active. + """ + return self._data_manager.get_state_data(state) + + @property + def state_data_values(self) -> Dict[str, Dict[str, Any]]: + """Snapshot of all active state data, keyed by state identifier.""" + return self._data_manager.values_snapshot() + + def set_state_data(self, state: "State | str", key: str, value: Any) -> None: + """Assign ``key`` on an active state's data. + + Raises: + InvalidDefinition: If the state is inactive, ``key`` was not + declared, or a :class:`~statemachine.state_data.DataVar` type + constraint is violated. + """ + self._data_manager.set_state_data(self, state, key, value) + + def get_data_changes(self) -> list: + """Return :class:`~statemachine.state_data.DataChangeInfo` records for + the current macrostep. + + The list is cleared at the start of each new macrostep. + """ + return list(self._data_manager.changes) + @property def is_terminated(self): """Whether the state machine has reached a final state. diff --git a/tests/test_state_data.py b/tests/test_state_data.py new file mode 100644 index 0000000..0b33e25 --- /dev/null +++ b/tests/test_state_data.py @@ -0,0 +1,605 @@ +"""State-owned data: lifecycle, scoping, history, validation, and persistence.""" + +import pickle + +import pytest + +from statemachine import DataChangeInfo +from statemachine import DataVar +from statemachine import HistoryState +from statemachine import State +from statemachine import StateChart +from statemachine.exceptions import InvalidDefinition +from statemachine.io.scxml.parser import parse_scxml + + +class CounterMachine(StateChart): + idle = State(initial=True) + running = State(data={"count": 0, "items": list}) + + start = idle.to(running) + tick = running.to.itself() + stop = running.to(idle) + + +class TypedMachine(StateChart): + idle = State(initial=True) + active = State( + data={ + "count": DataVar(default=0, type=int), + "seen": DataVar(factory=set), + } + ) + + start = idle.to(active) + stop = active.to(idle) + + +class NestedDataMachine(StateChart): + validate_trap_states = False + + class outer(State.Compound, data={"level": "outer", "shared": "parent"}): + inner = State( + initial=True, + data={"level": "inner", "local": 1}, + ) + + away = State() + + leave = outer.to(away) + enter = away.to(outer) + + +class ParallelDataMachine(StateChart): + validate_trap_states = False + + class work(State.Parallel, data={"team": "fellowship"}): + class left(State.Compound, data={"side": "left"}): + a = State(initial=True, data={"name": "frodo"}) + + class right(State.Compound, data={"side": "right"}): + b = State(initial=True, data={"name": "sam"}) + + done = State() + finish = work.to(done) + + +class HistoryDataMachine(StateChart): + validate_trap_states = False + + class room(State.Compound, data={"visits": 0}): + h = HistoryState() + h_deep = HistoryState(type="deep") + + class hall(State.Compound, data={"torches": 1}): + entrance = State(initial=True, data={"dust": 0}) + chamber = State(data={"gold": 10}) + go_in = entrance.to(chamber) + + courtyard = State(data={"rain": True}) + go_out = hall.to(courtyard) + + outside = State(initial=True) + enter_room = outside.to(room) + enter_history = outside.to(room.h) + enter_deep = outside.to(room.h_deep) + leave = room.to(outside) + + +@pytest.mark.timeout(5) +class TestStateDataLifecycle: + async def test_initializes_on_entry(self, sm_runner): + sm = await sm_runner.start(CounterMachine) + assert sm.get_state_data(sm.idle) is None + await sm_runner.send(sm, "start") + data = sm.get_state_data(sm.running) + assert data is not None + assert data["count"] == 0 + assert data["items"] == [] + + async def test_removed_on_exit(self, sm_runner): + sm = await sm_runner.start(CounterMachine) + await sm_runner.send(sm, "start") + await sm_runner.send(sm, "stop") + assert sm.get_state_data(sm.running) is None + assert sm.get_state_data("running") is None + + async def test_reentry_resets_defaults(self, sm_runner): + sm = await sm_runner.start(CounterMachine) + await sm_runner.send(sm, "start") + sm.set_state_data(sm.running, "count", 5) + sm.get_state_data(sm.running)["items"].append("x") + await sm_runner.send(sm, "stop") + await sm_runner.send(sm, "start") + data = sm.get_state_data("running") + assert data["count"] == 0 + assert data["items"] == [] + + async def test_instances_do_not_share_data(self, sm_runner): + sm1 = await sm_runner.start(CounterMachine) + sm2 = await sm_runner.start(CounterMachine) + await sm_runner.send(sm1, "start") + await sm_runner.send(sm2, "start") + sm1.set_state_data(sm1.running, "count", 9) + assert sm2.get_state_data(sm2.running)["count"] == 0 + + async def test_callable_factory_and_datavar_factory(self, sm_runner): + sm = await sm_runner.start(TypedMachine) + await sm_runner.send(sm, "start") + data = sm.get_state_data(sm.active) + assert data["count"] == 0 + assert data["seen"] == set() + data["seen"].add("a") + await sm_runner.send(sm, "stop") + await sm_runner.send(sm, "start") + assert sm.get_state_data(sm.active)["seen"] == set() + + async def test_data_available_in_enter_and_exit(self, sm_runner): + seen = {} + + class Probe(StateChart): + a = State(initial=True) + b = State(data={"n": 1}) + go = a.to(b) + back = b.to(a) + + def on_enter_b(self, state_data): + seen["enter"] = dict(state_data) + state_data["n"] = 2 + + def on_exit_b(self, state_data): + seen["exit"] = dict(state_data) + + sm = await sm_runner.start(Probe) + await sm_runner.send(sm, "go") + assert seen["enter"] == {"n": 1} + await sm_runner.send(sm, "back") + assert seen["exit"] == {"n": 2} + + async def test_state_data_values_snapshot(self, sm_runner): + sm = await sm_runner.start(CounterMachine) + await sm_runner.send(sm, "start") + snapshot = sm.state_data_values + assert "running" in snapshot + assert snapshot["running"]["count"] == 0 + snapshot["running"]["count"] = 99 + assert sm.get_state_data(sm.running)["count"] == 0 + + +@pytest.mark.timeout(5) +class TestStateDataScoping: + async def test_child_shadows_parent(self, sm_runner): + seen = {} + + class Probe(NestedDataMachine): + def on_enter_inner(self, state_data): + seen["level"] = state_data["level"] + seen["shared"] = state_data["shared"] + seen["local"] = state_data["local"] + + sm = await sm_runner.start(Probe) + assert seen["level"] == "inner" + assert seen["shared"] == "parent" + assert seen["local"] == 1 + + async def test_parallel_regions_isolated(self, sm_runner): + seen = {} + + class Probe(ParallelDataMachine): + def on_enter_a(self, state_data): + seen["a"] = dict(state_data) + + def on_enter_b(self, state_data): + seen["b"] = dict(state_data) + + sm = await sm_runner.start(Probe) + assert seen["a"]["name"] == "frodo" + assert seen["a"]["side"] == "left" + assert seen["a"]["team"] == "fellowship" + assert "right" not in seen["a"] + assert seen["b"]["name"] == "sam" + assert seen["b"]["side"] == "right" + assert "left" not in seen["b"] + assert sm.get_state_data(sm.work.left.a)["name"] == "frodo" + assert sm.get_state_data(sm.work.right.b)["name"] == "sam" + + +@pytest.mark.timeout(5) +class TestStateDataHistory: + async def test_shallow_restores_direct_child_data(self, sm_runner): + sm = await sm_runner.start(HistoryDataMachine) + await sm_runner.send(sm, "enter_room") + await sm_runner.send(sm, "go_in") + sm.set_state_data(sm.room.hall.chamber, "gold", 99) + sm.set_state_data(sm.room.hall, "torches", 7) + await sm_runner.send(sm, "leave") + await sm_runner.send(sm, "enter_history") + # shallow restores hall, which default-enters entrance (not chamber) + assert "hall" in sm.configuration_values + assert "entrance" in sm.configuration_values + assert sm.get_state_data(sm.room.hall)["torches"] == 7 + assert sm.get_state_data(sm.room.hall.chamber) is None + # hall's child entrance is freshly initialized + assert sm.get_state_data(sm.room.hall.entrance)["dust"] == 0 + + async def test_deep_restores_descendant_data(self, sm_runner): + sm = await sm_runner.start(HistoryDataMachine) + await sm_runner.send(sm, "enter_room") + await sm_runner.send(sm, "go_in") + sm.set_state_data(sm.room.hall.chamber, "gold", 42) + sm.set_state_data(sm.room.hall, "torches", 3) + await sm_runner.send(sm, "leave") + await sm_runner.send(sm, "enter_deep") + assert "chamber" in sm.configuration_values + assert sm.get_state_data(sm.room.hall.chamber)["gold"] == 42 + assert sm.get_state_data(sm.room.hall)["torches"] == 3 + + +@pytest.mark.timeout(5) +class TestStateDataApi: + async def test_set_validates_active_declared_and_type(self, sm_runner): + sm = await sm_runner.start(TypedMachine) + with pytest.raises(InvalidDefinition, match="inactive"): + sm.set_state_data(sm.active, "count", 1) + + await sm_runner.send(sm, "start") + sm.set_state_data(sm.active, "count", 4) + assert sm.get_state_data(sm.active)["count"] == 4 + + with pytest.raises(InvalidDefinition, match="not declared"): + sm.set_state_data(sm.active, "missing", 1) + + with pytest.raises(InvalidDefinition, match="not an instance"): + sm.set_state_data(sm.active, "count", "nope") + + with pytest.raises(InvalidDefinition, match="Unknown state"): + sm.set_state_data("ghost", "count", 1) + + async def test_get_data_changes_tracks_macrostep(self, sm_runner): + sm = await sm_runner.start(TypedMachine) + await sm_runner.send(sm, "start") + sm.set_state_data("active", "count", 1) + sm.set_state_data("active", "count", 2) + changes = sm.get_data_changes() + assert len(changes) == 2 + assert all(isinstance(c, DataChangeInfo) for c in changes) + assert changes[0].state_id == "active" + assert changes[0].key == "count" + assert changes[0].old_value == 0 + assert changes[0].new_value == 1 + assert changes[1].old_value == 1 + assert changes[1].new_value == 2 + + await sm_runner.send(sm, "stop") + # new macrostep clears previous records + assert sm.get_data_changes() == [] + + async def test_callback_assignment_is_recorded(self, sm_runner): + class Probe(StateChart): + validate_trap_states = False + a = State(initial=True) + b = State(data={"n": 0}) + go = a.to(b) + + def on_enter_b(self, state_data): + state_data["n"] = 8 + + sm = await sm_runner.start(Probe) + await sm_runner.send(sm, "go") + changes = [c for c in sm.get_data_changes() if c.key == "n"] + assert changes + assert changes[-1].new_value == 8 + + async def test_invalid_assignment_rolls_back_data(self, sm_runner): + class Probe(StateChart): + a = State(initial=True) + b = State(data={"n": DataVar(default=0, type=int)}) + go = a.to(b) + back = b.to(a) + + def on_enter_b(self): + self.set_state_data(self.b, "n", "bad") + + sm = await sm_runner.start(Probe) + with pytest.raises(InvalidDefinition, match="not an instance"): + await sm_runner.send(sm, "go") + assert "a" in sm.configuration_values + assert sm.get_state_data(sm.b) is None + + +class TestStateDataDefinition: + def test_data_must_be_dict_with_string_keys(self): + with pytest.raises(InvalidDefinition, match="dict with string keys"): + State(data=["x"]) + with pytest.raises(InvalidDefinition, match="dict with string keys"): + State(data={1: "x"}) + + def test_datavar_rejects_default_and_factory(self): + with pytest.raises(InvalidDefinition, match="default"): + DataVar(default=1, factory=int) + + def test_compound_and_parallel_accept_data_keyword(self): + class Compound(State.Compound, data={"x": 1}): + child = State(initial=True) + + class Parallel(State.Parallel, data={"y": 2}): + class r1(State.Compound): + a = State(initial=True) + + class r2(State.Compound): + b = State(initial=True) + + assert Compound.data == {"x": 1} + assert Parallel.data == {"y": 2} + + def test_imports_from_package(self): + assert DataVar is not None + assert DataChangeInfo is not None + + +class TestStateDataPickle: + def test_data_survives_pickle(self): + sm = CounterMachine() + sm.send("start") + sm.set_state_data(sm.running, "count", 11) + sm.get_state_data(sm.running)["items"].append("ring") + + restored = pickle.loads(pickle.dumps(sm)) + data = restored.get_state_data(restored.running) + assert data["count"] == 11 + assert data["items"] == ["ring"] + restored.send("stop") + assert restored.get_state_data(restored.running) is None + restored.send("start") + assert restored.get_state_data(restored.running)["count"] == 0 + + +class TestStateDataScxml: + def test_parses_datamodel_literals(self): + xml = """ + + + + + + + + + + + + + """ + definition = parse_scxml(xml) + state = definition.states["s1"] + assert state.data["count"] == 3 + assert state.data["name"] == "frodo" + assert state.data["items"] == [1, 2] + assert state.data["empty"] is None + assert "dynamic" not in state.data + + def test_scxml_state_data_is_active(self): + from statemachine.io.scxml.processor import SCXMLProcessor + + xml = """ + + + + + + + + + + """ + processor = SCXMLProcessor() + processor.parse_scxml("BagEnd", xml) + sm = processor.scs["BagEnd"]() + assert sm.get_state_data("home")["pipe"] is True + assert sm.get_state_data("home")["meals"] == 7 + + +class TestStateDataDiagrams: + def test_mermaid_annotates_data_vars(self): + from statemachine.contrib.diagram import extract + from statemachine.contrib.diagram.renderers.dot import DotRenderer + from statemachine.contrib.diagram.renderers.mermaid import MermaidRenderer + + class Mapped(StateChart): + validate_trap_states = False + validate_disconnected_states = False + + class session(State.Compound, name="Session", data={"user": None}): + start = State(initial=True, data={"steps": 0, "seen": DataVar(factory=set)}) + + class crew(State.Parallel, name="Crew", data={"team": "fellowship"}): + class left(State.Compound): + a = State(initial=True) + + class right(State.Compound): + b = State(initial=True) + + end = State(final=True) + finish = session.to(end) + wrap = crew.to(end) + + graph = extract(Mapped) + rendered = MermaidRenderer().render(graph) + assert "steps = 0" in rendered + assert "seen = set()" in rendered + assert "user = None" in rendered + assert "team = 'fellowship'" in rendered + + dot = DotRenderer().render(graph).to_string() + assert "steps = 0" in dot + assert "user = None" in dot + assert "team" in dot + + def test_data_elem_without_id_is_skipped(self): + import xml.etree.ElementTree as ET + + from statemachine.io.scxml.parser import parse_state_data + + elem = ET.fromstring( + '' + ) + assert parse_state_data(elem) is None + + +class TestStateDataInternals: + def test_format_data_var_variants(self): + from statemachine.state_data import format_data_var + + assert format_data_var("count", DataVar(default=0, type=int)) == "count = 0 : int" + assert format_data_var("items", list) == "items = list()" + assert format_data_var("flag", True) == "flag = True" + + class NoName: + def __call__(self): + return 1 + + factory = NoName() + rendered = format_data_var("x", DataVar(factory=factory, type=int)) + assert "x = " in rendered + assert ": int" in rendered + + class WeirdType: + __name__ = None # type: ignore[misc] + + # type without a usable __name__ still formats the default + assert "y = 1" in format_data_var("y", DataVar(default=1, type=WeirdType)) + + def test_view_missing_keys_and_new_assignment(self): + from statemachine.state_data import StateDataManager + + class Dummy: + id = "s" + parent = None + data = {"n": 0} + + manager = StateDataManager() + dummy = Dummy() + manager.enter_state(dummy) + view = manager.scoped(dummy) + assert len(view) == 1 + assert "n" in view + with pytest.raises(KeyError): + view["missing"] + view["extra"] = 5 + assert manager.active["s"]["extra"] == 5 + del view["extra"] + assert "extra" not in manager.active["s"] + with pytest.raises(KeyError): + del view["missing"] + assert "n" in repr(view) + + def test_view_assigns_when_state_has_no_active_bag(self): + from statemachine.state_data import StateDataManager + + class Dummy: + id = "orphan" + parent = None + data = {} + + manager = StateDataManager() + view = manager.scoped(Dummy()) + view["x"] = 1 + assert manager.active["orphan"]["x"] == 1 + + def test_scope_chain_breaks_on_cycle_and_skips_empty(self): + from statemachine.state_data import StateDataManager + + class Node: + def __init__(self, id, parent=None): + self.id = id + self.parent = parent + + manager = StateDataManager() + a = Node("a") + a.parent = a + manager.active["a"] = {"v": 1} + chain = manager.scope_chain(a) + assert chain == [("a", {"v": 1})] + + class NoId: + id = "" + parent = None + + assert manager.scope_chain(NoId()) == [] + + parent = Node("p") + child = Node("c", parent) + # parent has no active data + manager.active["c"] = {"k": 1} + chain = manager.scope_chain(child) + assert chain == [("c", {"k": 1})] + + def test_history_helpers_and_snapshot_restore(self): + from statemachine.state_data import StateDataManager + + class Dummy: + def __init__(self, id): + self.id = id + + manager = StateDataManager() + manager.save_history("h", [Dummy("ghost")]) + assert manager.history["h"] == {} + manager.queue_restore("missing") + assert manager.pending_restore == {} + + manager.active["s"] = {"n": 1} + snap = manager.snapshot() + manager.active["s"]["n"] = 9 + manager.restore_snapshot(snap) + assert manager.active["s"]["n"] == 1 + + def test_iter_skips_shadowed_keys(self): + from statemachine.state_data import StateDataManager + + class Parent: + id = "p" + parent = None + data = {"level": "p", "shared": 1} + + class Child: + id = "c" + parent = Parent() + data = {"level": "c"} + + manager = StateDataManager() + manager.enter_state(Parent()) + manager.enter_state(Child()) + view = manager.scoped(Child()) + assert dict(view) == {"level": "c", "shared": 1} + + + def test_scoped_none_state(self): + from statemachine.state_data import StateDataManager + + view = StateDataManager().scoped(None) + assert dict(view) == {} + + + def test_dot_compound_labels(self): + from statemachine.contrib.diagram.model import ActionType + from statemachine.contrib.diagram.model import DiagramAction + from statemachine.contrib.diagram.model import DiagramState + from statemachine.contrib.diagram.model import StateType + from statemachine.contrib.diagram.renderers.dot import DotRenderer + + renderer = DotRenderer() + parallel = DiagramState(id="p", name="P", type=StateType.PARALLEL) + assert "P" in renderer._build_compound_label(parallel) + parallel.data_vars = ["team = 1"] + assert "team = 1" in renderer._build_compound_label(parallel) + + compound = DiagramState( + id="c", + name="C", + type=StateType.REGULAR, + actions=[DiagramAction(type=ActionType.ENTRY, body="setup")], + data_vars=["x = 1"], + ) + label = renderer._build_compound_label(compound) + assert "x = 1" in label + assert "entry / setup" in label