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