docs: document callable/lambda guard conditions and add regression tests (#638)

docs/guards.md

@@ -132,6 +132,71 @@ example combining multiple transitions on the same event.
 ```
 
 
+(callable conditions)=
+
+### Callable conditions
+
+Besides strings, `cond` and `unless` also accept callables directly, including
+lambdas, allowing simple guards to be defined inline:
+
+```py
+>>> class Turnstile(StateChart):
+... locked = State(initial=True)
+... unlocked = State(final=True)
+...
+... coin = locked.to(unlocked, cond=lambda machine: machine.credits > 0)
+...
+... credits = 0
+
+>>> sm = Turnstile()
+>>> sm.send("coin")
+>>> "locked" in sm.configuration_values
+True
+
+>>> sm.credits = 1
+>>> sm.send("coin")
+>>> "unlocked" in sm.configuration_values
+True
+
+```
+
+Like any callback, a callable condition receives its arguments via
+{ref}`dependency injection <dependency-injection>`: declare only the
+parameters you need, using the injectable names (`machine`, `event`,
+`source`, `target`, `model`, ...) or the arguments passed when triggering
+the event:
+
+```py
+>>> class Dispatcher(StateChart):
+... idle = State(initial=True)
+... dispatched = State(final=True)
+...
+... dispatch = idle.to(dispatched, cond=lambda priority=0: priority > 5)
+
+>>> sm = Dispatcher()
+>>> sm.send("dispatch", priority=1)
+>>> "idle" in sm.configuration_values
+True
+
+>>> sm.send("dispatch", priority=9)
+>>> "dispatched" in sm.configuration_values
+True
+
+```
+
+```{warning}
+Plain callables, like lambdas and functions defined outside the class body,
+are called **unbound**, so `self` is not injected. A guard declared as
+`cond=lambda self: ...` fails with a `TypeError` when evaluated. Use
+`machine` instead of `self` to receive the state machine instance.
+
+`self` is only available when the callable resolves to a bound method,
+which happens when it is an attribute of the state machine class: either
+referenced by name (`cond="my_condition"`) or defined in the class body
+and passed by reference (`cond=my_condition`).
+```
+
+
 (condition expressions)=
 
 ### Condition expressions

tests/test_callbacks.py

@@ -354,6 +354,102 @@ class ExampleStateMachine(StateChart):
  ExampleStateMachine()
 
 
+class TestIssue638:
+ """Guards passed as plain callables (e.g. lambdas) are resolved unbound.
+
+ Dependency injection works by parameter name, so ``self`` is only injected when
+ the callable is an attribute of the class and gets resolved to a bound method.
+ Plain callables must declare injectable names (e.g. ``machine``) instead.
+
+ See: https://github.com/fgmacedo/python-statemachine/issues/638
+ """
+
+ def test_lambda_cond_with_machine_param(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda machine: machine.can_start)
+
+ def __init__(self, can_start: bool):
+ self.can_start = can_start
+ super().__init__()
+
+ sm = ExampleStateMachine(can_start=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(can_start=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_without_params(self):
+ flags = {"can_start": False}
+
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda: flags["can_start"])
+
+ sm = ExampleStateMachine()
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ flags["can_start"] = True
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_event_kwargs(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda priority=0: priority > 5)
+
+ sm = ExampleStateMachine()
+ sm.send("start", priority=1)
+ assert "created" in sm.configuration_values
+
+ sm.send("start", priority=9)
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_self_param_is_called_unbound(self):
+ class ExampleStateMachine(StateChart):
+ catch_errors_as_events = False
+
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda self: True)
+
+ sm = ExampleStateMachine()
+ with pytest.raises(TypeError, match="missing 1 required positional argument: 'self'"):
+ sm.send("start")
+
+ def test_class_body_function_cond_by_reference_is_bound(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ def can_start(self) -> bool:
+ return self.flag
+
+ start = created.to(started, cond=can_start)
+
+ def __init__(self, flag: bool):
+ self.flag = flag
+ super().__init__()
+
+ sm = ExampleStateMachine(flag=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(flag=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+
 class TestVisitConditionFalse:
  """visit/async_visit skip callbacks whose condition returns False."""
 

docs/guards.md

@@ -132,6 +132,71 @@ example combining multiple transitions on the same event.
 ```
 
 
+(callable conditions)=
+
+### Callable conditions
+
+Besides strings, `cond` and `unless` also accept callables directly, including
+lambdas, allowing simple guards to be defined inline:
+
+```py
+>>> class Turnstile(StateChart):
+... locked = State(initial=True)
+... unlocked = State(final=True)
+...
+... coin = locked.to(unlocked, cond=lambda machine: machine.credits > 0)
+...
+... credits = 0
+
+>>> sm = Turnstile()
+>>> sm.send("coin")
+>>> "locked" in sm.configuration_values
+True
+
+>>> sm.credits = 1
+>>> sm.send("coin")
+>>> "unlocked" in sm.configuration_values
+True
+
+```
+
+Like any callback, a callable condition receives its arguments via
+{ref}`dependency injection <dependency-injection>`: declare only the
+parameters you need, using the injectable names (`machine`, `event`,
+`source`, `target`, `model`, ...) or the arguments passed when triggering
+the event:
+
+```py
+>>> class Dispatcher(StateChart):
+... idle = State(initial=True)
+... dispatched = State(final=True)
+...
+... dispatch = idle.to(dispatched, cond=lambda priority=0: priority > 5)
+
+>>> sm = Dispatcher()
+>>> sm.send("dispatch", priority=1)
+>>> "idle" in sm.configuration_values
+True
+
+>>> sm.send("dispatch", priority=9)
+>>> "dispatched" in sm.configuration_values
+True
+
+```
+
+```{warning}
+Plain callables, like lambdas and functions defined outside the class body,
+are called **unbound**, so `self` is not injected. A guard declared as
+`cond=lambda self: ...` fails with a `TypeError` when evaluated. Use
+`machine` instead of `self` to receive the state machine instance.
+
+`self` is only available when the callable resolves to a bound method,
+which happens when it is an attribute of the state machine class: either
+referenced by name (`cond="my_condition"`) or defined in the class body
+and passed by reference (`cond=my_condition`).
+```
+
+
 (condition expressions)=
 
 ### Condition expressions

tests/test_callbacks.py

@@ -354,6 +354,102 @@ class ExampleStateMachine(StateChart):
  ExampleStateMachine()
 
 
+class TestIssue638:
+ """Guards passed as plain callables (e.g. lambdas) are resolved unbound.
+
+ Dependency injection works by parameter name, so ``self`` is only injected when
+ the callable is an attribute of the class and gets resolved to a bound method.
+ Plain callables must declare injectable names (e.g. ``machine``) instead.
+
+ See: https://github.com/fgmacedo/python-statemachine/issues/638
+ """
+
+ def test_lambda_cond_with_machine_param(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda machine: machine.can_start)
+
+ def __init__(self, can_start: bool):
+ self.can_start = can_start
+ super().__init__()
+
+ sm = ExampleStateMachine(can_start=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(can_start=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_without_params(self):
+ flags = {"can_start": False}
+
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda: flags["can_start"])
+
+ sm = ExampleStateMachine()
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ flags["can_start"] = True
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_event_kwargs(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda priority=0: priority > 5)
+
+ sm = ExampleStateMachine()
+ sm.send("start", priority=1)
+ assert "created" in sm.configuration_values
+
+ sm.send("start", priority=9)
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_self_param_is_called_unbound(self):
+ class ExampleStateMachine(StateChart):
+ catch_errors_as_events = False
+
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda self: True)
+
+ sm = ExampleStateMachine()
+ with pytest.raises(TypeError, match="missing 1 required positional argument: 'self'"):
+ sm.send("start")
+
+ def test_class_body_function_cond_by_reference_is_bound(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ def can_start(self) -> bool:
+ return self.flag
+
+ start = created.to(started, cond=can_start)
+
+ def __init__(self, flag: bool):
+ self.flag = flag
+ super().__init__()
+
+ sm = ExampleStateMachine(flag=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(flag=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+
 class TestVisitConditionFalse:
  """visit/async_visit skip callbacks whose condition returns False."""
 

docs/guards.md

@@ -132,6 +132,71 @@ example combining multiple transitions on the same event.
 ```
 
 
+(callable conditions)=
+
+### Callable conditions
+
+Besides strings, `cond` and `unless` also accept callables directly, including
+lambdas, allowing simple guards to be defined inline:
+
+```py
+>>> class Turnstile(StateChart):
+... locked = State(initial=True)
+... unlocked = State(final=True)
+...
+... coin = locked.to(unlocked, cond=lambda machine: machine.credits > 0)
+...
+... credits = 0
+
+>>> sm = Turnstile()
+>>> sm.send("coin")
+>>> "locked" in sm.configuration_values
+True
+
+>>> sm.credits = 1
+>>> sm.send("coin")
+>>> "unlocked" in sm.configuration_values
+True
+
+```
+
+Like any callback, a callable condition receives its arguments via
+{ref}`dependency injection <dependency-injection>`: declare only the
+parameters you need, using the injectable names (`machine`, `event`,
+`source`, `target`, `model`, ...) or the arguments passed when triggering
+the event:
+
+```py
+>>> class Dispatcher(StateChart):
+... idle = State(initial=True)
+... dispatched = State(final=True)
+...
+... dispatch = idle.to(dispatched, cond=lambda priority=0: priority > 5)
+
+>>> sm = Dispatcher()
+>>> sm.send("dispatch", priority=1)
+>>> "idle" in sm.configuration_values
+True
+
+>>> sm.send("dispatch", priority=9)
+>>> "dispatched" in sm.configuration_values
+True
+
+```
+
+```{warning}
+Plain callables, like lambdas and functions defined outside the class body,
+are called **unbound**, so `self` is not injected. A guard declared as
+`cond=lambda self: ...` fails with a `TypeError` when evaluated. Use
+`machine` instead of `self` to receive the state machine instance.
+
+`self` is only available when the callable resolves to a bound method,
+which happens when it is an attribute of the state machine class: either
+referenced by name (`cond="my_condition"`) or defined in the class body
+and passed by reference (`cond=my_condition`).
+```
+
+
 (condition expressions)=
 
 ### Condition expressions

tests/test_callbacks.py

@@ -354,6 +354,102 @@ class ExampleStateMachine(StateChart):
  ExampleStateMachine()
 
 
+class TestIssue638:
+ """Guards passed as plain callables (e.g. lambdas) are resolved unbound.
+
+ Dependency injection works by parameter name, so ``self`` is only injected when
+ the callable is an attribute of the class and gets resolved to a bound method.
+ Plain callables must declare injectable names (e.g. ``machine``) instead.
+
+ See: https://github.com/fgmacedo/python-statemachine/issues/638
+ """
+
+ def test_lambda_cond_with_machine_param(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda machine: machine.can_start)
+
+ def __init__(self, can_start: bool):
+ self.can_start = can_start
+ super().__init__()
+
+ sm = ExampleStateMachine(can_start=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(can_start=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_without_params(self):
+ flags = {"can_start": False}
+
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda: flags["can_start"])
+
+ sm = ExampleStateMachine()
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ flags["can_start"] = True
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_event_kwargs(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda priority=0: priority > 5)
+
+ sm = ExampleStateMachine()
+ sm.send("start", priority=1)
+ assert "created" in sm.configuration_values
+
+ sm.send("start", priority=9)
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_self_param_is_called_unbound(self):
+ class ExampleStateMachine(StateChart):
+ catch_errors_as_events = False
+
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda self: True)
+
+ sm = ExampleStateMachine()
+ with pytest.raises(TypeError, match="missing 1 required positional argument: 'self'"):
+ sm.send("start")
+
+ def test_class_body_function_cond_by_reference_is_bound(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ def can_start(self) -> bool:
+ return self.flag
+
+ start = created.to(started, cond=can_start)
+
+ def __init__(self, flag: bool):
+ self.flag = flag
+ super().__init__()
+
+ sm = ExampleStateMachine(flag=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(flag=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+
 class TestVisitConditionFalse:
  """visit/async_visit skip callbacks whose condition returns False."""
 

docs/guards.md

@@ -132,6 +132,71 @@ example combining multiple transitions on the same event.
 ```
 
 
+(callable conditions)=
+
+### Callable conditions
+
+Besides strings, `cond` and `unless` also accept callables directly, including
+lambdas, allowing simple guards to be defined inline:
+
+```py
+>>> class Turnstile(StateChart):
+... locked = State(initial=True)
+... unlocked = State(final=True)
+...
+... coin = locked.to(unlocked, cond=lambda machine: machine.credits > 0)
+...
+... credits = 0
+
+>>> sm = Turnstile()
+>>> sm.send("coin")
+>>> "locked" in sm.configuration_values
+True
+
+>>> sm.credits = 1
+>>> sm.send("coin")
+>>> "unlocked" in sm.configuration_values
+True
+
+```
+
+Like any callback, a callable condition receives its arguments via
+{ref}`dependency injection <dependency-injection>`: declare only the
+parameters you need, using the injectable names (`machine`, `event`,
+`source`, `target`, `model`, ...) or the arguments passed when triggering
+the event:
+
+```py
+>>> class Dispatcher(StateChart):
+... idle = State(initial=True)
+... dispatched = State(final=True)
+...
+... dispatch = idle.to(dispatched, cond=lambda priority=0: priority > 5)
+
+>>> sm = Dispatcher()
+>>> sm.send("dispatch", priority=1)
+>>> "idle" in sm.configuration_values
+True
+
+>>> sm.send("dispatch", priority=9)
+>>> "dispatched" in sm.configuration_values
+True
+
+```
+
+```{warning}
+Plain callables, like lambdas and functions defined outside the class body,
+are called **unbound**, so `self` is not injected. A guard declared as
+`cond=lambda self: ...` fails with a `TypeError` when evaluated. Use
+`machine` instead of `self` to receive the state machine instance.
+
+`self` is only available when the callable resolves to a bound method,
+which happens when it is an attribute of the state machine class: either
+referenced by name (`cond="my_condition"`) or defined in the class body
+and passed by reference (`cond=my_condition`).
+```
+
+
 (condition expressions)=
 
 ### Condition expressions

tests/test_callbacks.py

@@ -354,6 +354,102 @@ class ExampleStateMachine(StateChart):
  ExampleStateMachine()
 
 
+class TestIssue638:
+ """Guards passed as plain callables (e.g. lambdas) are resolved unbound.
+
+ Dependency injection works by parameter name, so ``self`` is only injected when
+ the callable is an attribute of the class and gets resolved to a bound method.
+ Plain callables must declare injectable names (e.g. ``machine``) instead.
+
+ See: https://github.com/fgmacedo/python-statemachine/issues/638
+ """
+
+ def test_lambda_cond_with_machine_param(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda machine: machine.can_start)
+
+ def __init__(self, can_start: bool):
+ self.can_start = can_start
+ super().__init__()
+
+ sm = ExampleStateMachine(can_start=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(can_start=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_without_params(self):
+ flags = {"can_start": False}
+
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda: flags["can_start"])
+
+ sm = ExampleStateMachine()
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ flags["can_start"] = True
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_event_kwargs(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda priority=0: priority > 5)
+
+ sm = ExampleStateMachine()
+ sm.send("start", priority=1)
+ assert "created" in sm.configuration_values
+
+ sm.send("start", priority=9)
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_self_param_is_called_unbound(self):
+ class ExampleStateMachine(StateChart):
+ catch_errors_as_events = False
+
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda self: True)
+
+ sm = ExampleStateMachine()
+ with pytest.raises(TypeError, match="missing 1 required positional argument: 'self'"):
+ sm.send("start")
+
+ def test_class_body_function_cond_by_reference_is_bound(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ def can_start(self) -> bool:
+ return self.flag
+
+ start = created.to(started, cond=can_start)
+
+ def __init__(self, flag: bool):
+ self.flag = flag
+ super().__init__()
+
+ sm = ExampleStateMachine(flag=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(flag=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+
 class TestVisitConditionFalse:
  """visit/async_visit skip callbacks whose condition returns False."""
 

docs/guards.md

@@ -132,6 +132,71 @@ example combining multiple transitions on the same event.
 ```
 
 
+(callable conditions)=
+
+### Callable conditions
+
+Besides strings, `cond` and `unless` also accept callables directly, including
+lambdas, allowing simple guards to be defined inline:
+
+```py
+>>> class Turnstile(StateChart):
+... locked = State(initial=True)
+... unlocked = State(final=True)
+...
+... coin = locked.to(unlocked, cond=lambda machine: machine.credits > 0)
+...
+... credits = 0
+
+>>> sm = Turnstile()
+>>> sm.send("coin")
+>>> "locked" in sm.configuration_values
+True
+
+>>> sm.credits = 1
+>>> sm.send("coin")
+>>> "unlocked" in sm.configuration_values
+True
+
+```
+
+Like any callback, a callable condition receives its arguments via
+{ref}`dependency injection <dependency-injection>`: declare only the
+parameters you need, using the injectable names (`machine`, `event`,
+`source`, `target`, `model`, ...) or the arguments passed when triggering
+the event:
+
+```py
+>>> class Dispatcher(StateChart):
+... idle = State(initial=True)
+... dispatched = State(final=True)
+...
+... dispatch = idle.to(dispatched, cond=lambda priority=0: priority > 5)
+
+>>> sm = Dispatcher()
+>>> sm.send("dispatch", priority=1)
+>>> "idle" in sm.configuration_values
+True
+
+>>> sm.send("dispatch", priority=9)
+>>> "dispatched" in sm.configuration_values
+True
+
+```
+
+```{warning}
+Plain callables, like lambdas and functions defined outside the class body,
+are called **unbound**, so `self` is not injected. A guard declared as
+`cond=lambda self: ...` fails with a `TypeError` when evaluated. Use
+`machine` instead of `self` to receive the state machine instance.
+
+`self` is only available when the callable resolves to a bound method,
+which happens when it is an attribute of the state machine class: either
+referenced by name (`cond="my_condition"`) or defined in the class body
+and passed by reference (`cond=my_condition`).
+```
+
+
 (condition expressions)=
 
 ### Condition expressions

tests/test_callbacks.py

@@ -354,6 +354,102 @@ class ExampleStateMachine(StateChart):
  ExampleStateMachine()
 
 
+class TestIssue638:
+ """Guards passed as plain callables (e.g. lambdas) are resolved unbound.
+
+ Dependency injection works by parameter name, so ``self`` is only injected when
+ the callable is an attribute of the class and gets resolved to a bound method.
+ Plain callables must declare injectable names (e.g. ``machine``) instead.
+
+ See: https://github.com/fgmacedo/python-statemachine/issues/638
+ """
+
+ def test_lambda_cond_with_machine_param(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda machine: machine.can_start)
+
+ def __init__(self, can_start: bool):
+ self.can_start = can_start
+ super().__init__()
+
+ sm = ExampleStateMachine(can_start=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(can_start=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_without_params(self):
+ flags = {"can_start": False}
+
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda: flags["can_start"])
+
+ sm = ExampleStateMachine()
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ flags["can_start"] = True
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_event_kwargs(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda priority=0: priority > 5)
+
+ sm = ExampleStateMachine()
+ sm.send("start", priority=1)
+ assert "created" in sm.configuration_values
+
+ sm.send("start", priority=9)
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_self_param_is_called_unbound(self):
+ class ExampleStateMachine(StateChart):
+ catch_errors_as_events = False
+
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda self: True)
+
+ sm = ExampleStateMachine()
+ with pytest.raises(TypeError, match="missing 1 required positional argument: 'self'"):
+ sm.send("start")
+
+ def test_class_body_function_cond_by_reference_is_bound(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ def can_start(self) -> bool:
+ return self.flag
+
+ start = created.to(started, cond=can_start)
+
+ def __init__(self, flag: bool):
+ self.flag = flag
+ super().__init__()
+
+ sm = ExampleStateMachine(flag=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(flag=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+
 class TestVisitConditionFalse:
  """visit/async_visit skip callbacks whose condition returns False."""
 

docs/guards.md

@@ -132,6 +132,71 @@ example combining multiple transitions on the same event.
 ```
 
 
+(callable conditions)=
+
+### Callable conditions
+
+Besides strings, `cond` and `unless` also accept callables directly, including
+lambdas, allowing simple guards to be defined inline:
+
+```py
+>>> class Turnstile(StateChart):
+... locked = State(initial=True)
+... unlocked = State(final=True)
+...
+... coin = locked.to(unlocked, cond=lambda machine: machine.credits > 0)
+...
+... credits = 0
+
+>>> sm = Turnstile()
+>>> sm.send("coin")
+>>> "locked" in sm.configuration_values
+True
+
+>>> sm.credits = 1
+>>> sm.send("coin")
+>>> "unlocked" in sm.configuration_values
+True
+
+```
+
+Like any callback, a callable condition receives its arguments via
+{ref}`dependency injection <dependency-injection>`: declare only the
+parameters you need, using the injectable names (`machine`, `event`,
+`source`, `target`, `model`, ...) or the arguments passed when triggering
+the event:
+
+```py
+>>> class Dispatcher(StateChart):
+... idle = State(initial=True)
+... dispatched = State(final=True)
+...
+... dispatch = idle.to(dispatched, cond=lambda priority=0: priority > 5)
+
+>>> sm = Dispatcher()
+>>> sm.send("dispatch", priority=1)
+>>> "idle" in sm.configuration_values
+True
+
+>>> sm.send("dispatch", priority=9)
+>>> "dispatched" in sm.configuration_values
+True
+
+```
+
+```{warning}
+Plain callables, like lambdas and functions defined outside the class body,
+are called **unbound**, so `self` is not injected. A guard declared as
+`cond=lambda self: ...` fails with a `TypeError` when evaluated. Use
+`machine` instead of `self` to receive the state machine instance.
+
+`self` is only available when the callable resolves to a bound method,
+which happens when it is an attribute of the state machine class: either
+referenced by name (`cond="my_condition"`) or defined in the class body
+and passed by reference (`cond=my_condition`).
+```
+
+
 (condition expressions)=
 
 ### Condition expressions

tests/test_callbacks.py

@@ -354,6 +354,102 @@ class ExampleStateMachine(StateChart):
  ExampleStateMachine()
 
 
+class TestIssue638:
+ """Guards passed as plain callables (e.g. lambdas) are resolved unbound.
+
+ Dependency injection works by parameter name, so ``self`` is only injected when
+ the callable is an attribute of the class and gets resolved to a bound method.
+ Plain callables must declare injectable names (e.g. ``machine``) instead.
+
+ See: https://github.com/fgmacedo/python-statemachine/issues/638
+ """
+
+ def test_lambda_cond_with_machine_param(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda machine: machine.can_start)
+
+ def __init__(self, can_start: bool):
+ self.can_start = can_start
+ super().__init__()
+
+ sm = ExampleStateMachine(can_start=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(can_start=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_without_params(self):
+ flags = {"can_start": False}
+
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda: flags["can_start"])
+
+ sm = ExampleStateMachine()
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ flags["can_start"] = True
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_event_kwargs(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda priority=0: priority > 5)
+
+ sm = ExampleStateMachine()
+ sm.send("start", priority=1)
+ assert "created" in sm.configuration_values
+
+ sm.send("start", priority=9)
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_self_param_is_called_unbound(self):
+ class ExampleStateMachine(StateChart):
+ catch_errors_as_events = False
+
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda self: True)
+
+ sm = ExampleStateMachine()
+ with pytest.raises(TypeError, match="missing 1 required positional argument: 'self'"):
+ sm.send("start")
+
+ def test_class_body_function_cond_by_reference_is_bound(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ def can_start(self) -> bool:
+ return self.flag
+
+ start = created.to(started, cond=can_start)
+
+ def __init__(self, flag: bool):
+ self.flag = flag
+ super().__init__()
+
+ sm = ExampleStateMachine(flag=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(flag=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+
 class TestVisitConditionFalse:
  """visit/async_visit skip callbacks whose condition returns False."""
 

docs/guards.md

@@ -132,6 +132,71 @@ example combining multiple transitions on the same event.
 ```
 
 
+(callable conditions)=
+
+### Callable conditions
+
+Besides strings, `cond` and `unless` also accept callables directly, including
+lambdas, allowing simple guards to be defined inline:
+
+```py
+>>> class Turnstile(StateChart):
+... locked = State(initial=True)
+... unlocked = State(final=True)
+...
+... coin = locked.to(unlocked, cond=lambda machine: machine.credits > 0)
+...
+... credits = 0
+
+>>> sm = Turnstile()
+>>> sm.send("coin")
+>>> "locked" in sm.configuration_values
+True
+
+>>> sm.credits = 1
+>>> sm.send("coin")
+>>> "unlocked" in sm.configuration_values
+True
+
+```
+
+Like any callback, a callable condition receives its arguments via
+{ref}`dependency injection <dependency-injection>`: declare only the
+parameters you need, using the injectable names (`machine`, `event`,
+`source`, `target`, `model`, ...) or the arguments passed when triggering
+the event:
+
+```py
+>>> class Dispatcher(StateChart):
+... idle = State(initial=True)
+... dispatched = State(final=True)
+...
+... dispatch = idle.to(dispatched, cond=lambda priority=0: priority > 5)
+
+>>> sm = Dispatcher()
+>>> sm.send("dispatch", priority=1)
+>>> "idle" in sm.configuration_values
+True
+
+>>> sm.send("dispatch", priority=9)
+>>> "dispatched" in sm.configuration_values
+True
+
+```
+
+```{warning}
+Plain callables, like lambdas and functions defined outside the class body,
+are called **unbound**, so `self` is not injected. A guard declared as
+`cond=lambda self: ...` fails with a `TypeError` when evaluated. Use
+`machine` instead of `self` to receive the state machine instance.
+
+`self` is only available when the callable resolves to a bound method,
+which happens when it is an attribute of the state machine class: either
+referenced by name (`cond="my_condition"`) or defined in the class body
+and passed by reference (`cond=my_condition`).
+```
+
+
 (condition expressions)=
 
 ### Condition expressions

tests/test_callbacks.py

@@ -354,6 +354,102 @@ class ExampleStateMachine(StateChart):
  ExampleStateMachine()
 
 
+class TestIssue638:
+ """Guards passed as plain callables (e.g. lambdas) are resolved unbound.
+
+ Dependency injection works by parameter name, so ``self`` is only injected when
+ the callable is an attribute of the class and gets resolved to a bound method.
+ Plain callables must declare injectable names (e.g. ``machine``) instead.
+
+ See: https://github.com/fgmacedo/python-statemachine/issues/638
+ """
+
+ def test_lambda_cond_with_machine_param(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda machine: machine.can_start)
+
+ def __init__(self, can_start: bool):
+ self.can_start = can_start
+ super().__init__()
+
+ sm = ExampleStateMachine(can_start=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(can_start=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_without_params(self):
+ flags = {"can_start": False}
+
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda: flags["can_start"])
+
+ sm = ExampleStateMachine()
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ flags["can_start"] = True
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_event_kwargs(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda priority=0: priority > 5)
+
+ sm = ExampleStateMachine()
+ sm.send("start", priority=1)
+ assert "created" in sm.configuration_values
+
+ sm.send("start", priority=9)
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_self_param_is_called_unbound(self):
+ class ExampleStateMachine(StateChart):
+ catch_errors_as_events = False
+
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda self: True)
+
+ sm = ExampleStateMachine()
+ with pytest.raises(TypeError, match="missing 1 required positional argument: 'self'"):
+ sm.send("start")
+
+ def test_class_body_function_cond_by_reference_is_bound(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ def can_start(self) -> bool:
+ return self.flag
+
+ start = created.to(started, cond=can_start)
+
+ def __init__(self, flag: bool):
+ self.flag = flag
+ super().__init__()
+
+ sm = ExampleStateMachine(flag=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(flag=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+
 class TestVisitConditionFalse:
  """visit/async_visit skip callbacks whose condition returns False."""
 

docs/guards.md

@@ -132,6 +132,71 @@ example combining multiple transitions on the same event.
 ```
 
 
+(callable conditions)=
+
+### Callable conditions
+
+Besides strings, `cond` and `unless` also accept callables directly, including
+lambdas, allowing simple guards to be defined inline:
+
+```py
+>>> class Turnstile(StateChart):
+... locked = State(initial=True)
+... unlocked = State(final=True)
+...
+... coin = locked.to(unlocked, cond=lambda machine: machine.credits > 0)
+...
+... credits = 0
+
+>>> sm = Turnstile()
+>>> sm.send("coin")
+>>> "locked" in sm.configuration_values
+True
+
+>>> sm.credits = 1
+>>> sm.send("coin")
+>>> "unlocked" in sm.configuration_values
+True
+
+```
+
+Like any callback, a callable condition receives its arguments via
+{ref}`dependency injection <dependency-injection>`: declare only the
+parameters you need, using the injectable names (`machine`, `event`,
+`source`, `target`, `model`, ...) or the arguments passed when triggering
+the event:
+
+```py
+>>> class Dispatcher(StateChart):
+... idle = State(initial=True)
+... dispatched = State(final=True)
+...
+... dispatch = idle.to(dispatched, cond=lambda priority=0: priority > 5)
+
+>>> sm = Dispatcher()
+>>> sm.send("dispatch", priority=1)
+>>> "idle" in sm.configuration_values
+True
+
+>>> sm.send("dispatch", priority=9)
+>>> "dispatched" in sm.configuration_values
+True
+
+```
+
+```{warning}
+Plain callables, like lambdas and functions defined outside the class body,
+are called **unbound**, so `self` is not injected. A guard declared as
+`cond=lambda self: ...` fails with a `TypeError` when evaluated. Use
+`machine` instead of `self` to receive the state machine instance.
+
+`self` is only available when the callable resolves to a bound method,
+which happens when it is an attribute of the state machine class: either
+referenced by name (`cond="my_condition"`) or defined in the class body
+and passed by reference (`cond=my_condition`).
+```
+
+
 (condition expressions)=
 
 ### Condition expressions

tests/test_callbacks.py

@@ -354,6 +354,102 @@ class ExampleStateMachine(StateChart):
  ExampleStateMachine()
 
 
+class TestIssue638:
+ """Guards passed as plain callables (e.g. lambdas) are resolved unbound.
+
+ Dependency injection works by parameter name, so ``self`` is only injected when
+ the callable is an attribute of the class and gets resolved to a bound method.
+ Plain callables must declare injectable names (e.g. ``machine``) instead.
+
+ See: https://github.com/fgmacedo/python-statemachine/issues/638
+ """
+
+ def test_lambda_cond_with_machine_param(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda machine: machine.can_start)
+
+ def __init__(self, can_start: bool):
+ self.can_start = can_start
+ super().__init__()
+
+ sm = ExampleStateMachine(can_start=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(can_start=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_without_params(self):
+ flags = {"can_start": False}
+
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda: flags["can_start"])
+
+ sm = ExampleStateMachine()
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ flags["can_start"] = True
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_event_kwargs(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda priority=0: priority > 5)
+
+ sm = ExampleStateMachine()
+ sm.send("start", priority=1)
+ assert "created" in sm.configuration_values
+
+ sm.send("start", priority=9)
+ assert "started" in sm.configuration_values
+
+ def test_lambda_cond_with_self_param_is_called_unbound(self):
+ class ExampleStateMachine(StateChart):
+ catch_errors_as_events = False
+
+ created = State(initial=True)
+ started = State(final=True)
+
+ start = created.to(started, cond=lambda self: True)
+
+ sm = ExampleStateMachine()
+ with pytest.raises(TypeError, match="missing 1 required positional argument: 'self'"):
+ sm.send("start")
+
+ def test_class_body_function_cond_by_reference_is_bound(self):
+ class ExampleStateMachine(StateChart):
+ created = State(initial=True)
+ started = State(final=True)
+
+ def can_start(self) -> bool:
+ return self.flag
+
+ start = created.to(started, cond=can_start)
+
+ def __init__(self, flag: bool):
+ self.flag = flag
+ super().__init__()
+
+ sm = ExampleStateMachine(flag=False)
+ sm.send("start")
+ assert "created" in sm.configuration_values
+
+ sm = ExampleStateMachine(flag=True)
+ sm.send("start")
+ assert "started" in sm.configuration_values
+
+
 class TestVisitConditionFalse:
  """visit/async_visit skip callbacks whose condition returns False."""