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

statemachine/io/{scxml/invoke.py → invoke.py}

@@ -1,27 +1,35 @@
-"""SCXML-specific invoke handler.
+"""Format-neutral invoke handler.
 
-Implements the IInvoke protocol by resolving child SCXML content (inline or
-via src/srcexpr), evaluating params/namelist in the parent context, and managing
-the child machine lifecycle including ``#_parent`` routing, autoforward, and
-finalize.
+Implements the engine's ``IInvoke`` protocol: resolves a child statechart (inline
+content, ``src`` file, or ``srcexpr``), evaluates ``params``/``namelist`` in the parent
+context, and manages the child machine lifecycle including ``#_parent`` routing,
+autoforward and finalize.
+
+The child is compiled via the ``register_child`` callback (which the interpreter wires to
+its own format reader), so invoke is not tied to SCXML: a child may be authored in any
+format the interpreter understands.
 """
 
 import asyncio
 import logging
+from collections.abc import Callable
 from inspect import isawaitable
 from pathlib import Path
 from typing import Any
-from typing import Callable
 
-from ...invoke import IInvoke
-from ...invoke import InvokeContext
+from ..invoke import IInvoke
+from ..invoke import InvokeContext
 from .actions import ExecuteBlock
-from .actions import _eval
-from .schema import InvokeDefinition
+from .actions import _ensure_writable_target
+from .evaluators import Evaluator
+from .model import InvokeDefinition
+from .model import StateMachineDefinition
+from .system_variables import EventDataWrapper
 
 logger = logging.getLogger(__name__)
 
-_VALID_INVOKE_TYPES = {
+#: Invoke ``type`` values understood by the runtime (SCXML processor URLs + ``None``).
+VALID_INVOKE_TYPES = {
     None,
     "scxml",
     "http://www.w3.org/TR/scxml",
@@ -30,10 +38,10 @@ _VALID_INVOKE_TYPES = {
 }
 
 
-class SCXMLInvoker:
-    """SCXML-specific invoke handler implementing the IInvoke protocol.
+class Invoker:
+    """Invoke handler implementing the IInvoke protocol.
 
-    Resolves the child SCXML from inline content, src file, or srcexpr,
+    Resolves the child statechart from inline content, a ``src`` file or ``srcexpr``,
     evaluates params/namelist, and manages the child machine lifecycle.
     """
 
@@ -41,12 +49,20 @@ class SCXMLInvoker:
         self,
         definition: InvokeDefinition,
         base_dir: str,
-        register_child: "Callable[[str, str], type]",
+        register_child: "Callable[[StateMachineDefinition | str, str], type]",
+        evaluator: Evaluator,
     ):
         self._definition = definition
         self._register_child = register_child
         self._child: Any = None
         self._base_dir: str = base_dir
+        self._evaluator: Evaluator = evaluator
+
+        # A static ``src`` is known at load time, so reject it now (like <data src> /
+        # <script>) for a clean, propagating error. A dynamic ``srcexpr`` can only be
+        # resolved at runtime and is gated again in ``_resolve_content``.
+        if definition.content is None and definition.src is not None:
+            self._evaluator.ensure_external_src_allowed("<invoke src=...>")
 
         # Duck-typed attributes for InvokeManager
         self.invoke_id: "str | None" = definition.id
@@ -56,7 +72,10 @@ class SCXMLInvoker:
         # Pre-compile finalize block
         self._finalize_block: "ExecuteBlock | None" = None
         if definition.finalize and not definition.finalize.is_empty:
-            self._finalize_block = ExecuteBlock(definition.finalize)
+            self._finalize_block = ExecuteBlock(definition.finalize, self._evaluator)
+
+    def _eval(self, expr: str, machine) -> Any:
+        return self._evaluator.compile_value(expr)(machine=machine)
 
     def run(self, ctx: InvokeContext) -> Any:
         """Create and run the child state machine."""
@@ -64,32 +83,33 @@ class SCXMLInvoker:
 
         # Store invokeid in idlocation if specified
         if self.idlocation:
+            _ensure_writable_target(self.idlocation, "<invoke> 'idlocation'")
             setattr(machine.model, self.idlocation, ctx.invokeid)
 
         # Resolve invoke type
         invoke_type = self._definition.type
         if self._definition.typeexpr:
-            invoke_type = _eval(self._definition.typeexpr, machine=machine)
+            invoke_type = self._eval(self._definition.typeexpr, machine=machine)
 
-        if invoke_type not in _VALID_INVOKE_TYPES:
+        if invoke_type not in VALID_INVOKE_TYPES:
             raise ValueError(
-                f"Unsupported invoke type: {invoke_type}. Supported types: {_VALID_INVOKE_TYPES}"
+                f"Unsupported invoke type: {invoke_type}. Supported types: {VALID_INVOKE_TYPES}"
             )
 
-        # Resolve child SCXML content
-        scxml_content = self._resolve_content(machine)
-        if scxml_content is None:
+        # Resolve child statechart content
+        child_content = self._resolve_content(machine)
+        if child_content is None:
             raise ValueError("No content resolved for <invoke>")
 
         # Evaluate params and namelist
         invoke_params = self._evaluate_params(machine)
 
         # Parse and create the child machine
-        child_cls = self._create_child_class(scxml_content, ctx.invokeid)
+        child_cls = self._create_child_class(child_content, ctx.invokeid)
 
         # _invoke_session and _invoke_params are passed as kwargs so that the
         # invoke_init callback (inserted at position 0 in the initial state's onentry
-        # by the processor) can pop them and store them on the machine instance.
+        # by the interpreter) can pop them and store them on the machine instance.
         #
         # The _ChildRefSetter listener captures ``self._child`` during the first
         # state entry, before the processing loop blocks.  This is necessary
@@ -108,7 +128,7 @@ class SCXMLInvoker:
 
     def on_cancel(self):
         """Cancel the child machine and all its invocations."""
-        from ...invoke import _stop_child_machine
+        from ..invoke import _stop_child_machine
 
         _stop_child_machine(self._child)
         self._child = None
@@ -129,49 +149,65 @@ class SCXMLInvoker:
                 "machine": machine,
                 "model": machine.model,
             }
-            # Inject SCXML context variables
-            from .actions import EventDataWrapper
-
             kwargs.update(
                 {k: v for k, v in machine.model.__dict__.items() if not k.startswith("_")}
             )
-            # Build EventDataWrapper from trigger_data's kwargs
             kwargs["_event"] = EventDataWrapper.from_trigger_data(trigger_data)
             self._finalize_block(**kwargs)
 
-    def _resolve_content(self, machine) -> "str | None":
-        """Resolve the child SCXML content from content/src/srcexpr."""
+    def _resolve_content(self, machine):
+        """Resolve the child statechart content from content/src/srcexpr.
+
+        Returns either a source string (file text / inline document text) that the reader
+        will parse, or an already-parsed definition (native inline child), which the
+        interpreter registers directly.
+        """
         defn = self._definition
 
-        if defn.content:
-            # Content could be an expr to evaluate or inline SCXML
-            if defn.content.lstrip().startswith("<"):
-                return defn.content
+        if defn.content is not None:
+            content = defn.content
+            if not isinstance(content, str):
+                # Native inline child: an already-parsed StateMachineDefinition.
+                return content
+            if self._is_inline_document(content):
+                return content
             # It's an expression — evaluate it
-            result = _eval(defn.content, machine=machine)
+            result = self._eval(content, machine=machine)
             if isinstance(result, str):
                 return result
             return str(result)
 
         if defn.srcexpr:
-            src = _eval(defn.srcexpr, machine=machine)
+            src = self._eval(defn.srcexpr, machine=machine)
         elif defn.src:
             src = defn.src
         else:
             return None
 
+        # Reading a local file named by an untrusted document is a confidentiality risk,
+        # so it is gated on the trust level (mirrors <script> / <data src>).
+        self._evaluator.ensure_external_src_allowed("<invoke src=...>")
+
         # Handle file: URIs and relative paths
         if src.startswith("file:"):
             path = Path(src.removeprefix("file:"))
         else:
             path = Path(src)
 
-        # Resolve relative to the base directory of the parent SCXML file
+        # Resolve relative to the base directory of the parent document
         if not path.is_absolute():
             path = Path(self._base_dir) / path
 
         return path.read_text()
 
+    @staticmethod
+    def _is_inline_document(content: str) -> bool:
+        """Whether ``content`` is an inline document (vs an expression to evaluate).
+
+        The default heuristic recognizes inline XML (SCXML). Other formats may override.
+        """
+        return content.lstrip().startswith("<")
+
     def _evaluate_params(self, machine) -> dict:
         """Evaluate params and namelist into a dict of values."""
         defn = self._definition
@@ -186,28 +222,28 @@ class SCXMLInvoker:
         # Evaluate param elements
         for param in defn.params:
             if param.expr is not None:
-                result[param.name] = _eval(param.expr, machine=machine)
+                result[param.name] = self._eval(param.expr, machine=machine)
             elif param.location is not None:
-                result[param.name] = _eval(param.location, machine=machine)
+                result[param.name] = self._eval(param.location, machine=machine)
 
         return result
 
-    def _create_child_class(self, scxml_content: str, invokeid: str):
-        """Parse the child SCXML and create a machine class."""
+    def _create_child_class(self, content: "StateMachineDefinition | str", invokeid: str):
+        """Compile the child statechart and create a machine class."""
         child_name = f"invoke_{invokeid}"
-        return self._register_child(scxml_content, child_name)
+        return self._register_child(content, child_name)
 
 
 class _ChildRefSetter:
     """Listener that captures the child machine reference during initialization.
 
     The child's ``__init__`` blocks inside the processing loop (e.g. when there
-    are delayed events).  By using this listener, ``SCXMLInvoker._child`` is set
-    during the first state entry — *before* the processing loop starts spinning —
-    so that ``on_event()`` can forward events to the child immediately.
+    are delayed events).  By using this listener, ``Invoker._child`` is set during
+    the first state entry — *before* the processing loop starts spinning — so that
+    ``on_event()`` can forward events to the child immediately.
     """
 
-    def __init__(self, invoker: "SCXMLInvoker"):
+    def __init__(self, invoker: "Invoker"):
         self._invoker = invoker
 
     def on_enter_state(self, machine=None, **kwargs):
@@ -221,13 +257,17 @@ class _InvokeSession:
     def __init__(self, parent, invokeid: str):
         self.parent = parent
         self.invokeid = invokeid
+        self._pending_tasks: "set[asyncio.Future]" = set()
+        """Strong refs to scheduled sends; the loop only holds weak refs to tasks."""
 
     def send_to_parent(self, event: str, **data):
         """Send an event to the parent machine's external queue."""
         result = self.parent.send(event, _invokeid=self.invokeid, **data)
         if isawaitable(result):
-            asyncio.ensure_future(result)
+            task = asyncio.ensure_future(result)
+            self._pending_tasks.add(task)
+            task.add_done_callback(self._pending_tasks.discard)
 
 
 # Verify protocol compliance at import time
-assert isinstance(SCXMLInvoker.__new__(SCXMLInvoker), IInvoke)
+assert isinstance(Invoker.__new__(Invoker), IInvoke)

statemachine/io/json/__init__.py

@@ -0,0 +1 @@
+"""JSON statechart format adapter."""

statemachine/io/json/reader.py

@@ -0,0 +1,27 @@
+"""JSON format adapter: parse a JSON statechart document into the neutral IR."""
+
+import json
+
+from ..model import StateMachineDefinition
+from ..native import native_dict_to_definition
+from ..ports import FormatSpec
+from ..ports import register_format
+
+
+class JSONReader:
+    """Format adapter that parses JSON documents (stdlib :mod:`json`) into the IR."""
+
+    def parse_document(self, text: str) -> dict:
+        return json.loads(text)  # 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="json",
+        extensions=(".json",),
+        reader_factory=JSONReader,
+    )
+)

statemachine/io/loader.py

@@ -0,0 +1,175 @@
+"""High-level, format-neutral facade for loading statecharts.
+
+:func:`load` is the simple entry point: give it a file path (format detected by
+extension) or inline content (with an explicit ``format=``) and it returns the
+ready-to-instantiate :class:`~statemachine.statemachine.StateChart` class. It is
+**secure by default** — expressions are evaluated by a restricted AST-allowlist
+evaluator and ``<script>`` / arbitrary Python is rejected unless ``trusted=True``.
+
+For advanced scenarios (a document declaring several statecharts, or SCXML files
+that import/invoke others), use :func:`build_processor` to get the underlying
+processor and reach ``.scs`` / ``.start()``.
+"""
+
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from typing import cast
+
+from ..statemachine import StateChart
+from .evaluators import evaluator_for
+from .interpreter import Interpreter
+from .json import reader as _json_reader  # noqa: F401
+from .ports import detect_format
+from .ports import get_format
+
+# Importing the reader modules registers their formats (extensions). None of these
+# imports pulls in PyYAML or jsonschema at module load time.
+from .scxml import reader as _scxml_reader  # noqa: F401
+from .yaml import reader as _yaml_reader  # noqa: F401
+
+
+@contextmanager
+def _chdir(new_dir: Path):
+    original = os.getcwd()
+    try:
+        os.chdir(new_dir)
+        yield
+    finally:
+        os.chdir(original)
+
+
+def _is_existing_file(source: str) -> bool:
+    """Whether ``source`` names an existing file, treating "too long"/invalid as not a file.
+
+    A long single-line inline document (e.g. minified JSON) is not a path, but reaches
+    :meth:`Path.is_file`, which on some platforms raises ``OSError`` (``ENAMETOOLONG``) or
+    ``ValueError`` (embedded NUL) instead of returning ``False``. Swallow those so inline
+    content is never mistaken for a crash; a real, resolvable path still returns ``True``.
+    """
+    try:
+        return Path(source).is_file()
+    except (OSError, ValueError):
+        return False
+
+
+def _resolve_source(source: "str | Path", format: "str | None"):
+    """Return ``(text, format_name, location_hint, base_dir)`` for a source.
+
+    A :class:`~pathlib.Path`, or a single-line string naming an existing file, is
+    read from disk (format detected by extension unless overridden). Any other
+    string is treated as inline content and requires an explicit ``format``.
+    """
+    if isinstance(source, Path):
+        path: "Path | None" = source
+    elif "\n" not in source and _is_existing_file(source):
+        path = Path(source)
+    else:
+        path = None
+
+    if path is not None:
+        text = path.read_text()
+        fmt = detect_format(path, format)
+        return text, fmt, path.stem, path.parent
+
+    fmt = detect_format(Path("<inline>"), format)
+    return source, fmt, None, None
+
+
+def _build(source, *, format, trusted, validate, name):
+    """Shared pipeline: read source -> IR -> interpreter (returns ``(interpreter, location)``)."""
+    text, fmt, location_hint, base_dir = _resolve_source(source, format)
+    spec = get_format(fmt)
+    reader = spec.reader_factory()
+
+    parse_document = getattr(reader, "parse_document", None)
+    if validate and parse_document is None:
+        raise ValueError(
+            f"validate=True is not supported for the {fmt!r} format; "
+            "validation applies to the native JSON/YAML schema."
+        )
+
+    def _read_and_build():
+        # Parsing and compilation both run here, inside the file's directory when loading
+        # from a file, so a reader that resolves external references (e.g. SCXML
+        # ``<data src="...">``) and invoke ``src`` resolve relative to the document.
+        if parse_document is not None:
+            doc = parse_document(text)
+            if validate:
+                from .validation import validate_document
+
+                validate_document(doc)
+            from .native import native_dict_to_definition
+
+            definition = native_dict_to_definition(doc, source_name=name or location_hint)
+        else:
+            definition = reader.read(text, source_name=name or location_hint)
+
+        location = name or definition.name or location_hint or "statechart"
+        # The runtime is the format-neutral Interpreter, wired with this format's reader
+        # (so invoked children compile in the same format) and the chosen evaluator.
+        interpreter = Interpreter(reader=reader, evaluator=evaluator_for(trusted))
+        interpreter.process_definition(definition, location=location)
+        return interpreter, location
+
+    if base_dir is not None:
+        with _chdir(base_dir):
+            return _read_and_build()
+    return _read_and_build()
+
+
+def build_processor(
+    source: "str | Path",
+    *,
+    format: "str | None" = None,
+    trusted: bool = False,
+    validate: bool = False,
+    name: "str | None" = None,
+):
+    """Load a statechart and return the underlying interpreter (low-level API).
+
+    Returns the :class:`~statemachine.io.interpreter.Interpreter`. Use it when you need
+    access to ``interpreter.scs`` (all compiled classes) or ``interpreter.start(...)`` —
+    e.g. documents that invoke/import children. See :func:`load` for the argument semantics.
+    """
+    interpreter, _location = _build(
+        source, format=format, trusted=trusted, validate=validate, name=name
+    )
+    return interpreter
+
+
+def load(
+    source: "str | Path",
+    *,
+    format: "str | None" = None,
+    trusted: bool = False,
+    validate: bool = False,
+    name: "str | None" = None,
+) -> "type[StateChart]":
+    """Load a statechart from a file or inline content and return its class.
+
+    Args:
+        source: a file path (``str``/:class:`~pathlib.Path`; format detected from
+            the extension) or inline document content (requires ``format``).
+        format: explicit format name (``"scxml"``, ``"json"``, ``"yaml"``),
+            overriding extension detection and required for inline content.
+        trusted: when ``False`` (default), expressions are evaluated by a restricted
+            AST-allowlist evaluator and ``<script>`` / arbitrary Python is rejected.
+            When ``True``, expressions and scripts are evaluated as arbitrary Python.
+        validate: when ``True`` (native JSON/YAML only), validate the document against
+            the published JSON Schema before building (requires the ``[validation]``
+            extra).
+        name: explicit name for the generated class (defaults to the document name
+            or the file stem).
+
+    Returns:
+        The :class:`~statemachine.statemachine.StateChart` subclass. Instantiate it
+        to run the machine (``load("m.yaml")()``).
+    """
+    interpreter, location = _build(
+        source, format=format, trusted=trusted, validate=validate, name=name
+    )
+    cls = interpreter.scs[location]
+    # Keep the interpreter reachable (and alive) from the returned class.
+    cls._io_processor = interpreter  # pyright: ignore[reportAttributeAccessIssue]
+    return cast("type[StateChart]", cls)