python-statemachine 3.1.2__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.1.2 → python_statemachine-3.2.1}/.github/workflows/python-package.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v5

{python_statemachine-3.1.2 → python_statemachine-3.2.1}/.gitignore

@@ -85,3 +85,8 @@ tmp/
 
 # Local specs
 specs/
+
+# Environment files (secrets)
+.env
+.env.*
+!.env.example

{python_statemachine-3.1.2 → python_statemachine-3.2.1}/.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
         exclude: docs/auto_examples
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.15.13
+  rev: v0.15.17
   hooks:
     # Run the linter.
     - id: ruff

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

@@ -218,11 +218,19 @@ uv run mypy statemachine/ tests/
 
 ## Code style
 
-- **Formatter/Linter:** ruff (line length 99, target Python 3.9)
+- **Formatter/Linter:** ruff (line length 99, target Python 3.10)
 - **Rules:** pycodestyle, pyflakes, isort, pyupgrade, flake8-comprehensions, flake8-bugbear, flake8-pytest-style
 - **Imports:** single-line, sorted by isort. **Always prefer top-level imports** — only use
   lazy (in-function) imports when strictly necessary to break circular dependencies
-- **Docstrings:** Google convention
+- **Docstrings:** Google convention. Document only what isn't obvious from the
+  name/type (hidden conventions, non-obvious semantics), not trivial fields.
+- **Attribute docs:** use an attribute *docstring* (a string literal on the line
+  **below** the attribute), not an inline `#` comment, so Sphinx autodoc captures it.
+  Reserve `#` for explaining logic. Example:
+  ```python
+  unless: "str | None" = None
+  """Negated guard expression; the transition is allowed only if it is falsy."""
+  ```
 - **Naming:** PascalCase for classes, snake_case for functions/methods, UPPER_SNAKE_CASE for constants
 - **Type hints:** used throughout; `TYPE_CHECKING` for circular imports
 - Pre-commit hooks enforce ruff + mypy + pytest
@@ -268,6 +276,24 @@ All code examples in `docs/*.md` **must** be testable doctests (using ```` ```py
 `--doctest-glob=*.md`. If an example cannot be expressed as a doctest (e.g., it requires
 real concurrency), write it as a unit test in `tests/` and reference it from the docs instead.
 
+### Declarative IO: keep the JSON Schema and the parser in sync
+
+The native JSON/YAML format has three artifacts that must agree: the parser
+(`statemachine/io/native.py`), the runtime, and the published JSON Schema
+(`statemachine/io/schemas/statechart.schema.json`). They drift apart silently unless
+enforced, so when you add or change native vocabulary:
+
+- Update the **schema** alongside the parser/runtime change, never after.
+- The parser is the source of truth for accepted keys: `_ACTION_KEYS` and the
+  `_DOCUMENT_KEYS`/`_STATE_KEYS`/`_TRANSITION_KEYS`/`_INVOKE_KEYS` frozensets. The parser
+  **rejects unknown keys** using them, and `tests/io/test_validation.py` asserts each set
+  equals the matching schema node's properties, so a change on one side without the other
+  fails CI.
+- **Every native example is schema-validated.** Test fixtures load with `validate=True` (and
+  a corpus test validates every `.yaml`/`.json` under `tests/io/`); docs examples pass
+  `validate=True` too. A feature exercised by an example but missing from the schema breaks a
+  test.
+
 ## Git workflow
 
 - Main branch: `develop`
@@ -276,6 +302,10 @@ real concurrency), write it as a unit test in `tests/` and reference it from the
 - 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.1.2 → python_statemachine-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-statemachine
-Version: 3.1.2
+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>
@@ -13,7 +13,6 @@ Classifier: Framework :: Django
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -21,9 +20,16 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Home Automation
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Provides-Extra: diagrams
 Requires-Dist: pydot>=4.0.1; extra == 'diagrams'
+Provides-Extra: io
+Requires-Dist: jsonschema>=4.18; extra == 'io'
+Requires-Dist: pyyaml>=6.0; extra == 'io'
+Provides-Extra: validation
+Requires-Dist: jsonschema>=4.18; extra == 'validation'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
 Description-Content-Type: text/markdown
 
 # Python StateMachine
@@ -400,6 +406,13 @@ To generate diagrams, install with the `diagrams` extra (requires
 pip install python-statemachine[diagrams]
 ```
 
+To load statecharts from declarative documents, install the IO extras
+(`yaml` for YAML, `validation` for `validate=True`, or `io` for both):
+
+```
+pip install python-statemachine[io]
+```
+
 
 ## Contributing
 

{python_statemachine-3.1.2 → python_statemachine-3.2.1}/README.md

@@ -372,6 +372,13 @@ To generate diagrams, install with the `diagrams` extra (requires
 pip install python-statemachine[diagrams]
 ```
 
+To load statecharts from declarative documents, install the IO extras
+(`yaml` for YAML, `validation` for `validate=True`, or `io` for both):
+
+```
+pip install python-statemachine[io]
+```
+
 
 ## Contributing
 

{python_statemachine-3.1.2 → 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.1.2 → python_statemachine-3.2.1}/docs/api.md

@@ -147,6 +147,19 @@ class MyMachine(StateChart):
 .. autofunction:: statemachine.io.create_machine_class_from_definition
 ```
 
+## io.load
+
+```{versionadded} 3.2.0
+```
+
+See [](io/index.md) for the guide.
+
+```{eval-rst}
+.. autofunction:: statemachine.io.load
+
+.. autofunction:: statemachine.io.build_processor
+```
+
 ## timeout
 
 ```{versionadded} 3.0.0

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

@@ -25,6 +25,15 @@ Existing projects should consider migrating when possible, as the
 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 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.
+```
+
 
 ## Comparison table
 
@@ -149,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.1.2 → python_statemachine-3.2.1}/docs/contributing.md

@@ -289,3 +289,32 @@ which will:
 
 Monitor the workflow run at `https://github.com/fgmacedo/python-statemachine/actions` to
 confirm the release was published successfully.
+
+#### 10. Publish the GitHub release
+
+Create the GitHub release from the freshly pushed tag using the release notes file as the
+body. Two adjustments are needed when going from MyST/Sphinx markdown to GitHub-flavored
+markdown:
+
+- Convert MyST directives (`` ```{note} ``, `` ```{warning} ``, etc.) to GitHub's
+  [alert syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
+  (`> [!NOTE]`, `> [!WARNING]`) or to plain blockquotes.
+- Rewrite intra-docs links. Relative links like `[3.1.0 release notes](3.1.0.md)` resolve
+  on ReadTheDocs but not on github.com. Replace them with absolute URLs against the
+  matching tag, e.g.
+  `https://github.com/fgmacedo/python-statemachine/blob/vX.Y.Z/docs/releases/X.Y.Z.md`.
+  Avoid linking to `https://python-statemachine.readthedocs.io/en/vX.Y.Z/` immediately
+  after publishing because the ReadTheDocs build for the new tag may still be in progress.
+
+Then create the release. Use the converted notes as the body:
+
+```shell
+gh release create vX.Y.Z \
+  --title "vX.Y.Z" \
+  --notes-file /tmp/release-X.Y.Z-notes.md \
+  --target main \
+  --verify-tag
+```
+
+Confirm the rendered release at
+`https://github.com/fgmacedo/python-statemachine/releases/tag/vX.Y.Z`.

{python_statemachine-3.1.2 → 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.1.2 → 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.1.2 → 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.1.2 → python_statemachine-3.2.1}/docs/index.md

@@ -58,6 +58,17 @@ weighted_transitions
 timeout
 ```
 
+```{toctree}
+:caption: IO and formats
+:maxdepth: 2
+:hidden:
+
+io/index
+io/formats
+io/json_schema
+io/security
+```
+
 ```{toctree}
 :caption: How to
 :maxdepth: 2

{python_statemachine-3.1.2 → python_statemachine-3.2.1}/docs/installation.md

@@ -21,14 +21,21 @@ Alternatively, if you prefer using [pip](https://pip.pypa.io):
 python3 -m pip install python-statemachine
 ```
 
-For those looking to generate diagrams from your state machines, [pydot](https://github.com/pydot/pydot) and [Graphviz](https://graphviz.org/) are required.
-Conveniently, you can install python-statemachine along with the `pydot` dependency using the extras option.
-For more information, please refer to our documentation.
+## Optional extras
+
+Some features require extra dependencies, available as pip extras:
 
 ```shell
-python3 -m pip install "python-statemachine[diagrams]"
+python3 -m pip install "python-statemachine[diagrams]"    # pydot, to generate diagrams from your machines
+python3 -m pip install "python-statemachine[yaml]"        # PyYAML, to load YAML statechart documents
+python3 -m pip install "python-statemachine[validation]"  # jsonschema, to validate documents (validate=True)
+python3 -m pip install "python-statemachine[io]"          # PyYAML + jsonschema, the full JSON/YAML IO stack
 ```
 
+Diagram generation also requires the [Graphviz](https://graphviz.org/) system package (see
+[](diagram.md)). The `[yaml]`, `[validation]` and `[io]` extras back the declarative loaders
+documented in [](io/index.md); loading JSON needs no extra, as it uses only the standard library.
+
 
 
 ## From sources