chore: merge develop into macedo/scxml

Resolve conflicts from Python 3.14 support merge (PR #552):
- CI matrix: keep scxml's min Python 3.9, add 3.14
- pyproject.toml: add 3.14 classifier, update ruff ignore list
- statemachine.py: use `is not None` check, keep history_values and
  id-keyed listeners from scxml branch
- docs/guards.md: keep expanded declaration order docs from develop
- Fix trailing whitespace and unused imports from scxml branch

Author: fgmacedo

.github/workflows/python-package.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v4
@@ -37,7 +37,7 @@ jobs:
       #              run ruff
       #----------------------------------------------
     - name: Linter with ruff
-      if: matrix.python-version == 3.13
+      if: matrix.python-version == 3.14
       run: |
         uv run ruff check .
         uv run ruff format --check .
@@ -53,7 +53,7 @@ jobs:
       #----------------------------------------------
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v4
-      if: matrix.python-version == 3.13
+      if: matrix.python-version == 3.14
       with:
         token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos
         directory: .

.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.13'
+          python-version: '3.14'
 
       - name: Setup Graphviz
         uses: ts-graphviz/setup-graphviz@v2

.readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "3.12"
+    python: "3.14"
   apt_packages:
     - graphviz
   jobs:

AGENTS.md

@@ -0,0 +1,114 @@
+# python-statemachine
+
+Python Finite State Machines made easy.
+
+## Project overview
+
+A library for building finite state machines in Python, with support for sync and async engines,
+Django integration, diagram generation, and a flexible callback/listener system.
+
+- **Source code:** `statemachine/`
+- **Tests:** `tests/`
+- **Documentation:** `docs/` (Sphinx + MyST Markdown, hosted on ReadTheDocs)
+
+## Architecture
+
+- `statemachine.py` — Core `StateMachine` class
+- `factory.py` — `StateMachineMetaclass` handles class construction, state/transition validation
+- `state.py` / `event.py` — Descriptor-based `State` and `Event` definitions
+- `transition.py` / `transition_list.py` — Transition logic and composition (`|` operator)
+- `callbacks.py` — Priority-based callback registry (`CallbackPriority`, `CallbackGroup`)
+- `dispatcher.py` — Listener/observer pattern, `callable_method` wraps callables with signature adaptation
+- `signature.py` — `SignatureAdapter` for dependency injection into callbacks
+- `engines/sync.py`, `engines/async_.py` — Sync and async run-to-completion engines
+- `registry.py` — Global state machine registry (used by `MachineMixin`)
+- `mixins.py` — `MachineMixin` for domain model integration (e.g., Django models)
+- `spec_parser.py` — Boolean expression parser for condition guards
+- `contrib/diagram.py` — Diagram generation via pydot/Graphviz
+
+## Environment setup
+
+```bash
+uv sync --all-extras --dev
+pre-commit install
+```
+
+## Running tests
+
+Always use `uv` to run commands:
+
+```bash
+# Run all tests (parallel)
+uv run pytest -n auto
+
+# Run a specific test file
+uv run pytest tests/test_signature.py
+
+# Run a specific test
+uv run pytest tests/test_signature.py::TestSignatureAdapter::test_wrap_fn_single_positional_parameter
+
+# Skip slow tests
+uv run pytest -m "not slow"
+```
+
+Tests include doctests from both source modules (`--doctest-modules`) and markdown docs
+(`--doctest-glob=*.md`). Coverage is enabled by default.
+
+## Linting and formatting
+
+```bash
+# Lint
+uv run ruff check .
+
+# Auto-fix lint issues
+uv run ruff check --fix .
+
+# Format
+uv run ruff format .
+
+# Type check
+uv run mypy statemachine/ tests/
+```
+
+## Code style
+
+- **Formatter/Linter:** ruff (line length 99, target Python 3.14)
+- **Rules:** pycodestyle, pyflakes, isort, pyupgrade, flake8-comprehensions, flake8-bugbear, flake8-pytest-style
+- **Imports:** single-line, sorted by isort
+- **Docstrings:** Google convention
+- **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
+
+## Design principles
+
+- **Decouple infrastructure from domain:** Modules like `signature.py` and `dispatcher.py` are
+  general-purpose (signature adaptation, listener/observer pattern) and intentionally not coupled
+  to the state machine domain. Prefer this separation even for modules that are only used
+  internally — it keeps responsibilities clear and the code easier to reason about.
+- **Favor small, focused modules:** When adding new functionality, consider whether it can live in
+  its own module with a well-defined boundary, rather than growing an existing one.
+
+## Building documentation
+
+```bash
+# Build HTML docs
+uv run sphinx-build docs docs/_build/html
+
+# Live reload for development
+uv run sphinx-autobuild docs docs/_build/html --re-ignore "auto_examples/.*"
+```
+
+## Git workflow
+
+- Main branch: `develop`
+- PRs target `develop`
+- Releases are tagged as `v*.*.*`
+- Signed commits preferred (`git commit -s`)
+- Use [Conventional Commits](https://www.conventionalcommits.org/) messages
+  (e.g., `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, `perf:`)
+
+## Security
+
+- Do not commit secrets, credentials, or `.env` files
+- Validate at system boundaries; trust internal code

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

conftest.py

@@ -6,9 +6,10 @@
 
 @pytest.fixture(autouse=True, scope="session")
 def add_doctest_context(doctest_namespace):  # noqa: PT004
+    from statemachine.utils import run_async_from_sync
+
     from statemachine import State
     from statemachine import StateMachine
-    from statemachine.utils import run_async_from_sync
 
     class ContribAsyncio:
         """

docs/actions.md

@@ -14,7 +14,7 @@ There are several action callbacks that you can define to interact with a
 StateMachine in execution.
 
 There are callbacks that you can specify that are generic and will be called
-when something changes and are not bounded to a specific state or event:
+when something changes, and are not bound to a specific state or event:
 
 - `prepare_event()`
 
@@ -28,7 +28,7 @@ when something changes and are not bounded to a specific state or event:
 
 - `after_transition()`
 
-The following example can get you an overview of the "generic" callbacks available:
+The following example offers an overview of the "generic" callbacks available:
 
 ```py
 >>> from statemachine import StateMachine, State

docs/guards.md

@@ -22,7 +22,37 @@ A conditional transition occurs only if specific conditions or criteria are met.
 
 When a transition is conditional, it includes a condition (also known as a _guard_) that must be satisfied for the transition to take place. If the condition is not met, the transition does not occur, and the state machine remains in its current state or follows an alternative path.
 
-This feature allows for multiple transitions on the same {ref}`event`, with each {ref}`transition` checked in the order they are declared. A condition acts like a predicate (a function that evaluates to true/false) and is checked when a {ref}`statemachine` handles an {ref}`event` with a transition from the current state bound to this event. The first transition that meets the conditions (if any) is executed. If none of the transitions meet the conditions, the state machine either raises an exception or does nothing (see the `allow_event_without_transition` class attribute of {ref}`StateMachine`).
+This feature allows for multiple transitions on the same {ref}`event`, with each {ref}`transition` checked in **declaration order** — that is, the order in which the transitions themselves were created using `state.to()`. A condition acts like a predicate (a function that evaluates to true/false) and is checked when a {ref}`statemachine` handles an {ref}`event` with a transition from the current state bound to this event. The first transition that meets the conditions (if any) is executed. If none of the transitions meet the conditions, the state machine either raises an exception or does nothing (see the `allow_event_without_transition` parameter of {ref}`StateMachine`).
+
+````{important}
+**Evaluation order is based on declaration order, not composition order.**
+
+When using conditional transitions, the order of evaluation is determined by **when each transition was created** (the order of `state.to()` calls), **not** by the order they appear when combined with the `|` operator.
+
+For example:
+
+```python
+# These are evaluated in DECLARATION ORDER (when state.to() was called):
+created_first = state_a.to(state_x)   # Created FIRST → Checked FIRST
+created_second = state_a.to(state_y)  # Created SECOND → Checked SECOND
+created_third = state_a.to(state_z)   # Created THIRD → Checked THIRD
+
+# The | operator does NOT change evaluation order:
+my_event = created_third | created_second | created_first
+# Evaluation order is still: created_first → created_second → created_third
+```
+
+To control the evaluation order, declare transitions in the desired order:
+
+```python
+# Declare in the order you want them checked:
+first = state_a.to(state_b, cond="check1")   # Checked FIRST
+second = state_a.to(state_c, cond="check2")  # Checked SECOND
+third = state_a.to(state_d, cond="check3")   # Checked THIRD
+
+my_event = first | second | third  # Order matches declaration
+```
+````
 
 When {ref}`transitions` have guards, it is possible to define two or more transitions for the same {ref}`event` from the same {ref}`state`. When the {ref}`event` occurs, the guarded transitions are checked one by one, and the first transition whose guard is true will be executed, while the others will be ignored.
 

docs/transitions.md

@@ -166,7 +166,7 @@ the event name is used to describe the transition.
 ## Events
 
 An event is an external signal that something has happened.
-They are send to a state machine and allow the state machine to react.
+They are sent to a state machine and allow the state machine to react.
 
 An event starts a {ref}`transition`, which can be thought of as a "cause" that
 initiates a change in the state of the system.
@@ -176,7 +176,7 @@ In `python-statemachine`, an event is specified as an attribute of the state mac
 
 ### Declaring events
 
-The simplest way to declare an {ref}`event` is by assiging a transitions list to a name at the
+The simplest way to declare an {ref}`event` is by assigning a transitions list to a name at the
 State machine class level. The name will be converted to an {ref}`Event`:
 
 ```py
@@ -196,7 +196,7 @@ True
 ```
 
 ```{versionadded} 2.4.0
-You can also explict declare an {ref}`Event` instance, this helps IDEs to know that the event is callable and also with transtation strings.
+You can also explictly declare an {ref}`Event` instance, this helps IDEs to know that the event is callable, and also with translation strings.
 ```
 
 To declare an explicit event you must also import the {ref}`Event`:

pyproject.toml

@@ -17,6 +17,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3.9",
     "Topic :: Home Automation",
     "Topic :: Software Development :: Libraries",
@@ -35,7 +36,8 @@ dev = [
     "pre-commit",
     "mypy",
     "pytest",
-    "pytest-cov",
+    "pytest-cov >=6.0.0; python_version >='3.9'",
+    "pytest-cov; python_version <'3.9'",
     "pytest-sugar >=1.0.0",
     "pytest-mock >=3.10.0",
     "pytest-benchmark >=4.0.0",
@@ -118,7 +120,7 @@ directory = "tmp/htmlcov"
 show_contexts = true
 
 [tool.mypy]
-python_version = "3.13"
+python_version = "3.14"
 warn_return_any = true
 warn_unused_configs = true
 disable_error_code = "annotation-unchecked"
@@ -132,7 +134,7 @@ ignore_missing_imports = true
 src = ["statemachine"]
 
 line-length = 99
-target-version = "py313"
+target-version = "py314"
 
 # Exclude a variety of commonly ignored directories.
 exclude = [
@@ -171,8 +173,8 @@ select = [
 ignore = [
     "UP006", # `use-pep585-annotation` Requires Python3.9+
     "UP035", # `use-pep585-annotation` Requires Python3.9+
-    "UP037", # `use-pep586-annotation` Requires Python3.9+
-    "UP038", # `use-pep585-annotation` Requires Python3.9+
+    "UP037", # `remove-quotes-from-type-annotation` Not safe without `from __future__ import annotations`
+    "UP042", # `use-str-enum` Requires Python3.11+
 ]
 
 # Allow unused variables when underscore-prefixed.