python-statemachine 2.5.0__tar.gz → 2.6.0__tar.gz

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/.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: .

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/.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

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/.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

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/.readthedocs.yaml

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

python_statemachine-2.6.0/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

python_statemachine-2.6.0/CLAUDE.md

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

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/PKG-INFO

@@ -1,11 +1,12 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: python-statemachine
-Version: 2.5.0
+Version: 2.6.0
 Summary: Python Finite State Machines made easy.
 Project-URL: homepage, https://github.com/fgmacedo/python-statemachine
 Author-email: Fernando Macedo <fgmacedo@gmail.com>
 Maintainer-email: Fernando Macedo <fgmacedo@gmail.com>
 License: MIT License
+License-File: LICENSE
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: AsyncIO
 Classifier: Framework :: Django
@@ -19,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Home Automation
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.7
@@ -127,6 +129,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)
 

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/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)
 

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/conftest.py

@@ -1,3 +1,4 @@
+import shutil
 import sys
 
 import pytest
@@ -5,9 +6,10 @@ 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.")

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/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

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/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

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/docs/diagram.md

@@ -59,9 +59,23 @@ As this one:
 ![OrderControl](images/order_control_machine_initial.png)
 
 
+If you find the resolution of the image lacking, you can
+
+```py
+>>> dot.set_dpi(300)
+
+>>> dot.write_png("docs/images/order_control_machine_initial_300dpi.png")
+
+```
+
+![OrderControl](images/order_control_machine_initial_300dpi.png)
+
+
 The current {ref}`state` is also highlighted:
 
 ``` py
+>>> # This example will only run on automated tests if dot is present
+>>> getfixture("requires_dot_installed")
 
 >>> from statemachine.contrib.diagram import DotGraphMachine
 

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/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` parameter 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.
 
@@ -129,6 +159,79 @@ So, a condition `s1.to(s2, cond=lambda: [])` will evaluate as `False`, as an emp
 **falsy** value.
 ```
 
+### Checking enabled events
+
+The {ref}`StateMachine.allowed_events` property returns events reachable from the current state,
+but it does **not** evaluate `cond`/`unless` guards. To check which events actually have their
+conditions satisfied, use {ref}`StateMachine.enabled_events`.
+
+```{testsetup}
+
+>>> from statemachine import StateMachine, State
+
+```
+
+```py
+>>> class ApprovalMachine(StateMachine):
+...     pending = State(initial=True)
+...     approved = State(final=True)
+...     rejected = State(final=True)
+...
+...     approve = pending.to(approved, cond="is_manager")
+...     reject = pending.to(rejected)
+...
+...     is_manager = False
+
+>>> sm = ApprovalMachine()
+
+>>> [e.id for e in sm.allowed_events]
+['approve', 'reject']
+
+>>> [e.id for e in sm.enabled_events()]
+['reject']
+
+>>> sm.is_manager = True
+
+>>> [e.id for e in sm.enabled_events()]
+['approve', 'reject']
+
+```
+
+`enabled_events` is a method (not a property) because conditions may depend on runtime
+arguments. Any `*args`/`**kwargs` passed to `enabled_events()` are forwarded to the
+condition callbacks, just like when triggering an event:
+
+```py
+>>> class TaskMachine(StateMachine):
+...     idle = State(initial=True)
+...     running = State(final=True)
+...
+...     start = idle.to(running, cond="has_enough_resources")
+...
+...     def has_enough_resources(self, cpu=0):
+...         return cpu >= 4
+
+>>> sm = TaskMachine()
+
+>>> sm.enabled_events()
+[]
+
+>>> [e.id for e in sm.enabled_events(cpu=8)]
+['start']
+
+```
+
+```{tip}
+This is useful for UI scenarios where you want to show or hide buttons based on whether
+an event's conditions are currently satisfied.
+```
+
+```{note}
+An event is considered **enabled** if at least one of its transitions from the current state
+has all conditions satisfied. If a condition raises an exception, the event is treated as
+enabled (permissive behavior).
+```
+
 ## Validators
 
 

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/docs/integrations.md

@@ -69,3 +69,22 @@ class Campaign(models.Model, MachineMixin):
 ```{seealso}
 Learn more about using the [](mixins.md#machinemixin).
 ```
+
+### Data migrations
+
+Django's `apps.get_model()` returns **historical model** classes that are dynamically created
+and don't carry user-defined class attributes like `state_machine_name`. Since version 2.6.0,
+`MachineMixin` detects these historical models and gracefully skips state machine
+initialization, so data migrations that use `apps.get_model()` work without errors.
+
+```{note}
+The state machine instance will **not** be available on historical model objects.
+If your data migration needs to interact with the state machine, set the attributes
+manually on the historical model class:
+
+    def backfill_data(apps, schema_editor):
+        MyModel = apps.get_model("myapp", "MyModel")
+        MyModel.state_machine_name = "myapp.statemachines.MyStateMachine"
+        for obj in MyModel.objects.all():
+            obj.statemachine  # now available
+```

python_statemachine-2.6.0/docs/releases/2.6.0.md

@@ -0,0 +1,128 @@
+# StateMachine 2.6.0
+
+*February 2026*
+
+## What's new in 2.6.0
+
+This release adds the {ref}`StateMachine.enabled_events` method, Python 3.14 support,
+a significant performance improvement for callback dispatch, and several bugfixes
+for async condition expressions, type checker compatibility, and Django integration.
+
+### Python compatibility in 2.6.0
+
+StateMachine 2.6.0 supports Python 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14.
+
+### Checking enabled events
+
+A new {ref}`StateMachine.enabled_events` method lets you query which events have their
+`cond`/`unless` guards currently satisfied, going beyond {ref}`StateMachine.allowed_events`
+which only checks reachability from the current state.
+
+This is particularly useful for **UI scenarios** where you want to enable or disable buttons
+based on whether an event's conditions are met at runtime.
+
+```{testsetup}
+
+>>> from statemachine import StateMachine, State
+
+```
+
+```py
+>>> class ApprovalMachine(StateMachine):
+...     pending = State(initial=True)
+...     approved = State(final=True)
+...     rejected = State(final=True)
+...
+...     approve = pending.to(approved, cond="is_manager")
+...     reject = pending.to(rejected)
+...
+...     is_manager = False
+
+>>> sm = ApprovalMachine()
+
+>>> [e.id for e in sm.allowed_events]
+['approve', 'reject']
+
+>>> [e.id for e in sm.enabled_events()]
+['reject']
+
+>>> sm.is_manager = True
+
+>>> [e.id for e in sm.enabled_events()]
+['approve', 'reject']
+
+```
+
+Since conditions may depend on runtime arguments, any `*args`/`**kwargs` passed to
+`enabled_events()` are forwarded to the condition callbacks:
+
+```py
+>>> class TaskMachine(StateMachine):
+...     idle = State(initial=True)
+...     running = State(final=True)
+...
+...     start = idle.to(running, cond="has_enough_resources")
+...
+...     def has_enough_resources(self, cpu=0):
+...         return cpu >= 4
+
+>>> sm = TaskMachine()
+
+>>> sm.enabled_events()
+[]
+
+>>> [e.id for e in sm.enabled_events(cpu=8)]
+['start']
+
+```
+
+```{seealso}
+See {ref}`Checking enabled events` in the Guards documentation for more details.
+```
+
+### Performance: cached signature binding
+
+Callback dispatch is now significantly faster thanks to cached signature binding in
+`SignatureAdapter`. The first call to a callback computes the argument binding and
+caches a fast-path template; subsequent calls with the same argument shape skip the
+full binding logic.
+
+This results in approximately **60% faster** `bind_expected()` calls and
+around **30% end-to-end improvement** on hot transition paths.
+
+See [#548](https://github.com/fgmacedo/python-statemachine/issues/548) for benchmarks.
+
+
+## Bugfixes in 2.6.0
+
+- Fixes [#531](https://github.com/fgmacedo/python-statemachine/issues/531) domain model
+  with falsy `__bool__` was being replaced by the default `Model()`.
+- Fixes [#535](https://github.com/fgmacedo/python-statemachine/issues/535) async predicates
+  in condition expressions (`not`, `and`, `or`) were not being awaited, causing guards to
+  silently return incorrect results.
+- Fixes [#548](https://github.com/fgmacedo/python-statemachine/issues/548)
+  `VAR_POSITIONAL` and kwargs precedence bugs in the signature binding cache introduced
+  by the performance optimization.
+- Fixes [#511](https://github.com/fgmacedo/python-statemachine/issues/511) Pyright/Pylance
+  false positive "Argument missing for parameter f" when calling events. Static analyzers
+  could not follow the metaclass transformation from `TransitionList` to `Event`.
+- Fixes [#551](https://github.com/fgmacedo/python-statemachine/issues/551) `MachineMixin`
+  now gracefully skips state machine initialization for Django historical models in data
+  migrations, instead of raising `ValueError`.
+- Fixes [#526](https://github.com/fgmacedo/python-statemachine/issues/526) sanitize project
+  path on Windows for documentation builds.
+
+
+## Misc in 2.6.0
+
+- Added Python 3.14 support [#552](https://github.com/fgmacedo/python-statemachine/pull/552).
+- Upgraded dev dependencies: ruff to 0.15.0, mypy to 1.14.1
+  [#552](https://github.com/fgmacedo/python-statemachine/pull/552).
+- Clarified conditional transition evaluation order in documentation
+  [#546](https://github.com/fgmacedo/python-statemachine/pull/546).
+- Added pydot DPI resolution settings to diagram documentation
+  [#514](https://github.com/fgmacedo/python-statemachine/pull/514).
+- Fixed miscellaneous typos in documentation
+  [#522](https://github.com/fgmacedo/python-statemachine/pull/522).
+- Removed Python 3.7 from CI build matrix
+  [ef351d5](https://github.com/fgmacedo/python-statemachine/commit/ef351d5).

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/docs/releases/index.md

@@ -15,6 +15,7 @@ Below are release notes through StateMachine and its patch releases.
 ```{toctree}
 :maxdepth: 2
 
+2.6.0
 2.5.0
 2.4.0
 2.3.6

{python_statemachine-2.5.0 → python_statemachine-2.6.0}/docs/transitions.md

@@ -131,6 +131,9 @@ Example:
 Usage:
 
 ```py
+>>> # This example will only run on automated tests if dot is present
+>>> getfixture("requires_dot_installed")
+
 >>> sm = TestStateMachine()
 
 >>> sm._graph().write_png("docs/images/test_state_machine_internal.png")
@@ -163,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.
@@ -173,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
@@ -193,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`: