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

statemachine/io/scxml/{parser.py → reader.py}

@@ -1,31 +1,32 @@
 import re
 import xml.etree.ElementTree as ET
-from typing import List
+from collections.abc import Callable
 from typing import Literal
-from typing import Set
 from typing import cast
-from urllib.parse import urlparse
-
-from .schema import Action
-from .schema import AssignAction
-from .schema import CancelAction
-from .schema import DataItem
-from .schema import DataModel
-from .schema import DoneData
-from .schema import ExecutableContent
-from .schema import ForeachAction
-from .schema import HistoryState
-from .schema import IfAction
-from .schema import IfBranch
-from .schema import InvokeDefinition
-from .schema import LogAction
-from .schema import Param
-from .schema import RaiseAction
-from .schema import ScriptAction
-from .schema import SendAction
-from .schema import State
-from .schema import StateMachineDefinition
-from .schema import Transition
+
+from ...exceptions import InvalidDefinition
+from ..model import Action
+from ..model import AssignAction
+from ..model import CancelAction
+from ..model import DataItem
+from ..model import DataModel
+from ..model import DoneData
+from ..model import ExecutableContent
+from ..model import ForeachAction
+from ..model import HistoryState
+from ..model import IfAction
+from ..model import IfBranch
+from ..model import InvokeDefinition
+from ..model import LogAction
+from ..model import Param
+from ..model import RaiseAction
+from ..model import ScriptAction
+from ..model import SendAction
+from ..model import State
+from ..model import StateMachineDefinition
+from ..model import Transition
+from ..ports import FormatSpec
+from ..ports import register_format
 
 
 def strip_namespaces(tree: ET.Element):
@@ -40,14 +41,33 @@ def strip_namespaces(tree: ET.Element):
                 attrib[new_name] = attrib.pop(name)
 
 
-def _parse_initial(initial_content: "str | None") -> List[str]:
+def _parse_initial(initial_content: "str | None") -> list[str]:
     if initial_content is None:
         return []
     return initial_content.split()
 
 
+class _NoDTDTreeBuilder(ET.TreeBuilder):
+    """A tree builder that refuses documents carrying a ``<!DOCTYPE>``/DTD.
+
+    Internal entity definitions (the basis of billion-laughs / quadratic-blowup
+    expansion bombs) require a DTD, so rejecting the DOCTYPE neutralizes them at
+    parse time. Expat calls this ``doctype`` hook when it meets the declaration.
+    """
+
+    def doctype(self, name, pubid, system):  # noqa: D102 - expat callback
+        raise InvalidDefinition(
+            "DOCTYPE/DTD is not allowed in SCXML documents (XML entity-expansion protection)."
+        )
+
+
+def _fromstring_no_dtd(scxml_content: str) -> ET.Element:
+    """Parse SCXML text rejecting any DOCTYPE (see :class:`_NoDTDTreeBuilder`)."""
+    return ET.fromstring(scxml_content, parser=ET.XMLParser(target=_NoDTDTreeBuilder()))
+
+
 def parse_scxml(scxml_content: str) -> StateMachineDefinition:  # noqa: C901
-    root = ET.fromstring(scxml_content)
+    root = _fromstring_no_dtd(scxml_content)
     strip_namespaces(root)
 
     scxml = root if root.tag == "scxml" else root.find(".//scxml")
@@ -87,13 +107,13 @@ def parse_scxml(scxml_content: str) -> StateMachineDefinition:  # noqa: C901
     return definition
 
 
-def _find_own_datamodel_elements(root: ET.Element) -> List[ET.Element]:
+def _find_own_datamodel_elements(root: ET.Element) -> list[ET.Element]:
     """Find <datamodel> elements that belong to this SCXML document, not to inline children.
 
     Skips any <datamodel> nested inside <content> elements (which contain inline
     child SCXML documents for <invoke>).
     """
-    result: List[ET.Element] = []
+    result: list[ET.Element] = []
 
     def _walk(elem: ET.Element):
         for child in elem:
@@ -113,16 +133,12 @@ def parse_datamodel(root: ET.Element) -> "DataModel | None":
     for datamodel_elem in _find_own_datamodel_elements(root):
         for data_elem in datamodel_elem.findall("data"):
             content = data_elem.text and re.sub(r"\s+", " ", data_elem.text).strip() or None
-            src = data_elem.attrib.get("src")
-            src_parsed = urlparse(src) if src else None
-            if src_parsed and src_parsed.scheme == "file" and content is None:
-                with open(src_parsed.path) as f:
-                    content = f.read()
-
+            # An external ``src`` is kept as a raw string; resolving it (reading the file)
+            # is deferred to datamodel compilation, where the trust policy can gate it.
             data_model.data.append(
                 DataItem(
                     id=data_elem.attrib["id"],
-                    src=src_parsed,
+                    src=data_elem.attrib.get("src"),
                     expr=data_elem.attrib.get("expr"),
                     content=content,
                 )
@@ -157,7 +173,7 @@ def parse_history(state_elem: ET.Element) -> HistoryState:
 
 def parse_state(  # noqa: C901
     state_elem: ET.Element,
-    initial_states: Set[str],
+    initial_states: set[str],
     is_final: bool = False,
     is_parallel: bool = False,
 ) -> State:
@@ -279,25 +295,11 @@ def parse_executable_content(element: ET.Element) -> ExecutableContent:
 
 
 def parse_element(element: ET.Element) -> Action:
-    tag = element.tag
-    if tag == "raise":
-        return parse_raise(element)
-    elif tag == "assign":
-        return parse_assign(element)
-    elif tag == "log":
-        return parse_log(element)
-    elif tag == "if":
-        return parse_if(element)
-    elif tag == "send":
-        return parse_send(element)
-    elif tag == "script":
-        return parse_script(element)
-    elif tag == "foreach":
-        return parse_foreach(element)
-    elif tag == "cancel":
-        return parse_cancel(element)
-
-    raise ValueError(f"Unknown tag: {tag}")
+    try:
+        parser = _ELEMENT_PARSERS[element.tag]
+    except KeyError:
+        raise ValueError(f"Unknown tag: {element.tag}") from None
+    return parser(element)
 
 
 def parse_raise(element: ET.Element) -> RaiseAction:
@@ -434,7 +436,7 @@ def parse_invoke(element: ET.Element) -> InvokeDefinition:
     autoforward = element.attrib.get("autoforward", "false").lower() == "true"
     namelist = element.attrib.get("namelist")
 
-    params: List[Param] = []
+    params: list[Param] = []
     content: "str | None" = None
     finalize: "ExecutableContent | None" = None
 
@@ -471,3 +473,33 @@ def parse_invoke(element: ET.Element) -> InvokeDefinition:
         content=content,
         finalize=finalize,
     )
+
+
+#: Dispatch table for executable-content elements (all parsers share the same
+#: ``(element) -> Action`` signature, so a lookup is cleaner than a branch chain).
+_ELEMENT_PARSERS: "dict[str, Callable[[ET.Element], Action]]" = {
+    "raise": parse_raise,
+    "assign": parse_assign,
+    "log": parse_log,
+    "if": parse_if,
+    "send": parse_send,
+    "script": parse_script,
+    "foreach": parse_foreach,
+    "cancel": parse_cancel,
+}
+
+
+class SCXMLReader:
+    """Format adapter that parses SCXML (XML) documents into the neutral IR."""
+
+    def read(self, text: str, *, source_name: "str | None" = None) -> StateMachineDefinition:
+        return parse_scxml(text)
+
+
+register_format(
+    FormatSpec(
+        name="scxml",
+        extensions=(".scxml", ".xml"),
+        reader_factory=SCXMLReader,
+    )
+)

statemachine/io/system_variables.py

@@ -0,0 +1,199 @@
+"""Runtime system variables of the statechart execution model.
+
+These are part of the (SCXML-derived) execution model the library implements, not of
+any particular syntax — so they are format-neutral and available to statecharts loaded
+from SCXML, JSON or YAML alike. The :class:`~statemachine.io.interpreter.Interpreter`
+injects them on every event via :func:`build_system_variables`:
+
+- ``_event``: the current event, wrapped as :class:`EventDataWrapper`
+  (``name``/``data``/``type``/``origintype``/``sendid``/``invokeid``).
+- ``_sessionid``: a stable id for the running machine session.
+- ``_name``: the machine name.
+- ``_ioprocessors``: the session's :class:`IOProcessor`.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class _Data:
+    """The ``_event.data`` payload view.
+
+    The raw payload dict is stored under a private (``_``-prefixed) name so a restricted
+    expression cannot hand back the underlying dict via ``_event.data.kwargs``; only the
+    individual payload fields (``_event.data.<field>``) are reachable.
+    """
+
+    _kwargs: dict
+
+    def __getattr__(self, name):
+        if name == "_kwargs":
+            # Guard against unbounded recursion before the field is set (e.g. copy/pickle).
+            raise AttributeError(name)
+        return self._kwargs.get(name, None)
+
+    def get(self, name, default=None):
+        return self._kwargs.get(name, default)
+
+
+class OriginTypeSCXML(str):
+    """The origintype of an :ref:`Event` as specified by the SCXML namespace."""
+
+    def __eq__(self, other):
+        return other == "http://www.w3.org/TR/scxml/#SCXMLEventProcessor" or other == "scxml"
+
+
+class EventDataWrapper:
+    """The ``_event`` system variable: a read-only view of the current event.
+
+    Exposes ``name``/``data``/``type``/``origintype``/``sendid``/``invokeid`` following
+    the SCXML event model, which is the library's execution model regardless of the
+    source syntax.
+    """
+
+    origin: str = ""
+    origintype: str = OriginTypeSCXML("scxml")
+    invokeid: str = ""
+    """If this event is generated from an invoked child process, the Processor MUST set
+    this field to the invoke id of the invocation that triggered the child process.
+    Otherwise it MUST leave it blank.
+    """
+
+    def __init__(self, event_data=None, *, trigger_data=None):
+        # The engine carriers are stored under private (``_``-prefixed) names so a
+        # restricted expression cannot reach them (``_event.event_data`` /
+        # ``_event.trigger_data``) and pivot to the machine/interpreter/State. The
+        # restricted evaluator blocks attribute access to ``_``-prefixed names, and this
+        # class deliberately exposes NO public attribute or ``__getattr__`` forward that
+        # would hand them back (GHSA-v3qq-3xvg-m77g).
+        self._event_data = event_data
+        if trigger_data is not None:
+            self._trigger_data = trigger_data
+        elif event_data is not None:
+            self._trigger_data = event_data.trigger_data
+        else:
+            raise ValueError("Either event_data or trigger_data must be provided")
+
+        td = self._trigger_data
+        self.sendid = td.send_id
+        self.invokeid = td.kwargs.get("_invokeid", "")
+        if td.event is None or td.event.internal:
+            if "error.execution" == td.event:
+                self.type = "platform"
+            else:
+                self.type = "internal"
+                self.origintype = ""
+        else:
+            self.type = "external"
+
+    @classmethod
+    def from_trigger_data(cls, trigger_data):
+        """Create an EventDataWrapper directly from a TriggerData (no EventData needed)."""
+        return cls(trigger_data=trigger_data)
+
+    def __eq__(self, value):
+        "This makes SCXML test 329 pass. It assumes that the event is the same instance"
+        return isinstance(value, EventDataWrapper)
+
+    @property
+    def name(self):
+        if self._event_data is not None:
+            return self._event_data.event
+        return str(self._trigger_data.event) if self._trigger_data.event else None
+
+    @property
+    def data(self):
+        "Property used to access the event payload (the SCXML ``_event.data``)."
+        td = self._trigger_data
+        if td.kwargs:
+            return _Data(td.kwargs)
+        elif td.args and len(td.args) == 1:
+            return td.args[0]
+        elif td.args:
+            return td.args
+        else:
+            return None
+
+
+class IOProcessor:
+    """The ``_ioprocessors`` system variable for a session.
+
+    A minimal Event I/O Processor handle: indexing by any processor name returns itself,
+    and ``location`` is the machine name.
+    """
+
+    def __init__(self, interpreter, machine):
+        # Stored under private (``_``-prefixed) names so a restricted expression cannot
+        # reach the interpreter/machine via ``_ioprocessors.interpreter`` /
+        # ``_ioprocessors.machine`` and mutate the process-shared engine
+        # (GHSA-v3qq-3xvg-m77g). Only the SCXML-visible ``location`` stays public.
+        self._interpreter = interpreter
+        self._machine = machine
+
+    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:
+    """Per-machine runtime session state held by the interpreter."""
+
+    machine: Any
+    processor: IOProcessor
+    first_event_raised: bool = False
+
+    def __post_init__(self):
+        self.session_id = f"{self.machine.name}:{id(self.machine)}"
+
+
+def build_system_variables(machine, session_data: SessionData, event, event_data) -> dict:
+    """Compute the system variables to inject into callbacks for the current event.
+
+    ``_event`` is exposed only after the first real (non-``__initial__``) event, matching
+    the SCXML rule that ``_event`` is unbound during the initial macrostep.
+    """
+    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(event_data)
+
+    return {
+        "_name": machine.name,
+        "_sessionid": session_data.session_id,
+        "_ioprocessors": session_data.processor,
+        "_event": _event,
+    }
+
+
+def create_invoke_init_callable():
+    """Create a callback that extracts invoke-specific kwargs and stores them on the machine.
+
+    Inserted at position 0 in the initial state's onentry list for invoked children, so
+    ``_invoke_session`` and ``_invoke_params`` are handled before any other callbacks run,
+    even for machines without a datamodel.
+    """
+    initialized = False
+
+    def invoke_init(*args, **kwargs):
+        nonlocal initialized
+        if initialized:
+            return
+        initialized = True
+        machine = kwargs.get("machine")
+        if machine is not None:
+            # Use get() not pop(): each callback receives a copy of kwargs
+            # (via EventData.extended_kwargs), so pop would be misleading.
+            machine._invoke_params = kwargs.get("_invoke_params")
+            machine._invoke_session = kwargs.get("_invoke_session")
+
+    return invoke_init

statemachine/io/validation.py

@@ -0,0 +1,44 @@
+"""Optional JSON Schema validation for the native (JSON/YAML) statechart format.
+
+Requires the optional ``[validation]`` extra (``jsonschema``). The schema itself is
+shipped with the package at ``statemachine/io/schemas/statechart.schema.json`` and is
+also published so editors/tools can reference it via ``$schema``.
+"""
+
+import json
+from functools import lru_cache
+from importlib.resources import files
+
+from ..exceptions import InvalidDefinition
+
+SCHEMA_RESOURCE = "statechart.schema.json"
+
+
+@lru_cache(maxsize=1)
+def load_schema() -> dict:
+    """Load and cache the bundled statechart JSON Schema."""
+    resource = files("statemachine.io").joinpath("schemas").joinpath(SCHEMA_RESOURCE)
+    return json.loads(resource.read_text(encoding="utf-8"))  # type: ignore[no-any-return]
+
+
+def validate_document(doc) -> None:
+    """Validate a parsed native document against the statechart JSON Schema.
+
+    Raises:
+        InvalidDefinition: if the document does not conform to the schema, or if the
+            optional ``jsonschema`` dependency is not installed.
+    """
+    try:
+        import jsonschema  # type: ignore[import-untyped]
+    except ModuleNotFoundError as exc:  # pragma: no cover - exercised via import mock
+        raise InvalidDefinition(
+            "validate=True requires the 'jsonschema' package. Install it with: "
+            'pip install "python-statemachine[validation]"'
+        ) from exc
+
+    try:
+        jsonschema.validate(instance=doc, schema=load_schema())
+    except jsonschema.ValidationError as exc:
+        raise InvalidDefinition(
+            f"Statechart document failed schema validation: {exc.message}"
+        ) from exc

statemachine/io/yaml/__init__.py

@@ -0,0 +1 @@
+"""YAML statechart format adapter (requires the optional ``[yaml]`` extra)."""

statemachine/io/yaml/reader.py

@@ -0,0 +1,65 @@
+"""YAML format adapter: parse a YAML statechart document into the neutral IR.
+
+Requires the optional ``[yaml]`` extra (PyYAML). YAML is always parsed with
+``yaml.safe_load`` semantics so a document can never instantiate arbitrary Python
+objects.
+"""
+
+from ..model import StateMachineDefinition
+from ..native import native_dict_to_definition
+from ..ports import FormatSpec
+from ..ports import register_format
+
+_LOADER = None
+
+
+def _make_loader(yaml):
+    """Build a SafeLoader that does NOT coerce ``on``/``off``/``yes``/``no`` to bool.
+
+    YAML 1.1 turns those tokens into booleans, which silently mangles state ids
+    like ``off``/``on`` into ``True``/``False``. We keep ``yaml.safe_load``'s safety
+    but restrict the implicit bool resolver to ``true``/``false`` only.
+    """
+    global _LOADER
+    if _LOADER is not None:
+        return _LOADER
+
+    class _StatechartSafeLoader(yaml.SafeLoader):
+        pass
+
+    _StatechartSafeLoader.yaml_implicit_resolvers = {
+        first_char: [
+            (tag, regexp)
+            for (tag, regexp) in resolvers
+            if not (tag == "tag:yaml.org,2002:bool" and first_char not in "tTfF")
+        ]
+        for first_char, resolvers in yaml.SafeLoader.yaml_implicit_resolvers.items()
+    }
+    _LOADER = _StatechartSafeLoader
+    return _LOADER
+
+
+class YAMLReader:
+    """Format adapter that parses YAML documents (``yaml.safe_load``) into the IR."""
+
+    def parse_document(self, text: str) -> dict:
+        try:
+            import yaml  # type: ignore[import-untyped]
+        except ModuleNotFoundError as exc:  # pragma: no cover - exercised via import mock
+            raise ImportError(
+                "YAML support requires PyYAML. Install it with: "
+                'pip install "python-statemachine[yaml]"'
+            ) from exc
+        return yaml.load(text, Loader=_make_loader(yaml))  # type: ignore[no-any-return]
+
+    def read(self, text: str, *, source_name: "str | None" = None) -> StateMachineDefinition:
+        return native_dict_to_definition(self.parse_document(text), source_name=source_name)
+
+
+register_format(
+    FormatSpec(
+        name="yaml",
+        extensions=(".yaml", ".yml"),
+        reader_factory=YAMLReader,
+    )
+)

statemachine/locale/en/LC_MESSAGES/statemachine.po

@@ -5,7 +5,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  3.1.1\n"
 "Report-Msgid-Bugs-To: fgmacedo@gmail.com\n"
-"POT-Creation-Date: 2026-05-18 16:16-0300\n"
+"POT-Creation-Date: 2026-06-16 23:00-0300\n"
 "PO-Revision-Date: 2026-02-24 14:31-0300\n"
 "Last-Translator: Fernando Macedo <fgmacedo@gmail.com>\n"
 "Language: en\n"
@@ -16,12 +16,12 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "Generated-By: Babel 2.18.0\n"
 
-#: statemachine/callbacks.py:404 statemachine/callbacks.py:409
+#: statemachine/callbacks.py:398 statemachine/callbacks.py:403
 #, python-brace-format
 msgid "Did not found name '{}' from model or statemachine"
 msgstr "Did not found name '{}' from model or statemachine"
 
-#: statemachine/configuration.py:129
+#: statemachine/configuration.py:128
 msgid ""
 "There's no current state set. In async code, did you activate the initial"
 " state? (e.g., `await sm.activate_initial_state()`)"
@@ -29,12 +29,12 @@ msgstr ""
 "There's no current state set. In async code, did you activate the initial"
 " state? (e.g., `await sm.activate_initial_state()`)"
 
-#: statemachine/dispatcher.py:126
+#: statemachine/dispatcher.py:123
 #, python-brace-format
 msgid "Failed to parse boolean expression '{}'"
 msgstr "Failed to parse boolean expression '{}'"
 
-#: statemachine/event.py:95
+#: statemachine/event.py:94
 #, python-brace-format
 msgid ""
 "Event() received a non-string 'id' ({cls_name}). To combine multiple "
@@ -43,12 +43,12 @@ msgstr ""
 "Event() received a non-string 'id' ({cls_name}). To combine multiple "
 "transitions under one event, use the | operator: t1 | t2."
 
-#: statemachine/event.py:131
+#: statemachine/event.py:130
 #, python-brace-format
 msgid "Cannot add callback '{}' to an event with no transitions."
 msgstr "Cannot add callback '{}' to an event with no transitions."
 
-#: statemachine/event.py:164
+#: statemachine/event.py:163
 #, python-brace-format
 msgid "Event {} cannot be called without a SM instance"
 msgstr "Event {} cannot be called without a SM instance"
@@ -63,7 +63,7 @@ msgstr "{!r} is not a valid state value."
 msgid "Can't {} when in {}."
 msgstr "Can't {} when in {}."
 
-#: statemachine/factory.py:81
+#: statemachine/factory.py:77
 #, python-brace-format
 msgid ""
 "There should be one and only one initial state. Your currently have "
@@ -72,7 +72,7 @@ msgstr ""
 "There should be one and only one initial state. Your currently have "
 "these: {0}"
 
-#: statemachine/factory.py:198
+#: statemachine/factory.py:194
 #, python-brace-format
 msgid ""
 "There should be one and only one initial state. You currently have these:"
@@ -81,12 +81,12 @@ msgstr ""
 "There should be one and only one initial state. You currently have these:"
 " {!r}"
 
-#: statemachine/factory.py:213
+#: statemachine/factory.py:209
 #, python-brace-format
 msgid "Cannot declare transitions from final state. Invalid state(s): {}"
 msgstr "Cannot declare transitions from final state. Invalid state(s): {}"
 
-#: statemachine/factory.py:225
+#: statemachine/factory.py:221
 #, python-brace-format
 msgid ""
 "All non-final states should have at least one outgoing transition. These "
@@ -95,7 +95,7 @@ msgstr ""
 "All non-final states should have at least one outgoing transition. These "
 "states have no outgoing transition: {!r}"
 
-#: statemachine/factory.py:239
+#: statemachine/factory.py:235
 #, python-brace-format
 msgid ""
 "All non-final states should have at least one path to a final state. "
@@ -104,7 +104,7 @@ msgstr ""
 "All non-final states should have at least one path to a final state. "
 "These states have no path to a final state: {!r}"
 
-#: statemachine/factory.py:252
+#: statemachine/factory.py:248
 #, python-brace-format
 msgid ""
 "There are unreachable states. The statemachine graph should have a single"
@@ -113,7 +113,7 @@ msgstr ""
 "There are unreachable states. The statemachine graph should have a single"
 " component. Disconnected states: {}"
 
-#: statemachine/factory.py:289
+#: statemachine/factory.py:285
 #, python-brace-format
 msgid ""
 "Invalid entry in 'listeners': {!r}. Expected a class, callable, or "
@@ -122,7 +122,7 @@ msgstr ""
 "Invalid entry in 'listeners': {!r}. Expected a class, callable, or "
 "listener instance."
 
-#: statemachine/factory.py:388
+#: statemachine/factory.py:384
 #, python-brace-format
 msgid "An event in the '{}' has no id."
 msgstr "An event in the '{}' has no id."
@@ -132,20 +132,20 @@ msgstr "An event in the '{}' has no id."
 msgid "{!r} is not a valid state machine name."
 msgstr "{!r} is not a valid state machine name."
 
-#: statemachine/state.py:250
+#: statemachine/state.py:249
 msgid "'donedata' can only be specified on final states."
 msgstr "'donedata' can only be specified on final states."
 
-#: statemachine/statemachine.py:169
+#: statemachine/statemachine.py:167
 msgid "There are no states or transitions."
 msgstr "There are no states or transitions."
 
-#: statemachine/statemachine.py:239
+#: statemachine/statemachine.py:237
 #, python-brace-format
 msgid "State overriding is not allowed. Trying to add '{}' to {}"
 msgstr "State overriding is not allowed. Trying to add '{}' to {}"
 
-#: statemachine/transition.py:75
+#: statemachine/transition.py:74
 #, python-brace-format
 msgid ""
 "Not a valid internal transition from source {source!r}, target {target!r}"