- name: Install old pydot for 3.7 only

if: matrix.python-version == 3.7

run: |

- **Contribute code**: If you would like to contribute code, please submit a pull

- **Report bugs**: If you find any bugs, please report them by opening an issue

- **Suggest features**: If you have an idea for a new feature, of feels something being harder than it should be,

please let us know by opening an issue on our GitHub issue tracker.

- **Documentation**: Help improve documentation by submitting pull requests.

- **Promote the project**: Help spread the word by sharing on social media,

For each {ref}`events`, you can register `before`, `on`, and `after` callbacks.

The {ref}`StateMachine` fully supports asynchronous code. You can write async {ref}`actions`, {ref}`guards`, and {ref}`events` triggers, while maintaining the same external API for both synchronous and asynchronous codebases.

This is achieved through a new concept called **engine**, an internal strategy pattern abstraction that manages transitions and callbacks.

: A list of condition expressions, acting like predicates. A transition is only allowed to occur if

* Single condition expression: `cond="condition"` / `cond="<condition expression>"`

* Multiple condition expressions: `cond=["condition1", "condition2"]`

* Single condition: `unless="condition"` / `unless="<condition expression>"`

This library supports a mini-language for boolean expressions in conditions, allowing the definition of guards that control transitions based on specified criteria. It includes basic [boolean algebra](https://en.wikipedia.org/wiki/Boolean_algebra) operators, parentheses for controlling precedence, and **names** that refer to attributes on the state machine, its associated model, or registered {ref}`Listeners`.

The mini-language is based on Python's built-in language and the [`ast`](https://docs.python.org/3/library/ast.html) parser, so there are no surprises if you’re familiar with Python. Below is a formal specification to clarify the structure.

1. **Names**:

- Names refer to attributes on the state machine instance, its model or listeners, used directly in expressions to evaluate conditions.

- Names must consist of alphanumeric characters and underscores (`_`) and cannot begin with a digit (e.g., `is_active`, `count`, `has_permission`).

- Any property name used in the expression must exist as an attribute on the state machine, model instance, or listeners, otherwise, an `InvalidDefinition` error is raised.

- Names can be pointed to `properties`, `attributes` or `methods`. If pointed to `attributes`, the library will create a

wrapper get method so each time the expression is evaluated the current value will be retrieved.

2. **Boolean operators and precedence**:

- The following Boolean operators are supported, listed from highest to lowest precedence:

1. `not` / `!` — Logical negation

2. `and` / `^` — Logical conjunction

3. `or` / `v` — Logical disjunction

- These operators are case-sensitive (e.g., `NOT` and `Not` are not equivalent to `not` and will raise syntax errors).

- Both formats can be used interchangeably, so `!sauron_alive` and `not sauron_alive` are equivalent.

3. **Parentheses for precedence**:

- When operators with the same precedence appear in the expression, evaluation proceeds from left to right, unless parentheses specify a different order.

- Parentheses `(` and `)` are supported to control the order of evaluation in expressions.

- Expressions within parentheses are evaluated first, allowing explicit precedence control (e.g., `(is_admin or is_moderator) and has_permission`).

Examples of valid boolean expressions include:

- `is_logged_in and has_permission`

- `not is_active or is_admin`

- `!(is_guest ^ has_access)`

- `(is_admin or is_moderator) and !is_banned`

- `has_account and (verified or trusted)`

- `frodo_has_ring and gandalf_present or !sauron_alive`

Being used on a transition definition:

start.to(end, cond="frodo_has_ring and gandalf_present or !sauron_alive")

The mini-language is formally specified as follows:

To install using [uv](https://docs.astral.sh/uv):

uv add python-statemachine

To install using [poetry](https://python-poetry.org/):

*November 5, 2024*

This release introduces powerful new features for the `StateMachine` library: {ref}`Condition expressions` and explicit definition of {ref}`Events`. These updates make it easier to define complex transition conditions and enhance performance, especially in workflows with nested or recursive event structures.

StateMachine 2.4.0 supports Python 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, and 3.13.

This release introduces support for conditionals with Boolean algebra. You can now use expressions like `or`, `and`, and `not` directly within transition conditions, simplifying the definition of complex state transitions. This allows for more flexible and readable condition setups in your state machine configurations.

Example (with a spoiler of the next highlight):

>>> from statemachine import StateMachine, State, Event

>>> class AnyConditionSM(StateMachine):

... start = State(initial=True)

... end = State(final=True)

... submit = Event(

... start.to(end, cond="used_money or used_credit"),

... name="finish order",

... )

... used_money: bool = False

... used_credit: bool = False

>>> sm = AnyConditionSM()

>>> sm.submit()

Traceback (most recent call last):

TransitionNotAllowed: Can't finish order when in Start.

>>> sm.used_credit = True

>>> sm.submit()

>>> sm.current_state.id

Now you can explicit declare {ref}`Events` using the {ref}`event` class. This allows custom naming, translations, and also helps your IDE to know that events are callable.

>>> from statemachine import StateMachine, State, Event

>>> class StartMachine(StateMachine):

... created = State(initial=True)

... started = State(final=True)

... start = Event(created.to(started), name="Launch the machine")

>>> [e.id for e in StartMachine.events]

['start']

>>> [e.name for e in StartMachine.events]

['Launch the machine']

>>> StartMachine.start.name

We removed a note from the docs saying to avoid recursion loops. Since the {ref}`StateMachine 2.0.0` release we've turned the RTC model enabled by default, allowing nested events to occour as all events are put on an internal queue before being executed.

- Fixes [#484](https://github.com/fgmacedo/python-statemachine/issues/484) issue where nested events inside loops could leak memory by incorrectly

referencing previous `event_data` when queuing the next event. This fix improves performance and stability in event-heavy workflows.