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

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,161 @@
+"""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-whitelist
+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 _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 Path(source).is_file():
+        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-whitelist 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)

statemachine/io/model.py

@@ -0,0 +1,268 @@
+"""Format-neutral intermediate representation (IR) of a statechart.
+
+These dataclasses are the common target every format reader (SCXML, JSON, YAML)
+produces, and the single input the :class:`~statemachine.io.processor.GenericProcessor`
+consumes to build a :class:`~statemachine.statemachine.StateChart` class. They carry
+the *structure* of a statechart (states, transitions, executable content, datamodel)
+as plain data, with expressions kept as un-evaluated strings; turning those strings
+into callables is the evaluator's job, not the IR's.
+
+The vocabulary mirrors the SCXML semantic model (the formalism this library
+standardizes on) plus a few optional callback-reference fields used by the native
+JSON/YAML format to integrate with methods on a bound model.
+"""
+
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Literal
+
+
+@dataclass
+class Action:
+    def __str__(self):
+        return f"{self.__class__.__name__}"
+
+
+@dataclass
+class ExecutableContent:
+    """An ordered block of actions (the body of an ``onentry``/``onexit``/transition).
+
+    A state may carry several blocks (SCXML allows multiple ``<onentry>`` elements),
+    which is why ``State.onentry``/``onexit`` are *lists* of ``ExecutableContent``.
+    """
+
+    actions: list[Action] = field(default_factory=list)
+
+    def __str__(self):
+        return ", ".join(str(action) for action in self.actions)
+
+    @property
+    def is_empty(self):
+        return not self.actions
+
+
+@dataclass
+class RaiseAction(Action):
+    event: str
+
+
+@dataclass
+class AssignAction(Action):
+    """Assign a value to a datamodel location (``location = expr``).
+
+    ``location`` is a dotted attribute path on the model (e.g. ``user.name``).
+    ``expr`` is the value expression; when it is ``None``, ``child_xml`` carries the
+    literal inline XML/text assigned instead (SCXML ``<assign>`` with element body).
+    """
+
+    location: str
+    expr: "str | None" = None
+    child_xml: "str | None" = None
+
+
+@dataclass
+class LogAction(Action):
+    label: "str | None"
+    expr: "str | None"
+
+
+@dataclass
+class IfBranch(Action):
+    """One branch of an :class:`IfAction`.
+
+    ``cond`` is the guard expression for this branch. A ``cond`` of ``None`` marks the
+    final ``else`` branch, which always matches.
+    """
+
+    cond: "str | None"
+    actions: list[Action] = field(default_factory=list)
+
+    def __str__(self):
+        return self.cond or "<empty cond>"
+
+    def append(self, action: Action):
+        self.actions.append(action)
+
+
+@dataclass
+class IfAction(Action):
+    """An ``if``/``elif``/``else`` chain.
+
+    ``branches`` is ordered and evaluated top to bottom; the first branch whose ``cond``
+    is truthy runs its actions and the rest are skipped. By convention the first branch
+    is the ``if``, intermediate branches with a ``cond`` are ``elif``, and a trailing
+    branch with ``cond=None`` is the ``else`` (see :class:`IfBranch`).
+    """
+
+    branches: list[IfBranch] = field(default_factory=list)
+
+
+@dataclass
+class ForeachAction(Action):
+    """Iterate ``item`` (and optional ``index``) over the iterable ``array`` evaluates to,
+    running ``content`` once per element."""
+
+    array: str
+    item: str
+    index: "str | None"
+    content: ExecutableContent
+
+
+@dataclass
+class Param:
+    name: str
+    expr: "str | None"
+    location: "str | None" = None
+
+
+@dataclass
+class SendAction(Action):
+    event: "str | None" = None
+    eventexpr: "str | None" = None
+    target: "str | None" = None
+    type: "str | None" = None
+    id: "str | None" = None
+    idlocation: "str | None" = None
+    delay: "str | None" = None
+    delayexpr: "str | None" = None
+    namelist: "str | None" = None
+    params: list[Param] = field(default_factory=list)
+    content: "str | None" = None
+
+
+@dataclass
+class CancelAction(Action):
+    sendid: "str | None" = None
+    sendidexpr: "str | None" = None
+
+
+@dataclass
+class ScriptAction(Action):
+    content: str
+
+
+@dataclass
+class Transition:
+    """A transition out of a state.
+
+    Two attributes carry non-obvious conventions:
+
+    - ``event=None`` makes the transition **eventless**: it fires automatically
+      whenever ``cond`` holds (the SCXML NULL transition), instead of on a named event.
+    - ``target=None`` makes it **targetless**: taking it runs ``on`` but does not change
+      the active configuration (a self-action with no state change).
+
+    ``cond``/``unless`` are guard expressions and may be a single string or a list (all
+    must hold). ``on`` is the executable content run when the transition is taken.
+    """
+
+    target: "str | None" = None
+    internal: bool = False
+    initial: bool = False
+    event: "str | None" = None
+    cond: "str | None | list" = None
+    on: "ExecutableContent | None" = None
+    unless: "str | None | list" = None
+    """Negated guard expression (or list); allowed only if falsy. Native format only."""
+    on_refs: list = field(default_factory=list)
+    """Extra ``on`` callbacks referenced by name. Native JSON/YAML format only (the SCXML
+    reader leaves it empty)."""
+    before: "ExecutableContent | None" = None
+    """``before`` executable content (the library lifecycle slot that runs once the guards
+    pass, before the state change). Native format only; SCXML has no equivalent slot."""
+    before_refs: list = field(default_factory=list)
+    """Extra ``before`` callbacks referenced by name. Native format only."""
+    after: "ExecutableContent | None" = None
+    """``after`` executable content (runs after the configuration has settled). Native
+    format only; SCXML has no equivalent slot."""
+    after_refs: list = field(default_factory=list)
+    """Extra ``after`` callbacks referenced by name. Native format only."""
+
+
+@dataclass
+class DoneData:
+    params: list[Param] = field(default_factory=list)
+    content_expr: "str | None" = None
+
+
+@dataclass
+class InvokeDefinition:
+    type: "str | None" = None
+    typeexpr: "str | None" = None
+    src: "str | None" = None
+    srcexpr: "str | None" = None
+    id: "str | None" = None
+    idlocation: "str | None" = None
+    autoforward: bool = False
+    namelist: "str | None" = None
+    params: list[Param] = field(default_factory=list)
+    content: "str | StateMachineDefinition | None" = None
+    """Inline child content. A string (inline SCXML, or an expression to evaluate) or, for
+    the native format, an already-parsed :class:`StateMachineDefinition`."""
+    finalize: "ExecutableContent | None" = None
+
+
+@dataclass
+class State:
+    """A state node.
+
+    ``parallel`` marks an orthogonal region (all child states are active at once);
+    ``final`` marks an accepting state (which may carry ``donedata``). ``states`` holds
+    nested children (compound state), keyed by id.
+    """
+
+    id: str
+    initial: bool = False
+    final: bool = False
+    parallel: bool = False
+    transitions: list[Transition] = field(default_factory=list)
+    onentry: list[ExecutableContent] = field(default_factory=list)
+    onexit: list[ExecutableContent] = field(default_factory=list)
+    states: dict[str, "State"] = field(default_factory=dict)
+    history: dict[str, "HistoryState"] = field(default_factory=dict)
+    donedata: "DoneData | None" = None
+    invocations: list[InvokeDefinition] = field(default_factory=list)
+    enter_refs: list = field(default_factory=list)
+    """``enter`` callbacks referenced by name, appended after the ``onentry`` content.
+    Native JSON/YAML format only (the SCXML reader leaves it empty)."""
+    exit_refs: list = field(default_factory=list)
+    """``exit`` callbacks referenced by name, appended after the ``onexit`` content.
+    Native format only."""
+
+
+@dataclass
+class HistoryState:
+    id: str
+    type: "Literal['shallow', 'deep']" = "shallow"
+    transitions: list[Transition] = field(default_factory=list)
+
+
+@dataclass
+class DataItem:
+    """A datamodel variable initializer (``id``), from ``expr``, inline ``content`` or
+    an external ``src`` location (kept as a raw string; URL parsing happens in the reader)."""
+
+    id: str
+    src: "str | None"
+    expr: "str | None"
+    content: "str | None"
+
+
+@dataclass
+class DataModel:
+    data: list[DataItem] = field(default_factory=list)
+    scripts: list[ScriptAction] = field(default_factory=list)
+
+
+@dataclass
+class StateMachineDefinition:
+    """Top-level, format-neutral statechart definition produced by every reader.
+
+    ``initial_states`` is a list because the initial configuration may name several
+    states at once (one per parallel region).
+    """
+
+    name: "str | None" = None
+    states: dict[str, State] = field(default_factory=dict)
+    initial_states: list[str] = field(default_factory=list)
+    datamodel: "DataModel | None" = None