Merge branch 'release/3.2.0'

Author: fgmacedo

.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

.gitignore

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

.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

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`

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
 

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

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 whitelist 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
 

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`.

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

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