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

Author: fgmacedo

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

@@ -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
 

statemachine/events.py

@@ -310,7 +310,7 @@ def add_from_attributes(cls, attrs):  # noqa: C901
                 cls.add_state(key, value)
             elif isinstance(value, (Transition, TransitionList)):
                 event_id = _expand_event_id(key)
-                cls.add_event(event=Event(transitions=value, id=event_id, name=key))
+                cls.add_event(event=Event(transitions=value, id=event_id))
             elif isinstance(value, (Event,)):
                 if value._has_real_id:
                     event_id = value.id
@@ -338,7 +338,7 @@ def _add_unbounded_callback(cls, attr_name, func):
         # machinery that is stored at ``func.attr_name``
         setattr(cls, func.attr_name, func)
         if func.is_event:
-            cls.add_event(event=Event(func._transitions, id=attr_name, name=attr_name))
+            cls.add_event(event=Event(func._transitions, id=attr_name))
 
     def add_state(cls, id, state: State):
         state._set_id(id)

statemachine/factory.py

@@ -382,7 +382,7 @@ def create_raise_action_callable(action: RaiseAction) -> Callable:
     def raise_action(*args, **kwargs):
         machine: StateChart = kwargs["machine"]
 
-        Event(id=action.event, name=action.event, internal=True, _sm=machine).put()
+        Event(id=action.event, internal=True, _sm=machine).put()
 
     raise_action.action = action  # type: ignore[attr-defined]
     return raise_action
@@ -492,7 +492,7 @@ def send_action(*args, **kwargs):  # noqa: C901
                 continue
             params_values[param.name] = _eval(param.expr, **kwargs)
 
-        Event(id=event, name=event, delay=delay, internal=internal, _sm=machine).put(
+        Event(id=event, delay=delay, internal=internal, _sm=machine).put(
             *content,
             send_id=send_id,
             **params_values,