Merge branch 'release/2.6.0'

Author: fgmacedo

.github/workflows/python-package.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v4
@@ -33,15 +33,11 @@ jobs:
         cache-suffix: "python${{ matrix.python-version }}"
     - name: Install the project
       run: uv sync --all-extras --dev
-    - name: Install old pydot for 3.7 only
-      if: matrix.python-version == 3.7
-      run: |
-        uv pip install pydot==2.0.0
       #----------------------------------------------
       #              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 .
@@ -57,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

.pre-commit-config.yaml

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

.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.9)
+- **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

README.md

@@ -99,6 +99,8 @@ You can now create an instance:
 This state machine can be represented graphically as follows:
 
 ```py
+>>> # This example will only run on automated tests if dot is present
+>>> getfixture("requires_dot_installed")
 >>> img_path = "docs/images/readme_trafficlightmachine.png"
 >>> sm._graph().write_png(img_path)
 

conftest.py

@@ -1,13 +1,15 @@
+import shutil
 import sys
 
 import pytest
 
 
 @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:
         """
@@ -31,3 +33,14 @@ def pytest_ignore_collect(collection_path, path, config):
 
     if "django_project" in str(path):
         return True
+
+
+@pytest.fixture(scope="session")
+def has_dot_installed():
+    return bool(shutil.which("dot"))
+
+
+@pytest.fixture()
+def requires_dot_installed(request, has_dot_installed):
+    if not has_dot_installed:
+        pytest.skip(f"Test {request.node.nodeid} requires 'dot' that is not installed.")

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:
 
 - `before_transition()`
 
@@ -26,7 +26,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/authors.md

@@ -10,6 +10,7 @@
 * [Rafael Rêgo](mailto:crafards@gmail.com)
 * [Raphael Schrader](mailto:raphael@schradercloud.de)
 * [João S. O. Bueno](mailto:gwidion@gmail.com)
+* [Rodrigo Nogueira](mailto:rodrigo.b.nogueira@gmail.com)
 
 
 ## Scaffolding