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

statemachine/io/ports.py

@@ -0,0 +1,83 @@
+"""Format ports & adapters: the reader Protocol and the format registry.
+
+A :class:`FormatReader` is the *port* every format adapter implements: it turns
+raw text into the neutral IR (:class:`~statemachine.io.model.StateMachineDefinition`).
+Each format also declares which file extensions it owns and which processor builds
+its IR into a :class:`~statemachine.statemachine.StateChart` class.
+
+Adapters register themselves with :func:`register_format` (see the ``scxml``,
+``json`` and ``yaml`` reader modules). The high-level :func:`statemachine.io.load`
+facade uses :func:`detect_format` and :func:`get_format` to wire everything up.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from typing import Protocol
+from typing import runtime_checkable
+
+from .model import StateMachineDefinition
+
+
+@runtime_checkable
+class FormatReader(Protocol):
+    """A format adapter: parses text of one format into the neutral IR."""
+
+    def read(
+        self, text: str, *, source_name: "str | None" = None
+    ) -> StateMachineDefinition:  # pragma: no cover - structural Protocol
+        ...
+
+
+@dataclass(frozen=True)
+class FormatSpec:
+    """Describes a supported serialization format.
+
+    The runtime is the format-neutral :class:`~statemachine.io.interpreter.Interpreter`;
+    a format only needs to provide a reader (text -> neutral IR).
+
+    Args:
+        name: the canonical format name (e.g. ``"scxml"``, ``"json"``, ``"yaml"``).
+        extensions: file extensions (with leading dot) that map to this format.
+        reader_factory: builds a :class:`FormatReader` for this format.
+    """
+
+    name: str
+    extensions: "tuple[str, ...]"
+    reader_factory: "Callable[..., Any]"
+
+
+_FORMATS: "dict[str, FormatSpec]" = {}
+_EXTENSIONS: "dict[str, str]" = {}
+
+
+def register_format(spec: FormatSpec) -> None:
+    """Register a format spec, indexing it by name and by each of its extensions."""
+    _FORMATS[spec.name] = spec
+    for ext in spec.extensions:
+        _EXTENSIONS[ext] = spec.name
+
+
+def get_format(name: str) -> FormatSpec:
+    """Return the :class:`FormatSpec` registered under ``name``."""
+    try:
+        return _FORMATS[name]
+    except KeyError:
+        available = ", ".join(sorted(_FORMATS)) or "(none registered)"
+        raise ValueError(f"Unknown format: {name!r}. Available formats: {available}.") from None
+
+
+def detect_format(path: Path, explicit: "str | None" = None) -> str:
+    """Resolve the format name from an explicit override or the file extension."""
+    if explicit is not None:
+        return explicit
+    ext = path.suffix.lower()
+    try:
+        return _EXTENSIONS[ext]
+    except KeyError:
+        known = ", ".join(sorted(_EXTENSIONS)) or "(none registered)"
+        raise ValueError(
+            f"Cannot detect format from extension {ext!r}. Known extensions: "
+            f"{known}. Pass an explicit format=... argument."
+        ) from None

statemachine/io/schemas/statechart.schema.json

@@ -0,0 +1,258 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://fgmacedo.github.io/python-statemachine/schemas/statechart/v1.json",
+  "title": "python-statemachine statechart",
+  "description": "Declarative statechart definition for python-statemachine (JSON/YAML native format).",
+  "type": "object",
+  "required": ["states"],
+  "properties": {
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "datamodel": {
+      "oneOf": [
+        { "type": "object", "additionalProperties": true },
+        { "type": "array", "items": { "$ref": "#/$defs/dataItem" } }
+      ]
+    },
+    "states": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/state" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "flag": {
+      "oneOf": [
+        { "type": "boolean" },
+        { "type": "string", "enum": ["true", "false", "yes", "no", "on", "off"] }
+      ]
+    },
+    "guard": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "dataItem": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": { "type": "string" },
+        "expr": { "type": "string" },
+        "content": {},
+        "src": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "param": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "expr": { "type": "string" },
+        "location": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "structuredAction": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "properties": {
+        "assign": {
+          "type": "object",
+          "required": ["location"],
+          "properties": {
+            "location": { "type": "string" },
+            "expr": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "raise": {
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "object",
+              "required": ["event"],
+              "properties": { "event": { "type": "string" } },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "log": {
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "object",
+              "properties": {
+                "label": { "type": "string" },
+                "expr": { "type": "string" }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "script": { "type": "string" },
+        "cancel": {
+          "type": "object",
+          "properties": {
+            "sendid": { "type": "string" },
+            "sendidexpr": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "send": {
+          "type": "object",
+          "properties": {
+            "event": { "type": "string" },
+            "eventexpr": { "type": "string" },
+            "target": { "type": "string" },
+            "type": { "type": "string" },
+            "id": { "type": "string" },
+            "idlocation": { "type": "string" },
+            "delay": { "type": "string" },
+            "delayexpr": { "type": "string" },
+            "namelist": { "type": "string" },
+            "params": { "type": "array", "items": { "$ref": "#/$defs/param" } },
+            "content": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "foreach": {
+          "type": "object",
+          "required": ["array", "item"],
+          "properties": {
+            "array": { "type": "string" },
+            "item": { "type": "string" },
+            "index": { "type": "string" },
+            "do": { "$ref": "#/$defs/structuredActions" }
+          },
+          "additionalProperties": false
+        },
+        "if": {
+          "type": "object",
+          "required": ["cond"],
+          "properties": {
+            "cond": { "type": "string" },
+            "then": { "$ref": "#/$defs/structuredActions" },
+            "elif": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["cond"],
+                "properties": {
+                  "cond": { "type": "string" },
+                  "then": { "$ref": "#/$defs/structuredActions" }
+                },
+                "additionalProperties": false
+              }
+            },
+            "else": { "$ref": "#/$defs/structuredActions" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "action": {
+      "oneOf": [
+        { "type": "string" },
+        { "$ref": "#/$defs/structuredAction" }
+      ]
+    },
+    "actions": {
+      "oneOf": [
+        { "$ref": "#/$defs/action" },
+        { "type": "array", "items": { "$ref": "#/$defs/action" } }
+      ]
+    },
+    "structuredActions": {
+      "oneOf": [
+        { "$ref": "#/$defs/structuredAction" },
+        { "type": "array", "items": { "$ref": "#/$defs/structuredAction" } }
+      ]
+    },
+    "invoke": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string" },
+        "typeexpr": { "type": "string" },
+        "src": { "type": "string" },
+        "srcexpr": { "type": "string" },
+        "id": { "type": "string" },
+        "idlocation": { "type": "string" },
+        "autoforward": { "$ref": "#/$defs/flag" },
+        "namelist": { "type": "string" },
+        "params": { "type": "array", "items": { "$ref": "#/$defs/param" } },
+        "content": {
+          "oneOf": [
+            { "type": "string" },
+            { "$ref": "#" }
+          ]
+        },
+        "finalize": { "$ref": "#/$defs/structuredActions" }
+      },
+      "additionalProperties": false
+    },
+    "invokeList": {
+      "oneOf": [
+        { "$ref": "#/$defs/invoke" },
+        { "type": "array", "items": { "$ref": "#/$defs/invoke" } }
+      ]
+    },
+    "transition": {
+      "type": "object",
+      "properties": {
+        "event": { "type": "string" },
+        "target": { "type": "string" },
+        "cond": { "$ref": "#/$defs/guard" },
+        "unless": { "$ref": "#/$defs/guard" },
+        "internal": { "$ref": "#/$defs/flag" },
+        "initial": { "$ref": "#/$defs/flag" },
+        "on": { "$ref": "#/$defs/actions" },
+        "before": { "$ref": "#/$defs/actions" },
+        "after": { "$ref": "#/$defs/actions" }
+      },
+      "additionalProperties": false
+    },
+    "history": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string", "enum": ["shallow", "deep"] },
+        "transitions": { "type": "array", "items": { "$ref": "#/$defs/transition" } }
+      },
+      "additionalProperties": false
+    },
+    "donedata": {
+      "type": "object",
+      "properties": {
+        "params": { "type": "array", "items": { "$ref": "#/$defs/param" } },
+        "content": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "state": {
+      "type": "object",
+      "properties": {
+        "initial": { "$ref": "#/$defs/flag" },
+        "final": { "$ref": "#/$defs/flag" },
+        "parallel": { "$ref": "#/$defs/flag" },
+        "enter": { "$ref": "#/$defs/actions" },
+        "exit": { "$ref": "#/$defs/actions" },
+        "transitions": { "type": "array", "items": { "$ref": "#/$defs/transition" } },
+        "invoke": { "$ref": "#/$defs/invokeList" },
+        "states": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/state" }
+        },
+        "history": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/history" }
+        },
+        "donedata": { "$ref": "#/$defs/donedata" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

statemachine/io/scxml/__init__.py

@@ -0,0 +1,15 @@
+"""SCXML ingestion support.
+
+SCXML is, per the W3C specification, *executable content*: ``cond``/``expr`` attributes and
+``<script>`` elements are evaluated in the document's datamodel language. This implementation
+provides a Python datamodel and loads SCXML through the same
+:func:`~statemachine.io.load` facade as the native JSON/YAML formats.
+
+Like every format, SCXML is loaded **secure by default** (``trusted=False`` rejects
+``<script>`` and external ``<data src>`` / ``<invoke src>`` file references, evaluates
+expressions with the restricted AST-allowlist evaluator, confines write targets to public model
+attributes and magnitude-caps ``**``/``*``); pass ``trusted=True`` only for documents you
+control. The parser also refuses ``<!DOCTYPE>``/DTD to block XML entity-expansion bombs. See the
+security note in :mod:`statemachine.io` and the GHSA-v4jc-pm6r-3vj8, GHSA-fj3w-533r-fvf6,
+GHSA-v3qq-3xvg-m77g, GHSA-4857-ggqc-p3jc and GHSA-r8gj-366q-cgvj advisories.
+"""

statemachine/io/scxml/processor.py

@@ -1,263 +1,33 @@
-import os
-from contextlib import contextmanager
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-from typing import Dict
-from typing import List
+"""Back-compatible SCXML entry point: a preconfigured neutral Interpreter.
 
-from ...event import Event
-from ...exceptions import InvalidDefinition
-from ...statemachine import StateChart
-from .. import HistoryDefinition
-from .. import StateDefinition
-from .. import TransitionDict
-from .. import TransitionsList
-from .. import create_machine_class_from_definition
-from .actions import Cond
-from .actions import DoneDataCallable
-from .actions import EventDataWrapper
-from .actions import ExecuteBlock
-from .actions import create_datamodel_action_callable
-from .actions import create_invoke_init_callable
-from .invoke import SCXMLInvoker
-from .parser import parse_scxml
-from .schema import HistoryState
-from .schema import InvokeDefinition
-from .schema import State
-from .schema import Transition
+The runtime is the format-neutral :class:`~statemachine.io.interpreter.Interpreter`.
+``SCXMLProcessor`` is simply that interpreter wired with the SCXML reader and the
+trusted/restricted evaluator, plus the ``parse_scxml`` convenience for parsing a document
+from a string. New code should prefer :func:`statemachine.io.load` (which also reads files
+and detects the format from the extension).
+"""
 
+from ..evaluators import evaluator_for
+from ..interpreter import Interpreter
+from .reader import SCXMLReader
+from .reader import parse_scxml
 
-@contextmanager
-def temporary_directory(new_current_dir):
-    original_dir = os.getcwd()
-    try:
-        os.chdir(new_current_dir)
-        yield
-    finally:
-        os.chdir(original_dir)
 
+class SCXMLProcessor(Interpreter):
+    """Parses SCXML documents into :class:`~statemachine.statemachine.StateChart` classes.
 
-class IOProcessor:
-    def __init__(self, processor: "SCXMLProcessor", machine: StateChart):
-        self.scxml_processor = processor
-        self.machine = machine
+    Args:
+        trusted: when ``False`` (default), datamodel expressions are evaluated by
+            a restricted AST-allowlist evaluator and ``<script>`` is rejected, so
+            loading a document cannot execute arbitrary code. When ``True``,
+            expressions and ``<script>`` are evaluated as arbitrary Python via
+            ``eval``/``exec`` — only use it for SCXML you trust (see the package
+            docstring and GHSA-v4jc-pm6r-3vj8).
+    """
 
-    def __getitem__(self, name: str):
-        return self
-
-    @property
-    def location(self):
-        return self.machine.name
-
-    def get(self, name: str):
-        return getattr(self, name)
-
-
-@dataclass
-class SessionData:
-    machine: StateChart
-    processor: IOProcessor
-    first_event_raised: bool = False
-
-    def __post_init__(self):
-        self.session_id = f"{self.machine.name}:{id(self.machine)}"
-
-
-class SCXMLProcessor:
-    def __init__(self):
-        self.scs: "Dict[str, type[StateChart]]" = {}
-        self.sessions: Dict[str, SessionData] = {}
-        self._ioprocessors = {
-            "http://www.w3.org/TR/scxml/#SCXMLEventProcessor": self,
-            "scxml": self,
-        }
-
-    def parse_scxml_file(self, path: Path):
-        scxml_content = path.read_text()
-        with temporary_directory(path.parent):
-            return self.parse_scxml(path.stem, scxml_content)
+    def __init__(self, trusted: bool = False):
+        super().__init__(reader=SCXMLReader(), evaluator=evaluator_for(trusted))
 
     def parse_scxml(self, sm_name: str, scxml_content: str):
         definition = parse_scxml(scxml_content)
         self.process_definition(definition, location=definition.name or sm_name)
-
-    def process_definition(self, definition, location: str, is_invoked: bool = False):
-        states_dict = self._process_states(definition.states)
-
-        # Find the initial state for inserting init callbacks
-        try:
-            initial_state = next(s for s in iter(states_dict.values()) if s.get("initial"))
-        except StopIteration:
-            initial_state = next(iter(states_dict.values()))
-
-        if "enter" not in initial_state:
-            initial_state["enter"] = []
-
-        insert_pos = 0
-
-        # For invoked children, insert invoke_init to pop _invoke_session/_invoke_params
-        # from kwargs and store them on the machine instance before any other callbacks.
-        if is_invoked:
-            initial_state["enter"].insert(0, create_invoke_init_callable())  # type: ignore[union-attr]
-            insert_pos = 1
-
-        # Process datamodel (initial variables)
-        if definition.datamodel:
-            datamodel = create_datamodel_action_callable(definition.datamodel)
-            if datamodel:  # pragma: no branch – parse_datamodel guarantees non-empty
-                if isinstance(  # pragma: no branch – always a list from lines above
-                    initial_state["enter"], list
-                ):
-                    initial_state["enter"].insert(insert_pos, datamodel)  # type: ignore[arg-type]
-
-        self._add(
-            location,
-            {
-                "states": states_dict,
-                "prepare_event": self._prepare_event,
-                "validate_disconnected_states": False,
-                "validate_trap_states": False,
-                "validate_final_reachability": False,
-                "start_configuration_values": list(definition.initial_states),
-            },
-        )
-
-    def _prepare_event(self, *args, event: Event, **kwargs):
-        machine = kwargs["machine"]
-        session_data = self._get_session(machine)
-
-        if not session_data.first_event_raised and event and event != "__initial__":
-            session_data.first_event_raised = True
-
-        _event: "EventDataWrapper | None" = None
-        if session_data.first_event_raised:
-            _event = EventDataWrapper(kwargs["event_data"])
-
-        return {
-            "_name": machine.name,
-            "_sessionid": session_data.session_id,
-            "_ioprocessors": session_data.processor,
-            "_event": _event,
-        }
-
-    def _get_session(self, machine: StateChart):
-        if machine.name not in self.sessions:
-            self.sessions[machine.name] = SessionData(
-                processor=IOProcessor(self, machine=machine), machine=machine
-            )
-        return self.sessions[machine.name]
-
-    def _process_history(self, history: Dict[str, HistoryState]) -> Dict[str, HistoryDefinition]:
-        states_dict: Dict[str, HistoryDefinition] = {}
-        for state_id, state in history.items():
-            state_dict = HistoryDefinition()
-
-            state_dict["type"] = state.type
-
-            # Process transitions
-            if state.transitions:
-                state_dict["transitions"] = self._process_transitions(state.transitions)
-
-            states_dict[state_id] = state_dict
-
-        return states_dict
-
-    def _process_states(self, states: Dict[str, State]) -> Dict[str, StateDefinition]:
-        states_dict: Dict[str, StateDefinition] = {}
-        for state_id, state in states.items():
-            states_dict[state_id] = self._process_state(state)
-        return states_dict
-
-    def _process_state(self, state: State) -> StateDefinition:  # noqa: C901
-        state_dict = StateDefinition()
-        if state.initial:
-            state_dict["initial"] = True
-        if state.final:
-            state_dict["final"] = True
-        if state.parallel:
-            state_dict["parallel"] = True
-
-        # Process enter actions
-        enter_callables: list = [
-            ExecuteBlock(content) for content in state.onentry if not content.is_empty
-        ]
-        if enter_callables:
-            state_dict["enter"] = enter_callables
-        if state.final and state.donedata:
-            state_dict["donedata"] = DoneDataCallable(state.donedata)
-
-        # Process exit actions
-        if state.onexit:
-            callables = [ExecuteBlock(content) for content in state.onexit if not content.is_empty]
-            state_dict["exit"] = callables
-
-        # Process transitions
-        if state.transitions:
-            state_dict["transitions"] = self._process_transitions(state.transitions)
-
-        # Process invoke elements
-        if state.invocations:
-            invokers = [self._process_invocation(inv) for inv in state.invocations]
-            state_dict["invoke"] = invokers  # type: ignore[typeddict-unknown-key]
-
-        if state.states:
-            state_dict["states"] = self._process_states(state.states)
-
-        if state.history:
-            state_dict["history"] = self._process_history(state.history)
-
-        return state_dict
-
-    def _process_invocation(self, invoke_def: InvokeDefinition) -> SCXMLInvoker:
-        """Convert an InvokeDefinition into an SCXMLInvoker."""
-        return SCXMLInvoker(
-            definition=invoke_def,
-            base_dir=os.getcwd(),
-            register_child=self._register_child,
-        )
-
-    def _register_child(self, scxml_content: str, child_name: str) -> type:
-        """Parse SCXML content, register it as a child machine, and return its class."""
-        definition = parse_scxml(scxml_content)
-        self.process_definition(definition, location=child_name, is_invoked=True)
-        return self.scs[child_name]
-
-    def _process_transitions(self, transitions: List[Transition]):
-        result: TransitionsList = []
-        for transition in transitions:
-            event = transition.event or None
-            transition_dict: TransitionDict = {
-                "event": event,
-                "target": transition.target,
-                "internal": transition.internal,
-                "initial": transition.initial,
-            }
-
-            # Process cond
-            if transition.cond:
-                cond_callable = Cond.create(transition.cond, processor=self)
-                if cond_callable is not None:  # pragma: no branch – cond already truthy
-                    transition_dict["cond"] = cond_callable
-
-                # Process actions
-            if transition.on and not transition.on.is_empty:
-                transition_dict["on"] = ExecuteBlock(transition.on)
-
-            result.append(transition_dict)
-        return result
-
-    def _add(self, location: str, definition: Dict[str, Any]):
-        try:
-            sc_class = create_machine_class_from_definition(location, **definition)
-            self.scs[location] = sc_class
-            return sc_class
-        except Exception as e:  # pragma: no cover
-            raise InvalidDefinition(
-                f"Failed to create state machine class: {e} from definition: {definition}"
-            ) from e
-
-    def start(self, **kwargs):
-        self.root_cls = next(iter(self.scs.values()))
-        self.root = self.root_cls(**kwargs)
-        return self.root