fix: render human-readable Event name in diagrams (#601)

* chore: add tmp/ to .gitignore

* fix: render human-readable Event name in diagrams (#600)

Event.name is now auto-generated as a humanized form of the id (split
by _ and . separators, first word capitalized) instead of echoing the
raw identifier. Explicit name= passed by the user is preserved.

- Add humanize_id() in utils.py (compiled regex, shared by Event and
  State)
- Remove redundant name= from Event call sites in factory, events,
  and SCXML actions so auto-generation kicks in
- Use event.name in diagram labels (_format_event_names)
- Update docs and tests to reflect humanized names

Closes #600

* docs: add event humanized name to 3.1.0 release notes

Author: fgmacedo

.gitignore

@@ -79,3 +79,6 @@ target/
 docs/auto_examples/sg_execution_times.*
 docs/auto_examples/*.pickle
 docs/sg_execution_times.rst
+
+# Temporary files
+tmp/

README.md

@@ -83,9 +83,10 @@ Generate a diagram or get a text representation with f-strings:
 >>> print(f"{sm:md}")
 | State  | Event | Guard | Target |
 | ------ | ----- | ----- | ------ |
-| Green  | cycle |       | Yellow |
-| Yellow | cycle |       | Red    |
-| Red    | cycle |       | Green  |
+| Green  | Cycle |       | Yellow |
+| Yellow | Cycle |       | Red    |
+| Red    | Cycle |       | Green  |
+<BLANKLINE>
 
 ```
 

docs/diagram.md

@@ -126,9 +126,9 @@ stateDiagram-v2
     state "Yellow" as yellow
     state "Red" as red
     [*] --> green
-    green --> yellow : cycle
-    yellow --> red : cycle
-    red --> green : cycle
+    green --> yellow : Cycle
+    yellow --> red : Cycle
+    red --> green : Cycle
 <BLANKLINE>
     classDef active fill:#40E0D0,stroke:#333
     green:::active
@@ -137,9 +137,9 @@ stateDiagram-v2
 >>> print(f"{sm:md}")
 | State  | Event | Guard | Target |
 | ------ | ----- | ----- | ------ |
-| Green  | cycle |       | Yellow |
-| Yellow | cycle |       | Red    |
-| Red    | cycle |       | Green  |
+| Green  | Cycle |       | Yellow |
+| Yellow | Cycle |       | Red    |
+| Red    | Cycle |       | Green  |
 <BLANKLINE>
 
 ```
@@ -154,9 +154,9 @@ stateDiagram-v2
     state "Yellow" as yellow
     state "Red" as red
     [*] --> green
-    green --> yellow : cycle
-    yellow --> red : cycle
-    red --> green : cycle
+    green --> yellow : Cycle
+    yellow --> red : Cycle
+    red --> green : Cycle
 <BLANKLINE>
 
 ```
@@ -191,9 +191,9 @@ stateDiagram-v2
     state "Yellow" as yellow
     state "Red" as red
     [*] --> green
-    green --> yellow : cycle
-    yellow --> red : cycle
-    red --> green : cycle
+    green --> yellow : Cycle
+    yellow --> red : Cycle
+    red --> green : Cycle
 <BLANKLINE>
 
 >>> formatter.supported_formats()
@@ -294,9 +294,9 @@ A traffic light.
 <BLANKLINE>
 | State  | Event | Guard | Target |
 | ------ | ----- | ----- | ------ |
-| Green  | cycle |       | Yellow |
-| Yellow | cycle |       | Red    |
-| Red    | cycle |       | Green  |
+| Green  | Cycle |       | Yellow |
+| Yellow | Cycle |       | Red    |
+| Red    | Cycle |       | Green  |
 <BLANKLINE>
 <BLANKLINE>
 

docs/events.md

@@ -80,21 +80,31 @@ Every event has two string properties:
 
 - **`id`** — the programmatic identifier, derived from the class attribute name.
   Use this in `send()`, guards, and comparisons.
-- **`name`** — a human-readable label for display purposes. Defaults to the `id`
-  when not explicitly set.
+- **`name`** — a human-readable label for display purposes. Auto-generated from
+  the `id` by replacing `_` and `.` with spaces and capitalizing the first word.
+  You can override the automatic name by passing `name=` explicitly when
+  declaring the event:
 
 ```py
 >>> TrafficLight.cycle.id
 'cycle'
 
 >>> TrafficLight.cycle.name
-'cycle'
+'Cycle'
+
+>>> class Example(StateChart):
+...     on = State(initial=True)
+...     off = State(final=True)
+...     shut_down = Event(on.to(off), name="Shut the system down")
+
+>>> Example.shut_down.name
+'Shut the system down'
 
 ```
 
 ```{tip}
 Always use `event.id` for programmatic checks. The `name` property is intended
-for UI display and may change format in future versions.
+for UI display and may differ from the `id`.
 ```
 
 

docs/images/readme_trafficlightmachine.png

@@ -158,4 +158,11 @@ machine instance concurrently. This is now documented in the
   interpreted as the event `id`, leaving the extra transitions eventless (auto-firing).
   [#588](https://github.com/fgmacedo/python-statemachine/pull/588).
 
+- `Event.name` is now auto-humanized from the `id` (e.g., `cycle` → `Cycle`,
+  `pick_up` → `Pick up`). Diagrams, Mermaid output, and text tables all display
+  the human-readable name. Explicit `name=` values are preserved. The same
+  `humanize_id()` helper is now shared by `Event` and `State`.
+  [#601](https://github.com/fgmacedo/python-statemachine/pull/601),
+  fixes [#600](https://github.com/fgmacedo/python-statemachine/issues/600).
+
 ## Misc in 3.1.0

docs/releases/3.1.0.md

@@ -375,9 +375,9 @@ You can also get text representations of any state machine using Python's built-
 >>> print(f"{CoffeeOrder:md}")
 | State     | Event   | Guard | Target    |
 | --------- | ------- | ----- | --------- |
-| Pending   | start   |       | Preparing |
-| Preparing | finish  |       | Ready     |
-| Ready     | pick_up |       | Picked up |
+| Pending   | Start   |       | Preparing |
+| Preparing | Finish  |       | Ready     |
+| Ready     | Pick up |       | Picked up |
 
 ```
 
@@ -394,9 +394,9 @@ stateDiagram-v2
     state "Picked up" as picked_up
     [*] --> pending
     picked_up --> [*]
-    pending --> preparing : start
-    preparing --> ready : finish
-    ready --> picked_up : pick_up
+    pending --> preparing : Start
+    preparing --> ready : Finish
+    ready --> picked_up : Pick up
 <BLANKLINE>
 
 ```

docs/tutorial.md

@@ -116,15 +116,17 @@ def _format_event_names(transition: "Transition") -> str:
 
     all_ids = {str(e) for e in events}
 
+    seen_ids: Set[str] = set()
     display: List[str] = []
     for event in events:
         eid = str(event)
         # Skip dot-form aliases (e.g. "done.invoke.X") when the underscore
         # form ("done_invoke_X") is also registered on this transition.
         if "." in eid and eid.replace(".", "_") in all_ids:
             continue
-        if eid not in display:  # pragma: no branch
-            display.append(eid)
+        if eid not in seen_ids:  # pragma: no branch
+            seen_ids.add(eid)
+            display.append(event.name if event.name else eid)
 
     return " ".join(display)
 

statemachine/contrib/diagram/extract.py

@@ -9,6 +9,7 @@
 from .exceptions import InvalidDefinition
 from .i18n import _
 from .transition_mixin import AddCallbacksMixin
+from .utils import humanize_id
 
 if TYPE_CHECKING:
     from .statemachine import StateChart
@@ -107,7 +108,7 @@ def __new__(
         if name:
             instance.name = name
         elif _has_real_id:
-            instance.name = str(id).replace("_", " ").capitalize()
+            instance.name = humanize_id(id)
         else:
             instance.name = ""
         if transitions:

statemachine/event.py

@@ -30,7 +30,7 @@ def add(self, events):
                 if isinstance(event, Event):
                     self._items.append(event)
                 else:
-                    self._items.append(Event(id=event, name=event))
+                    self._items.append(Event(id=event))
 
         return self