Skip to content

fix: honor Event(internal=True) when the event is triggered #663

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
chiliec wants to merge 1 commit into from
Closed

fix: honor Event(internal=True) when the event is triggered #663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/processing_model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ The engine maintains two separate FIFO queues:

| Queue | How to enqueue | When processed |
|---|---|---|
| **Internal** | {func}`raise_() <StateMachine.raise_>` or `send(..., internal=True)` | Within the current macrostep |
| **Internal** | {func}`raise_() <StateMachine.raise_>`, `send(..., internal=True)`, or an event declared with `Event(..., internal=True)` | Within the current macrostep |
| **External** | {func}`send() <StateMachine.send>` | After the current macrostep ends |

This distinction matters when you trigger events from inside callbacks.
Expand Down
11 changes: 9 additions & 2 deletions docs/releases/3.2.2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,8 +80,7 @@ Reported by [@Dolecor](https://github.com/Dolecor).

`Event(dark.to(lit), delay=50)` rebuilt the event without its `delay`, so
`BeaconsOfGondor.light.delay` was `0` and the event fired immediately instead of being queued.
The same happened to `internal`. Both are now preserved, although `internal` still has no
effect at trigger time:
The same happened to `internal`. Both are now preserved:

```py
>>> class BeaconsOfGondor(StateChart):
Expand All @@ -94,3 +93,11 @@ effect at trigger time:
50

```

### `internal` declared on an `Event` ignored at trigger time

`Event(a.to(b), internal=True)` kept `internal` on the declaration, but neither `sm.go()` nor
`sm.send("go")` carried it to the queue, so the event always went to the external queue. Both
paths now honor the declaration and put the event on the internal queue.

@fgmacedo fgmacedo Oct 11, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (non-blocking): Both engines collect the processing result only from external events, so sm.go() on a declared-internal event now returns None instead of the callback result (verified: on_go returning "go-result" gives None once internal=True is declared). A class-level flag changing the return contract of every caller is worth one sentence here.


[#655](https://github.com/fgmacedo/python-statemachine/issues/655).
4 changes: 3 additions & 1 deletion statemachine/event.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,9 @@ def __get__(self, instance, owner):
"""
if instance is None:
return self
return BoundEvent(id=self.id, name=self.name, delay=self.delay, _sm=instance)
return BoundEvent(
id=self.id, name=self.name, delay=self.delay, internal=self.internal, _sm=instance

@fgmacedo fgmacedo Oct 11, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue (blocking): Carrying internal through makes a declared delay silently inert: the internal queue never checks execution_time (only Phase 3 does), so Event(dark.to(lit), delay=50, internal=True) now fires at 0 ms, while on develop it waited 50 ms. That is exactly the declaration in test_accept_delay_and_internal and the example right above the new release note. Either hold internal triggers until their due time in both engines, or reject delay together with internal=True and say so in the note. raise_(..., delay=) has the same hole today, so a follow-up could cover it; #665 is rewriting the due-time checks, worth aligning with it.

)

def put(self, *args, send_id: "str | None" = None, **kwargs):
# The `__call__` is declared here to help IDEs knowing that an `Event`
Expand Down
1 change: 1 addition & 0 deletions statemachine/statemachine.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -483,6 +483,7 @@ def send(
delay = (
delay if delay else know_event and know_event.delay or 0
) # first the param, then the event, or 0
internal = internal or bool(know_event and know_event.internal)

@fgmacedo fgmacedo Oct 11, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue (blocking): On the async engine the first await sm.go() on a fresh machine now drops the event: Phase 1 pops it from the internal queue while the configuration is still empty (the __initial__ external event has not run yet), so it matches nothing, go() returns None and the machine stays in a. On develop the same declaration worked because the event went external, behind __initial__. docs/async.md promises the first send() activates the initial state automatically. Activate the initial configuration before an internal put from outside the loop, or process __initial__ before draining the internal queue when the configuration is empty.

event_instance = BoundEvent(
id=event, name=event_name, delay=delay, internal=internal, _sm=self
)
Expand Down
25 changes: 25 additions & 0 deletions tests/test_events.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,31 @@ class BeaconsOfGondor(StateChart):
assert BeaconsOfGondor.light.delay == 50
assert BeaconsOfGondor().light.delay == 50

@fgmacedo fgmacedo Oct 11, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick (non-blocking): The bound side of internal has no direct assertion.

Suggested change
assert BeaconsOfGondor().light.delay == 50
assert BeaconsOfGondor().light.delay == 50
assert BeaconsOfGondor().light.internal is True


@pytest.mark.parametrize("trigger", ["method", "send"])
def test_declared_internal_puts_on_the_internal_queue(self, trigger):

@fgmacedo fgmacedo Oct 11, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (non-blocking): Run this through sm_runner so the async engine is covered too (CLAUDE.md, "Testing both sync and async engines"); the async path is where the declaration misbehaves (see the comment on send). A case that triggers before activate_initial_state() would have caught the dropped event.

class BeaconsOfGondor(StateChart):
dark = State(initial=True)
lit = State(final=True)

light = Event(dark.to(lit), internal=True)

sm = BeaconsOfGondor()
queued = []
put = sm._engine.put

def spy(trigger_data, internal=False, **kwargs):
queued.append(internal)
return put(trigger_data, internal=internal, **kwargs)

sm._engine.put = spy
if trigger == "method":
sm.light()
else:
sm.send("light")

assert queued == [True]
assert sm.lit.is_active

def test_derive_name_from_id(self):
class StartMachine(StateChart):
created = State(initial=True)
Expand Down
Loading