fix: validate Event() id parameter to prevent silent transition loss (#588)

* fix: validate Event() id parameter to prevent silent transition loss

Passing multiple transitions as positional args to Event() (e.g.,
Event(t1, t2)) caused the second argument to be silently interpreted
as the event id, leaving those transitions eventless (auto-firing).

Now raises InvalidDefinition with a message suggesting the | operator.

Author: fgmacedo

docs/releases/3.1.0.md

@@ -0,0 +1,15 @@
+# StateChart 3.1.0
+
+*Not released yet*
+
+## What's new in 3.1.0
+
+### Bugfixes in 3.1.0
+
+- Fixes silent misuse of `Event()` with multiple positional arguments. Passing more than one
+  transition to `Event()` (e.g., `Event(t1, t2)`) now raises {ref}`InvalidDefinition` with a
+  clear message suggesting the `|` operator. Previously, the second argument was silently
+  interpreted as the event `id`, leaving the extra transitions eventless (auto-firing).
+  [#588](https://github.com/fgmacedo/python-statemachine/pull/588).
+
+## Misc in 3.1.0

docs/releases/index.md

@@ -16,6 +16,7 @@ Requires Python 3.9+.
 ```{toctree}
 :maxdepth: 2
 
+3.1.0
 3.0.0
 
 ```

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-statemachine"
-version = "3.0.0"
+version = "3.1.0"
 description = "Python Finite State Machines made easy."
 authors = [{ name = "Fernando Macedo", email = "fgmacedo@gmail.com" }]
 maintainers = [{ name = "Fernando Macedo", email = "fgmacedo@gmail.com" }]

statemachine/__init__.py

@@ -8,7 +8,7 @@
 
 __author__ = """Fernando Macedo"""
 __email__ = "fgmacedo@gmail.com"
-__version__ = "3.0.0"
+__version__ = "3.1.0"
 
 __all__ = [
     "StateChart",

statemachine/event.py

@@ -88,6 +88,15 @@ def __new__(
             id = transitions
             transitions = None
 
+        if id is not None and not isinstance(id, str):
+            raise InvalidDefinition(
+                _(
+                    "Event() received a non-string 'id' ({cls_name}). "
+                    "To combine multiple transitions under one event, "
+                    "use the | operator: t1 | t2."
+                ).format(cls_name=type(id).__name__)
+            )
+
         _has_real_id = id is not None
         id = str(id) if _has_real_id else f"__event__{uuid4().hex}"
 

tests/test_events.py

@@ -330,3 +330,18 @@ def test_events_match_none_with_empty():
 
     events = Events()
     assert events.match(None) is True
+
+
+def test_event_raises_on_non_string_id():
+    """Event() should raise InvalidDefinition when id is not a string.
+
+    This catches a common mistake where users pass multiple transitions as
+    positional args (e.g. Event(t1, t2)) instead of combining them with |.
+    """
+    s1 = State(initial=True)
+    s2 = State(final=True)
+    t1 = s1.to(s2)
+    t2 = s2.to(s1)
+
+    with pytest.raises(InvalidDefinition, match="non-string 'id'.*use the \\| operator"):
+        Event(t1, t2)