python-statemachine 3.2.0__tar.gz → 3.2.1__tar.gz

python_statemachine-3.2.1/.github/workflows/pages.yml

@@ -0,0 +1,51 @@
+name: pages
+
+# Publishes the static assets served at https://fgmacedo.github.io/python-statemachine/
+# Currently: the native statechart JSON Schema, at the canonical URL used as its `$id`
+# (statemachine/io/schemas/statechart.schema.json -> /schemas/statechart/v1.json).
+
+on:
+  push:
+    branches: [develop]
+    paths:
+      - statemachine/io/schemas/statechart.schema.json
+      - .github/workflows/pages.yml
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress publish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v5
+      - name: Assemble site
+        run: |
+          mkdir -p _site/schemas/statechart
+          cp statemachine/io/schemas/statechart.schema.json _site/schemas/statechart/v1.json
+          cat > _site/index.html <<'HTML'
+          <!doctype html>
+          <meta charset="utf-8">
+          <title>python-statemachine</title>
+          <meta http-equiv="refresh" content="0; url=https://python-statemachine.readthedocs.io/">
+          <p>See the <a href="schemas/statechart/v1.json">statechart JSON Schema</a> or the
+          <a href="https://python-statemachine.readthedocs.io/">documentation</a>.</p>
+          HTML
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+      - id: deployment
+        uses: actions/deploy-pages@v4

{python_statemachine-3.2.0 → python_statemachine-3.2.1}/AGENTS.md

@@ -302,6 +302,10 @@ enforced, so when you add or change native vocabulary:
 - Signed commits preferred (`git commit -s`)
 - Use [Conventional Commits](https://www.conventionalcommits.org/) messages
   (e.g., `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, `perf:`)
+- **NEVER bypass pre-commit hooks** (`--no-verify`, `-n`, or disabling hooks). The hooks
+  inspect every commit to keep regressions out; only the maintainer may decide to skip them.
+  If a hook modifies files (e.g. `generate-images` regenerating a diagram PNG), stage the
+  generated changes and commit again until the hooks pass — do not skip them.
 
 ## Security
 

{python_statemachine-3.2.0 → python_statemachine-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-statemachine
-Version: 3.2.0
+Version: 3.2.1
 Summary: Python Finite State Machines made easy.
 Project-URL: homepage, https://github.com/fgmacedo/python-statemachine
 Author-email: Fernando Macedo <fgmacedo@gmail.com>

{python_statemachine-3.2.0 → python_statemachine-3.2.1}/docs/actions.md

@@ -145,10 +145,13 @@ levels of the hierarchy.
 
 ```{note}
 The generic `on_exit_state()` and `on_enter_state()` callbacks also fire
-once per state in the set, but the `state` parameter is bound to the
-transition's `source` or `target` — not the individual state being
-exited/entered. Use `event_data` if you need the full context, or prefer
-state-specific callbacks for clarity.
+once per state in the set, and the `state` parameter is bound to the
+individual state being exited or entered, so you can tell each level of a
+compound apart. On entry, `target` matches `state`; on exit, `source`
+matches `state`. The opposite endpoint stays fixed at the transition's
+`source` (on entry) or `target` (on exit). Prefer state-specific callbacks
+(`on_exit_<state>`, `on_enter_<state>`) when you want to target one level
+directly.
 ```
 
 ```{seealso}

{python_statemachine-3.2.0 → python_statemachine-3.2.1}/docs/behaviour.md

@@ -28,7 +28,7 @@ SCXML-compliant behavior provides more predictable semantics.
 ```{warning}
 This page describes runtime *semantics*. If you **load SCXML documents** via
 `SCXMLProcessor`, note that SCXML is executable content: by default the
-datamodel is evaluated with a restricted AST whitelist and `<script>` is
+datamodel is evaluated with a restricted AST allowlist and `<script>` is
 rejected, so untrusted documents cannot execute arbitrary code. Pass
 `trusted=True` only for SCXML you control. See the 3.2.0 release notes and
 GHSA-v4jc-pm6r-3vj8.
@@ -158,6 +158,10 @@ When `True` (SCXML default), runtime exceptions in action callbacks
 internal `error.execution` events. When `False` (legacy default), exceptions
 propagate normally to the caller.
 
+This flag only governs exceptions raised **inside** an action callback. An event
+that doesn't match any enabled transition is a different case, controlled by
+{ref}`allow_event_without_transition <behaviour>` instead.
+
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the

{python_statemachine-3.2.0 → python_statemachine-3.2.1}/docs/events.md

@@ -131,6 +131,83 @@ delayed events, and cancellation.
 ```
 
 
+(events-as-method-protocol)=
+
+## Events as a method-call protocol
+
+Because every event is a callable method, a state machine can act as a guard
+for the **order** in which your object's methods may be called. Set
+`allow_event_without_transition = False` so that any call that doesn't match an
+enabled transition raises `TransitionNotAllowed` instead of being silently
+ignored. The transitions then describe the legal
+sequence, and the machine enforces it for you:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class Connection(StateChart):
+...     "A client whose methods can only be called in a valid order."
+...     allow_event_without_transition = False  # reject any unexpected call
+...
+...     disconnected = State(initial=True)
+...     connected = State()
+...     authenticated = State()
+...
+...     connect = disconnected.to(connected)
+...     authenticate = connected.to(authenticated)
+...     disconnect = connected.to(disconnected) | authenticated.to(disconnected)
+...
+...     def on_connect(self):
+...         print("socket opened")
+...
+...     def on_authenticate(self):
+...         print("credentials accepted")
+
+```
+
+Calling the methods in a valid order works:
+
+```py
+>>> conn = Connection()
+>>> conn.connect()
+socket opened
+>>> conn.authenticate()
+credentials accepted
+>>> "authenticated" in conn.configuration_values
+True
+
+```
+
+A call that isn't valid in the current state raises, so an out-of-order method
+call fails loudly instead of doing nothing:
+
+```py
+>>> fresh = Connection()
+
+>>> fresh.authenticate()  # must connect first
+Traceback (most recent call last):
+    ...
+statemachine.exceptions.TransitionNotAllowed: Can't Authenticate when in Disconnected.
+
+```
+
+The same protection applies to unknown event names sent dynamically:
+
+```py
+>>> fresh.send("teleport")
+Traceback (most recent call last):
+    ...
+statemachine.exceptions.TransitionNotAllowed: Can't teleport when in Disconnected.
+
+```
+
+```{seealso}
+{ref}`behaviour` explains `allow_event_without_transition` and the other
+class-level flags that switch between this strict mode and the tolerant,
+event-driven default.
+```
+
+
 (event-parameter)=
 
 ## The `event` parameter on transitions

{python_statemachine-3.2.0 → python_statemachine-3.2.1}/docs/guards.md

@@ -132,6 +132,71 @@ example combining multiple transitions on the same event.
 ```
 
 
+(callable conditions)=
+
+### Callable conditions
+
+Besides strings, `cond` and `unless` also accept callables directly, including
+lambdas, allowing simple guards to be defined inline:
+
+```py
+>>> class Turnstile(StateChart):
+...     locked = State(initial=True)
+...     unlocked = State(final=True)
+...
+...     coin = locked.to(unlocked, cond=lambda machine: machine.credits > 0)
+...
+...     credits = 0
+
+>>> sm = Turnstile()
+>>> sm.send("coin")
+>>> "locked" in sm.configuration_values
+True
+
+>>> sm.credits = 1
+>>> sm.send("coin")
+>>> "unlocked" in sm.configuration_values
+True
+
+```
+
+Like any callback, a callable condition receives its arguments via
+{ref}`dependency injection <dependency-injection>`: declare only the
+parameters you need, using the injectable names (`machine`, `event`,
+`source`, `target`, `model`, ...) or the arguments passed when triggering
+the event:
+
+```py
+>>> class Dispatcher(StateChart):
+...     idle = State(initial=True)
+...     dispatched = State(final=True)
+...
+...     dispatch = idle.to(dispatched, cond=lambda priority=0: priority > 5)
+
+>>> sm = Dispatcher()
+>>> sm.send("dispatch", priority=1)
+>>> "idle" in sm.configuration_values
+True
+
+>>> sm.send("dispatch", priority=9)
+>>> "dispatched" in sm.configuration_values
+True
+
+```
+
+```{warning}
+Plain callables, like lambdas and functions defined outside the class body,
+are called **unbound**, so `self` is not injected. A guard declared as
+`cond=lambda self: ...` fails with a `TypeError` when evaluated. Use
+`machine` instead of `self` to receive the state machine instance.
+
+`self` is only available when the callable resolves to a bound method,
+which happens when it is an attribute of the state machine class: either
+referenced by name (`cond="my_condition"`) or defined in the class body
+and passed by reference (`cond=my_condition`).
+```
+
+
 (condition expressions)=
 
 ### Condition expressions

{python_statemachine-3.2.0 → python_statemachine-3.2.1}/docs/how-to/coming_from_transitions.md

@@ -28,6 +28,7 @@ shown side by side where possible. For a quick overview, jump to the
 | Error handling | Exceptions propagate | Optional {ref}`catch_errors_as_events <error-execution>` (`error.execution`) |
 | Validations | None | {ref}`Structural + callback checks <validations>` at definition and creation time |
 | SCXML compliance | [Not a goal](https://github.com/pytransitions/transitions/issues/446#issuecomment-646837282) | {ref}`W3C conformant <processing-model>` with automated test suite |
+| Serialization / loading | `markup` dict round-trip (persist as JSON/YAML yourself; no SCXML) | [Secure `io.load()`](../io/index.md) from SCXML, JSON and YAML |
 | Processing model | Immediate or queued | Always queued ({ref}`run-to-completion <rtc-model>`) |
 
 
@@ -178,7 +179,7 @@ python-statemachine also supports hierarchical features not available in *transi
 See {ref}`compound-states` and {ref}`parallel-states` for the full reference.
 
 
-### Creating machines from dicts
+### Creating machines from dicts and documents
 
 If you prefer the dict-based definition style familiar from *transitions*, you can
 use {func}`~statemachine.io.create_machine_class_from_definition` to build a
@@ -218,6 +219,28 @@ The result is a regular `StateChart` subclass — all features (validations, dia
 listeners, async) work exactly the same way. See
 {func}`~statemachine.io.create_machine_class_from_definition` for the full API.
 
+#### Loading from SCXML, JSON or YAML documents
+
+*transitions* can serialize a built machine to a Python dict with `MarkupMachine`
+(`machine.markup`) and rebuild it via `Machine(markup=...)`. That dict isn't tied to a file
+format — you persist it as JSON/YAML yourself — and callbacks and conditions are method-name
+strings resolved against the model by import at build time, so it isn't designed to load
+untrusted definitions, has no published schema, and doesn't cover SCXML.
+
+python-statemachine provides a first-class, secure loader, {func}`~statemachine.io.load`,
+that reads SCXML, JSON and YAML *documents* straight into a `StateChart`:
+
+```python
+from statemachine.io import load
+
+Machine = load("traffic_light.scxml")   # or .json / .yaml; format detected from the extension
+```
+
+Expressions in the document (guards, datamodel) are evaluated by a restricted allowlist —
+never `eval` — so documents from untrusted sources are safe to load; the native JSON/YAML
+format has a published JSON Schema (`validate=True`), and SCXML follows the W3C execution
+model. See [](../io/index.md) for the full guide.
+
 
 ## Defining transitions
 
@@ -952,6 +975,8 @@ See {ref}`validations` for the full list.
 | {ref}`Listener/observer pattern <listeners>` | No | **Yes** |
 | {ref}`Definition-time validations <validations>` | No | **Yes** |
 | {ref}`SCXML conformance <processing-model>` | No | **Yes** |
+| [Load from SCXML/JSON/YAML documents](../io/index.md) | No | **Yes** |
+| Serialize a built machine to a portable definition | Yes (`markup`) | Partial (load only) |
 | {ref}`Diagrams <diagrams>` | Yes | Yes |
 | {ref}`Django integration <machinemixin>` | Community | Built-in |
 | {ref}`Model binding <models>` | Yes | Yes |

python_statemachine-3.2.1/docs/io/security.md

@@ -0,0 +1,217 @@
+# Security: secure by default
+
+Loading a statechart compiles its guards, datamodel expressions and executable content into
+callables. A statechart is an **executable document**, not inert data, so loading one is closer
+to importing code than to parsing JSON. The IO layer is **secure by default** (`trusted=False`)
+so that loading a semi-trusted document does not turn into code execution or file disclosure,
+but it is worth being precise about what that guarantee does and does not cover.
+
+## Intended use, and the limits of "safe"
+
+The primary use case for declarative loading is your **own** dynamic definitions: statecharts
+produced by your application, a no-code editor you ship, your own tooling, or configuration you
+control. For those, `trusted=False` is a defense-in-depth backstop.
+
+Loading a document authored by a genuine **adversary** is a stronger threat. `trusted=False`
+removes the obvious code- and file-execution vectors described below, but a statechart is still
+an executable document: the most reliable protection against a hostile document is to not run
+it, or to run it under OS-level isolation (see [](#availability-is-not-sandboxed)). Treat
+`trusted=False` as *hardening*, not as a sandbox, and do not rely on it as your only control
+for documents from parties you do not trust.
+
+## What the guarantee covers (and what it does not)
+
+Loading a statechart produces a **runnable machine**, not the inert data `yaml.safe_load`
+returns. So the `trusted` flag is best understood as a guarantee about **confidentiality and
+integrity**, not about **availability**:
+
+- **Loading is safe (confidentiality + integrity).** With the default `trusted=False`, loading
+  a document never runs arbitrary code and never reads arbitrary files. Expressions go through a
+  restricted evaluator (below), `<script>` is rejected, and external resource references
+  (`<data src>`, `<invoke src>`) are rejected. YAML is read with safe-load semantics and JSON
+  with the stdlib parser, so a document can never instantiate arbitrary Python objects.
+- **Running is not sandboxed (availability).** Once you start a machine, the document's logic
+  executes. `trusted` does **not** bound how much CPU, memory or time that logic consumes. A
+  malicious document can still cause denial of service. See [](#availability-is-not-sandboxed).
+
+## The two evaluation modes
+
+`load(..., trusted=False)` (the default) uses a **restricted evaluator** built on an AST
+allowlist. It allows the everyday building blocks of a guard or expression:
+
+- comparisons (`==`, `!=`, `<`, `>=`, …) and boolean algebra (`and`, `or`, `not`);
+- arithmetic, indexing (`items[0]`), and list/tuple/set/dict literals;
+- reading attributes, **including property getters** (`order.is_ready`);
+- the `In(state_id)` predicate for testing the active configuration.
+
+It refuses anything that could escape the sandbox:
+
+- function and method calls (the only exception is `In(...)`);
+- builtins (`len`, `open`, `__import__`, …), lambdas and comprehensions;
+- dunder or private attribute access (`x.__class__`, `x._secret`).
+
+A rejected expression fails **at load time** with `InvalidDefinition`, not later at runtime:
+
+```py
+>>> from statemachine.io import load
+>>> from statemachine.exceptions import InvalidDefinition
+
+>>> doc = """
+... states:
+...   s:
+...     initial: true
+...     transitions:
+...       - {event: go, target: s, cond: "escape_to_shell()"}
+... """
+>>> try:
+...     load(doc, format="yaml")
+... except InvalidDefinition:
+...     print("rejected")
+rejected
+
+```
+
+What the allowlist refuses is **call syntax** (`name()`, `obj.method()`), so an attacker's
+expression cannot reach builtins, the one exception being `In(...)`:
+
+- `cond: "order.is_ready"` — allowed (a plain attribute read, which runs the property getter).
+- `cond: "order.is_ready()"` — rejected (call syntax).
+
+Guards (`cond`/`unless`) have one extra affordance, matching class-defined guards: a bare name
+that resolves to a model **method** is invoked by name, like a callback reference, receiving
+the event's keyword arguments. That is still safe, it runs the integrator's own method named
+in the document, not arbitrary code, so guard logic can be a property, an attribute or a
+method without `trusted=True`.
+
+## What `trusted=True` unlocks
+
+`load(..., trusted=True)` evaluates expressions as full Python (`eval`) and enables the
+`script` action (`exec`). Concretely, it adds exactly what the restricted mode withholds:
+
+- method calls and builtins inside guards and expressions (`len(cart)`, `order.is_ready()`,
+  `_event.data.get("x")`);
+- the `script` action, a block of Python statements that reads and writes the model.
+
+Everything else, the `assign`, `raise`, `send`, `log`, `foreach`, `cancel` and `if` actions,
+already works in both modes; `script` is the only action gated behind `trusted`. Errors in
+trusted expressions surface at runtime (as `error.execution`) rather than at load time.
+
+Use `trusted=True` **only** for documents you fully control.
+
+## Write targets are confined to public attributes
+
+Actions that write to the datamodel take the destination *name* from the document:
+`<assign location>`, `<foreach item>`/`index`, `<data id>` and `<send>`/`<invoke>` `idlocation`.
+In every case the name must be a plain, public model attribute. Private (`_`-prefixed), dunder
+(`__class__`, `__init__`, …) and engine-protected names are rejected, and for a dotted
+`<assign location="a.b.c">` the check applies to **every** segment, not just the last one. This
+stops a document from traversing `__class__` to corrupt the shared model class (which would
+break every machine in the process) or from overwriting engine internals. As a second layer,
+a live engine-capability instance (the machine, the interpreter, a core `State`/`Transition`/
+`Event`, or the `_event`/`_ioprocessors` system-variable views) is also rejected as a traversed
+hop or write target, so even a value that somehow referenced one cannot be used to mutate state
+shared across machines. A rejected write surfaces as `error.execution`, the same as any other
+action failure.
+
+## Arithmetic is magnitude-bounded
+
+The restricted evaluator allows arithmetic, but `**` and `*` are capped so that a tiny
+expression cannot exhaust CPU or memory: an exponentiation whose result would be enormous
+(`9 ** 9 ** 9`, a ~370-million-digit number) and a sequence replication that would allocate a
+huge object (`[0] * 20000000`) are both rejected before they run. Ordinary scalar arithmetic
+(`x * 2`, `x ** 2`) is unaffected. Under `trusted=True` the full Python evaluator is used, so
+these caps do not apply.
+
+## External resource references (`src`)
+
+`<data src="file:…">` and `<invoke src="…">` (and `srcexpr`) read a **local file** named by the
+document. Because a malicious document could point them at any file on the host and then
+exfiltrate the contents (via `<log>`, `<send>` or the datamodel), they are gated exactly like
+`<script>`: rejected by default, allowed only with `trusted=True`.
+
+```py
+>>> from statemachine.io import load
+>>> from statemachine.exceptions import InvalidDefinition
+
+>>> doc = """
+... <scxml xmlns="http://www.w3.org/2005/07/scxml" initial="s">
+...   <datamodel><data id="x" src="file:///etc/passwd"/></datamodel>
+...   <state id="s"/>
+... </scxml>
+... """
+>>> try:
+...     load(doc, format="scxml")
+... except InvalidDefinition:
+...     print("rejected")
+rejected
+
+```
+
+The file is never opened in the default mode: the rejection happens at load time, before any
+`open()`. This also applies to a relative `src` (e.g. `src: child.yaml`), so loading a document
+that includes a child from disk requires `trusted=True`.
+
+## XML hardening
+
+The SCXML parser refuses any `<!DOCTYPE>`/DTD. Internal entity definitions (which a DTD enables)
+are the basis of *entity-expansion* denial-of-service bombs (billion laughs / quadratic blowup),
+so they are rejected at parse time, independent of `trusted`:
+
+```py
+>>> bomb = """<?xml version="1.0"?>
+... <!DOCTYPE scxml [<!ENTITY a "AAAAAAAAAA"><!ENTITY b "&a;&a;&a;&a;&a;">]>
+... <scxml xmlns="http://www.w3.org/2005/07/scxml" initial="s"><state id="s"/></scxml>
+... """
+>>> try:
+...     load(bomb, format="scxml")
+... except InvalidDefinition:
+...     print("rejected")
+rejected
+
+```
+
+## Availability is not sandboxed
+
+The guarantees above protect **confidentiality and integrity** of the host. They do **not** bound
+the **resources** a running machine consumes. Even a document with no unsafe element can, once
+started, exhaust CPU, memory or threads:
+
+- **Eventless loops**: two states with eventless transitions between them (`a → b → a`) never
+  reach a stable configuration, so a macrostep never completes.
+- **`<foreach>` over a huge collection**: iterating a very large iterable.
+- **Recursive `<invoke>`**: a document that invokes itself (directly or in a cycle) spawns
+  unbounded child machines and threads.
+- **Delayed-event accumulation**: scheduling many `<send delay="…">` events.
+
+The state machine engine follows the SCXML run-to-completion model and intentionally does not
+impose iteration, size or recursion limits. **If you load and run documents from untrusted
+sources, run them under your own resource controls**: an execution timeout, and OS/process
+limits on CPU, memory and threads (e.g. a subprocess with `resource` rlimits, a container, or a
+watchdog that stops the machine).
+
+## Background
+
+This safe-by-default behaviour comes from the security advisory
+[GHSA-v4jc-pm6r-3vj8](https://github.com/fgmacedo/python-statemachine/security/advisories/GHSA-v4jc-pm6r-3vj8)
+(CVE-2026-47103).
+Before it, SCXML datamodel expressions were evaluated with `eval`, which let a malicious
+document run arbitrary code on load. The restricted evaluator removes that by default across
+every format (SCXML, JSON and YAML).
+
+A set of follow-up advisories hardened the restricted mode further and prompted the
+confidentiality/integrity vs availability framing above:
+
+- [GHSA-fj3w-533r-fvf6](https://github.com/fgmacedo/python-statemachine/security/advisories/GHSA-fj3w-533r-fvf6)
+  — `<data src="file:…">` and `<invoke src="…">` read local files during loading, regardless of
+  `trusted`. Loading now rejects external `src` references unless `trusted=True`, and refuses
+  `<!DOCTYPE>`/DTD to block XML entity-expansion bombs.
+- [GHSA-v3qq-3xvg-m77g](https://github.com/fgmacedo/python-statemachine/security/advisories/GHSA-v3qq-3xvg-m77g)
+  / [GHSA-4857-ggqc-p3jc](https://github.com/fgmacedo/python-statemachine/security/advisories/GHSA-4857-ggqc-p3jc)
+  — a document could write to a dunder/private/protected attribute (notably traversing
+  `__class__`) and corrupt the shared model class process-wide. Write targets are now confined
+  to public model attributes on every path segment.
+- [GHSA-r8gj-366q-cgvj](https://github.com/fgmacedo/python-statemachine/security/advisories/GHSA-r8gj-366q-cgvj)
+  — `**`/`*` in the restricted evaluator had no magnitude bound, so a tiny expression could
+  exhaust CPU or memory. They are now magnitude-capped.
+
+These were released together in 3.2.1.