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

statemachine/invoke.py

@@ -9,6 +9,7 @@ decorators (``@state.invoke``), and inline callables all work out of the box.
 import asyncio
 import threading
 import uuid
+from collections.abc import Callable
 from concurrent.futures import Future
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
@@ -16,10 +17,6 @@ from dataclasses import field
 from inspect import iscoroutinefunction
 from typing import TYPE_CHECKING
 from typing import Any
-from typing import Callable
-from typing import Dict
-from typing import List
-from typing import Tuple
 from typing import runtime_checkable
 
 try:
@@ -216,13 +213,13 @@ class InvokeGroup:
     the exception propagates (which causes an ``error.execution`` event).
     """
 
-    def __init__(self, callables: "List[Callable[..., Any]]"):
+    def __init__(self, callables: "list[Callable[..., Any]]"):
         self._callables = list(callables)
-        self._futures: "List[Future[Any]]" = []
+        self._futures: "list[Future[Any]]" = []
         self._executor: "ThreadPoolExecutor | None" = None
 
-    def run(self, ctx: "InvokeContext") -> "List[Any]":
-        results: "List[Any]" = [None] * len(self._callables)
+    def run(self, ctx: "InvokeContext") -> "list[Any]":
+        results: "list[Any]" = [None] * len(self._callables)
         self._executor = ThreadPoolExecutor(max_workers=len(self._callables))
         try:
             self._futures = [self._executor.submit(fn) for fn in self._callables]
@@ -282,8 +279,8 @@ class InvokeManager:
 
     def __init__(self, engine: "BaseEngine"):
         self._engine = engine
-        self._active: Dict[str, Invocation] = {}
-        self._pending: "List[Tuple[State, dict]]" = []
+        self._active: dict[str, Invocation] = {}
+        self._pending: "list[tuple[State, dict]]" = []
 
     @property
     def _debug(self):
@@ -529,7 +526,11 @@ class InvokeManager:
                 self._debug("%s Error in on_cancel for %s", self._log_id, invokeid, exc_info=True)
 
         # 3) Cancel the async task (raises CancelledError at next await).
-        if invocation.task is not None and not invocation.task.done():
+        if (
+            invocation.task is not None
+            and invocation.task is not asyncio.current_task()
+            and not invocation.task.done()
+        ):
             invocation.task.cancel()
 
         # 4) Wait for the sync thread to actually finish (skip if we ARE

statemachine/io/__init__.py

@@ -1,225 +1,45 @@
-from typing import Any
-from typing import Dict
-from typing import List
-from typing import Mapping
-from typing import Protocol
-from typing import Sequence
-from typing import Tuple
-from typing import TypedDict
-from typing import cast
-
-from ..factory import StateMachineMetaclass
-from ..state import HistoryState
-from ..state import State
-from ..statemachine import StateChart
-from ..transition import Transition
-from ..transition_list import TransitionList
-
-
-class ActionProtocol(Protocol):  # pragma: no cover
-    def __call__(self, *args, **kwargs) -> Any: ...
-
-
-class TransitionDict(TypedDict, total=False):
-    target: "str | None"
-    event: "str | None"
-    internal: bool
-    initial: bool
-    validators: bool
-    cond: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
-    unless: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
-    on: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
-    before: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
-    after: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
-
-
-TransitionsDict = Dict["str | None", List[TransitionDict]]
-TransitionsList = List[TransitionDict]
-
-
-class BaseStateKwargs(TypedDict, total=False):
-    name: str
-    value: Any
-    initial: bool
-    final: bool
-    parallel: bool
-    enter: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
-    exit: "str | ActionProtocol | Sequence[str] | Sequence[ActionProtocol]"
-    donedata: "ActionProtocol | None"
-
-
-class StateKwargs(BaseStateKwargs, total=False):
-    states: List[State]
-    history: List[HistoryState]
-
-
-class HistoryKwargs(TypedDict, total=False):
-    name: str
-    value: Any
-    type: str
-
-
-class HistoryDefinition(HistoryKwargs, total=False):
-    on: TransitionsDict
-    transitions: TransitionsList
-
-
-class StateDefinition(BaseStateKwargs, total=False):
-    states: Dict[str, "StateDefinition"]
-    history: Dict[str, "HistoryDefinition"]
-    on: TransitionsDict
-    transitions: TransitionsList
-
-
-def _parse_history(
-    states: Mapping[str, "HistoryKwargs |HistoryDefinition"],
-) -> Tuple[Dict[str, HistoryState], Dict[str, dict]]:
-    states_instances: Dict[str, HistoryState] = {}
-    events_definitions: Dict[str, dict] = {}
-    for state_id, state_definition in states.items():
-        state_definition = cast(HistoryDefinition, state_definition)
-        transition_defs = state_definition.pop("on", {})
-        transition_list = state_definition.pop("transitions", [])
-        if transition_list:
-            transition_defs[None] = transition_list
-
-        if transition_defs:
-            events_definitions[state_id] = transition_defs
-
-        state_definition = cast(HistoryKwargs, state_definition)
-        states_instances[state_id] = HistoryState(**state_definition)
-
-    return (states_instances, events_definitions)
-
-
-def _parse_states(
-    states: Mapping[str, "BaseStateKwargs | StateDefinition"],
-) -> Tuple[Dict[str, State], Dict[str, dict]]:
-    states_instances: Dict[str, State] = {}
-    events_definitions: Dict[str, dict] = {}
-
-    for state_id, state_definition in states.items():
-        # Process nested states. Replaces `states` as a definition by a list of `State` instances.
-        state_definition = cast(StateDefinition, state_definition)
-
-        # pop the nested states, history and transitions definitions
-        inner_states_defs: Dict[str, StateDefinition] = state_definition.pop("states", {})
-        inner_history_defs: Dict[str, HistoryDefinition] = state_definition.pop("history", {})
-        transition_defs = state_definition.pop("on", {})
-        transition_list = state_definition.pop("transitions", [])
-        if transition_list:
-            transition_defs[None] = transition_list
-
-        if inner_states_defs:
-            inner_states, inner_events = _parse_states(inner_states_defs)
-
-            top_level_states = [
-                state._set_id(state_id)
-                for state_id, state in inner_states.items()
-                if not state.parent
-            ]
-            state_definition["states"] = top_level_states  # type: ignore
-            states_instances.update(inner_states)
-            events_definitions.update(inner_events)
-
-        if inner_history_defs:
-            inner_history, inner_events = _parse_history(inner_history_defs)
-
-            top_level_history = [
-                state._set_id(state_id)
-                for state_id, state in inner_history.items()
-                if not state.parent
-            ]
-            state_definition["history"] = top_level_history  # type: ignore
-            states_instances.update(inner_history)
-            events_definitions.update(inner_events)
-
-        if transition_defs:
-            events_definitions[state_id] = transition_defs
-
-        state_definition = cast(BaseStateKwargs, state_definition)
-        states_instances[state_id] = State(**state_definition)
-
-    return (states_instances, events_definitions)
-
-
-def create_machine_class_from_definition(
-    name: str, states: Mapping[str, "StateKwargs | StateDefinition"], **definition
-) -> "type[StateChart]":  # noqa: C901
-    """Create a StateChart class dynamically from a dictionary definition.
-
-    Args:
-        name: The class name for the generated state machine.
-        states: A mapping of state IDs to state definitions. Each state definition
-            can include ``initial``, ``final``, ``parallel``, ``name``, ``value``,
-            ``enter``/``exit`` callbacks, ``donedata``, nested ``states``,
-            ``history``, and transitions via ``on`` (event-triggered) or
-            ``transitions`` (eventless).
-        **definition: Additional keyword arguments passed to the metaclass
-            (e.g., ``validate_final_reachability=False``).
-
-    Returns:
-        A new StateChart subclass configured with the given states and transitions.
-
-    Example:
-
-    >>> machine = create_machine_class_from_definition(
-    ...     "TrafficLightMachine",
-    ...     **{
-    ...         "states": {
-    ...             "green": {"initial": True, "on": {"change": [{"target": "yellow"}]}},
-    ...             "yellow": {"on": {"change": [{"target": "red"}]}},
-    ...             "red": {"on": {"change": [{"target": "green"}]}},
-    ...         },
-    ...     }
-    ... )
-
-    """
-    states_instances, events_definitions = _parse_states(states)
-
-    events: Dict[str, TransitionList] = {}
-    for state_id, state_events in events_definitions.items():
-        for event_name, transitions_data in state_events.items():
-            for transition_data in transitions_data:
-                source = states_instances[state_id]
-
-                target_state_id = transition_data["target"]
-                transition_event_name = transition_data.get("event")
-                if event_name is not None and transition_event_name is not None:
-                    transition_event_name = f"{event_name} {transition_event_name}"
-                elif event_name is not None:
-                    transition_event_name = event_name
-
-                transition_kwargs = {
-                    "event": transition_event_name,
-                    "internal": transition_data.get("internal"),
-                    "initial": transition_data.get("initial"),
-                    "cond": transition_data.get("cond"),
-                    "unless": transition_data.get("unless"),
-                    "on": transition_data.get("on"),
-                    "before": transition_data.get("before"),
-                    "after": transition_data.get("after"),
-                }
-
-                # Handle multi-target transitions (space-separated target IDs)
-                if target_state_id and isinstance(target_state_id, str) and " " in target_state_id:
-                    target_ids = target_state_id.split()
-                    targets = [states_instances[tid] for tid in target_ids]
-                    t = Transition(source, target=targets, **transition_kwargs)
-                    source.transitions.add_transitions(t)
-                    transition = TransitionList([t])
-                else:
-                    target = states_instances[target_state_id] if target_state_id else None
-                    transition = source.to(target, **transition_kwargs)
-
-                if event_name in events:
-                    events[event_name] |= transition
-                elif event_name is not None:
-                    events[event_name] = transition
-
-    top_level_states = {
-        state_id: state for state_id, state in states_instances.items() if not state.parent
-    }
-
-    attrs_mapper = {**definition, **top_level_states, **events}
-    return StateMachineMetaclass(name, (StateChart,), attrs_mapper)  # type: ignore[return-value]
+"""Load a statechart from a declarative document (SCXML, JSON or YAML).
+
+This package is the high-level facade for building a running state machine from a document
+instead of a Python class. :func:`~statemachine.io.load` is the entry point: it detects the
+format (by file extension, or via an explicit ``format=``), parses the text into a neutral
+intermediate representation, compiles it with a secure-by-default evaluator and returns a
+ready-to-instantiate :class:`~statemachine.statemachine.StateChart` class. Every format runs
+under the same execution model, so a guard, an action or a nested machine behaves identically
+whether it was authored in SCXML, JSON or YAML.
+
+Security
+--------
+
+Loading a document compiles its guards, datamodel expressions and executable content into
+callables. Because a document may come from a semi-trusted source, loading is **secure by
+default** (``trusted=False``): expressions are evaluated by a **restricted AST-whitelist
+evaluator** that cannot reach builtins, dunder attributes, or arbitrary calls, and
+``<script>`` / ``script`` (arbitrary code) is rejected. This mirrors ``yaml.safe_load`` and
+keeps loading from turning into arbitrary code execution.
+
+Passing ``trusted=True`` restores full ``eval``/``exec`` evaluation and enables ``script``.
+In that mode a document is equivalent to executable Python (much like :mod:`pickle`), so
+**only load ``trusted`` documents from sources you control** (hand-authored documents, the
+output of your own tooling, the W3C conformance suite).
+
+See the GHSA-v4jc-pm6r-3vj8 advisory for details.
+"""
+
+from .class_factory import ActionProtocol
+from .class_factory import HistoryDefinition
+from .class_factory import StateDefinition
+from .class_factory import TransitionDict
+from .class_factory import create_machine_class_from_definition
+from .loader import build_processor
+from .loader import load
+
+__all__ = [
+    "ActionProtocol",
+    "TransitionDict",
+    "StateDefinition",
+    "HistoryDefinition",
+    "create_machine_class_from_definition",
+    "load",
+    "build_processor",
+]