python-statemachine 3.1.2__py3-none-any.whl → 3.2.1__py3-none-any.whl

statemachine/factory.py

@@ -1,9 +1,5 @@
 import re
 from typing import Any
-from typing import Dict
-from typing import List
-from typing import Optional
-from typing import Tuple
 
 from . import registry
 from .callbacks import CallbackGroup
@@ -39,8 +35,8 @@ class StateMachineMetaclass(type):
     def __init__(
         cls,
         name: str,
-        bases: Tuple[type],
-        attrs: Dict[str, Any],
+        bases: tuple[type],
+        attrs: dict[str, Any],
     ) -> None:
         super().__init__(name, bases, attrs)
         registry.register(cls)
@@ -49,13 +45,13 @@ class StateMachineMetaclass(type):
         # TODO: Experiment with the IDEA of a root state
         # cls.root = State(id=cls.id, name=cls.name)
         cls.states: States = States()
-        cls.states_map: Dict[Any, State] = {}
+        cls.states_map: dict[Any, State] = {}
         """Map of ``state.value`` to the corresponding :ref:`state`."""
 
         cls._abstract = True
-        cls._events: Dict[Event, None] = {}  # used Dict to preserve order and avoid duplicates
+        cls._events: dict[Event, None] = {}  # used Dict to preserve order and avoid duplicates
         cls._protected_attrs: set = set()
-        cls._events_to_update: Dict[Event, Optional[Event]] = {}
+        cls._events_to_update: dict[Event, Event | None] = {}
         cls._specs = CallbackSpecList()
         cls.prepare = cls._specs.grouper(CallbackGroup.PREPARE).add(
             "prepare_event", priority=CallbackPriority.GENERIC, is_convention=True
@@ -88,7 +84,7 @@ class StateMachineMetaclass(type):
         else:  # pragma: no cover
             cls.initial_state = None
 
-        cls.final_states: List[State] = [state for state in cls.states if state.final]
+        cls.final_states: list[State] = [state for state in cls.states if state.final]
 
         cls._check()
         cls._setup()
@@ -130,10 +126,10 @@ class StateMachineMetaclass(type):
         return formatter.render(cls, fmt)  # type: ignore[arg-type]
 
     def _initials_by_document_order(  # noqa: C901
-        cls, states: List[State], parent: "State | None" = None, order: int = 1
+        cls, states: list[State], parent: "State | None" = None, order: int = 1
     ):
         """Set initial state by document order if no explicit initial state is set"""
-        initials: List[State] = []
+        initials: list[State] = []
         for s in states:
             s.document_order = order
             order += 1
@@ -272,13 +268,13 @@ class StateMachineMetaclass(type):
             "send",
         } | {s.id for s in cls.states}
 
-    def _collect_class_listeners(cls, attrs: Dict[str, Any], bases: Tuple[type]):
+    def _collect_class_listeners(cls, attrs: dict[str, Any], bases: tuple[type]):
         """Collect class-level listener declarations from attrs and MRO.
 
         Listeners declared on parent classes are prepended (MRO order),
         unless the child sets ``listeners_inherit = False``.
         """
-        class_listeners: List[Any] = []
+        class_listeners: list[Any] = []
         if attrs.get("listeners_inherit", True):
             for base in reversed(bases):
                 class_listeners.extend(getattr(base, "_class_listeners", []))
@@ -291,7 +287,7 @@ class StateMachineMetaclass(type):
                     ).format(entry)
                 )
             class_listeners.append(entry)
-        cls._class_listeners: List[Any] = class_listeners
+        cls._class_listeners: list[Any] = class_listeners
 
     def add_inherited(cls, bases):
         for base in bases:

statemachine/graph.py

@@ -1,7 +1,7 @@
 from collections import deque
+from collections.abc import Iterable
+from collections.abc import MutableSet
 from typing import TYPE_CHECKING
-from typing import Iterable
-from typing import MutableSet
 
 if TYPE_CHECKING:
     from .state import State

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,52 @@
-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
+--------
+
+A statechart is an *executable document*, not inert data, so loading one is closer to importing
+code than to parsing JSON. Because a document may come from a semi-trusted source, loading is
+**secure by default** (``trusted=False``): expressions are evaluated by a **restricted
+AST-allowlist evaluator** that cannot reach builtins, dunder attributes or arbitrary calls;
+``<script>`` / ``script`` (arbitrary code) is rejected; external resource references
+(``<data src>`` / ``<invoke src>``, which read local files) are rejected; write targets are
+confined to public model attributes; and ``**``/``*`` are magnitude-capped.
+
+Passing ``trusted=True`` restores full ``eval``/``exec`` evaluation, enables ``script`` and
+allows external ``src`` references. 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).
+
+The intended use of ``trusted=False`` is your own dynamic definitions (a no-code editor, your
+tooling, config you control); it is *hardening*, not a sandbox. It guarantees confidentiality
+and integrity, not availability: a *running* machine can still exhaust resources (eventless
+loops, large ``<foreach>``, recursive ``<invoke>``), so run genuinely untrusted documents under
+your own timeout/resource limits or OS-level isolation. See the GHSA-v4jc-pm6r-3vj8,
+GHSA-fj3w-533r-fvf6, GHSA-v3qq-3xvg-m77g, GHSA-4857-ggqc-p3jc and GHSA-r8gj-366q-cgvj advisories,
+and ``docs/io/security.md``, 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",
+]