docs: Clarify conditional transition evaluation order #546
Conversation
Addresses issue fgmacedo#541 by clarifying that conditional transitions are evaluated in declaration order (when state.to() is called), not in the order they appear when combined with the | operator. Changes: - Update description to explicitly mention "declaration order" - Add Important note box with clear examples showing: - How declaration order differs from composition order - Common pitfall where variable names don't match check order - Correct way to control evaluation order This documentation fix helps prevent user confusion about which transition will be checked first when using multiple conditional transitions for the same event. Closes fgmacedo#541
|
Hi @rodrigobnogueira , thanks for the PR, and sorry it took me a while to get to the review 🙏 I noticed the documentation formatting contains an issue. I guess It comes from how the For every PR, we trigger a docs build and the link appers in the automated checks list. You can see the rendered page here. In MyST/Sphinx, fenced code blocks cannot appear unindented inside an admonition. Any nested content (including code blocks) must be indented; otherwise, the parser exits the admonition early and the rendered HTML ends up malformed — which is what we’re seeing in the Read the Docs preview. Suggested fix (something like this): ```{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):
last_checked = state_a.to(state_x) # Created FIRST → Checked FIRST
mid_checked = state_a.to(state_y) # Created SECOND → Checked SECOND
first_checked = state_a.to(state_z) # Created THIRD → Checked THIRD
# The | operator does NOT change evaluation order:
my_event = first_checked | mid_checked | last_checked
# Evaluation order is still: last_checked → mid_checked → first_checked
```
To control the evaluation order, declare transitions in the desired order:
```python
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
```
|
fgmacedo
left a comment
fgmacedo
left a comment
There was a problem hiding this comment.
You can see the PR rendered docs here.
|
|
Thank you @fgmacedo I've changed from ```{important} to ````{important} I've been using python-statemachine for a year and it is great. Let me know if there is something I could help with. All the best |
2 participants
Addresses issue #541 by clarifying that conditional transitions are evaluated in declaration order (when state.to() is called), not in the order they appear when combined with the | operator.
Changes:
This documentation fix helps prevent user confusion about which transition will be checked first when using multiple conditional transitions for the same event.
Closes #541