fgmacedo · fgmacedo · Mar 1, 2026 · Mar 1, 2026 · Mar 1, 2026 · Mar 1, 2026
diff --git a/docs/releases/3.1.0.md b/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
diff --git a/docs/releases/index.md b/docs/releases/index.md
@@ -16,6 +16,7 @@ Requires Python 3.9+.
 ```{toctree}
 :maxdepth: 2
 
+3.1.0
 3.0.0
 
 ```

diff --git a/pyproject.toml b/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 = "[email protected]" }]
 maintainers = [{ name = "Fernando Macedo", email = "[email protected]" }]

diff --git a/statemachine/__init__.py b/statemachine/__init__.py
@@ -8,7 +8,7 @@
 
 __author__ = """Fernando Macedo"""
 __email__ = "[email protected]"
-__version__ = "3.0.0"
+__version__ = "3.1.0"
 
 __all__ = [
     "StateChart",

diff --git a/statemachine/event.py b/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}"
 

diff --git a/tests/test_events.py b/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)
diff --git a/uv.lock b/uv.lock
-Original file line number
+Diff line change
@@ Expand Up / @@ -16,6 +16,7 @@ Requires Python 3.9+. @@
     ```{toctree}
     :maxdepth: 2
+.1.0
 .0.0
     ```
@@ Expand Down @@