feat: State.name is now optional (#354)

Author: fgmacedo

README.md

@@ -55,9 +55,9 @@ Define your state machine:
 
 >>> class TrafficLightMachine(StateMachine):
 ...     "A traffic light machine"
-...     green = State("Green", initial=True)
-...     yellow = State("Yellow")
-...     red = State("Red")
+...     green = State(initial=True)
+...     yellow = State()
+...     red = State()
 ...
 ...     cycle = green.to(yellow) | yellow.to(red) | red.to(green)
 ...
@@ -100,6 +100,14 @@ You can inspect the current state:
 
 ```
 
+A `State` human-readable name is automatically derived from the `State.id`:
+
+```py
+>>> traffic_light.current_state.name
+'Yellow'
+
+```
+
 Or get a complete state representation for debugging purposes:
 
 ```py
@@ -199,10 +207,10 @@ A simple didactic state machine for controlling an `Order`:
 
 ```py
 >>> class OrderControl(StateMachine):
-...     waiting_for_payment = State("Waiting for payment", initial=True)
-...     processing = State("Processing")
-...     shipping = State("Shipping")
-...     completed = State("Completed", final=True)
+...     waiting_for_payment = State(initial=True)
+...     processing = State()
+...     shipping = State()
+...     completed = State(final=True)
 ...
 ...     add_to_order = waiting_for_payment.to(waiting_for_payment)
 ...     receive_payment = (
@@ -254,6 +262,9 @@ You can use this machine as follows.
 >>> control.current_state.id
 'waiting_for_payment'
 
+>>> control.current_state.name
+'Waiting for payment'
+
 >>> control.process_order()
 Traceback (most recent call last):
 ...

docs/actions.md

@@ -32,8 +32,8 @@ The follow example can get you an overview of the "generic" callbacks available:
 >>> from statemachine import StateMachine, State
 
 >>> class ExampleStateMachine(StateMachine):
-...     initial = State("Initial", initial=True)
-...     final = State("Final", final=True)
+...     initial = State(initial=True)
+...     final = State(final=True)
 ...
 ...     loop = initial.to.itself()
 ...     go = initial.to(final)
@@ -101,7 +101,7 @@ model, using the patterns:
 >>> from statemachine import StateMachine, State
 
 >>> class ExampleStateMachine(StateMachine):
-...     initial = State("Initial", initial=True)
+...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself()
 ...
@@ -121,7 +121,7 @@ Use the `enter` or `exit` params available on the `State` constructor.
 >>> from statemachine import StateMachine, State
 
 >>> class ExampleStateMachine(StateMachine):
-...     initial = State("Initial", initial=True, enter="entering_initial", exit="leaving_initial")
+...     initial = State(initial=True, enter="entering_initial", exit="leaving_initial")
 ...
 ...     loop = initial.to.itself()
 ...
@@ -140,7 +140,7 @@ Use the `enter` or `exit` params available on the `State` constructor.
 >>> from statemachine import StateMachine, State
 
 >>> class ExampleStateMachine(StateMachine):
-...     initial = State("Initial", initial=True)
+...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself()
 ...
@@ -176,7 +176,7 @@ model, using the patterns:
 >>> from statemachine import StateMachine, State
 
 >>> class ExampleStateMachine(StateMachine):
-...     initial = State("Initial", initial=True)
+...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself()
 ...
@@ -198,7 +198,7 @@ model, using the patterns:
 >>> from statemachine import StateMachine, State
 
 >>> class ExampleStateMachine(StateMachine):
-...     initial = State("Initial", initial=True)
+...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself(before="just_before", on="its_happening", after="loop_completed")
 ...
@@ -222,7 +222,7 @@ The action will be registered for every {ref}`transition` associated with the ev
 >>> from statemachine import StateMachine, State
 
 >>> class ExampleStateMachine(StateMachine):
-...     initial = State("Initial", initial=True)
+...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself()
 ...
@@ -256,7 +256,7 @@ You can also declare an event while also adding a callback:
 >>> from statemachine import StateMachine, State
 
 >>> class ExampleStateMachine(StateMachine):
-...     initial = State("Initial", initial=True)
+...     initial = State(initial=True)
 ...
 ...     @initial.to.itself()
 ...     def loop(self):

docs/guards.md

@@ -81,9 +81,9 @@ Consider this example:
 ```py
 
 class InvoiceStateMachine(StateMachine):
-    unpaid = State("unpaid", initial=True)
-    paid = State("paid")
-    failed = State("failed")
+    unpaid = State(initial=True)
+    paid = State()
+    failed = State()
 
     paused = False
     offer_valid = True

docs/images/test_state_machine_internal.png

@@ -18,6 +18,33 @@ StateMachine 2.0 supports Python 3.7, 3.8, 3.9, 3.10, and 3.11.
 
 ## What's new in 2.0
 
+### State names are now optional
+
+{ref}`State` names are now by default derived from the class variable that they are assigned to. You can keep declaring explicit names, but we encourage you to only assign a name
+when it is different than the one derived from its id.
+
+```py
+>>> from statemachine import StateMachine, State
+
+>>> class SM(StateMachine):
+...     pending = State(initial=True)
+...     waiting_approval = State()
+...     approved = State(final=True)
+...
+...     start = pending.to(waiting_approval)
+...     approve = waiting_approval.to(approved)
+...
+
+>>> SM.pending.name
+'Pending'
+
+>>> SM.waiting_approval.name
+'Waiting approval'
+
+>>> SM.approved.name
+'Approved'
+
+```
 
 ### Added support for internal transitions
 
@@ -28,7 +55,7 @@ are ever executed as a result of an internal transition.
 >>> from statemachine import StateMachine, State
 
 >>> class TestStateMachine(StateMachine):
-...     initial = State("initial", initial=True)
+...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself(internal=True)
 

docs/releases/2.0.0.md

@@ -10,7 +10,7 @@ with advance notice in the **Deprecations** section of releases.
 
 Below are release notes through StateMachine and its patch releases.
 
-###  2.0 release
+###  2.0 releases
 
 ```{toctree}
 :maxdepth: 1
@@ -20,7 +20,7 @@ Below are release notes through StateMachine and its patch releases.
 ```
 
 
-###  1.0 release
+###  1.0 releases
 
 This is the last release series to support Python 2.X series.
 
@@ -34,7 +34,7 @@ This is the last release series to support Python 2.X series.
 
 ```
 
-###  0.* release
+###  0.* releases
 
 ```{toctree}
 :maxdepth: 1

docs/releases/index.md

@@ -107,7 +107,7 @@ Example:
 
 ```py
 >>> class TestStateMachine(StateMachine):
-...     initial = State("initial", initial=True)
+...     initial = State(initial=True)
 ...
 ...     external_loop = initial.to.itself(on="do_something")
 ...     internal_loop = initial.to.itself(internal=True, on="do_something")

docs/transitions.md

@@ -114,7 +114,7 @@ def _add_unbounded_callback(cls, attr_name, func):
         for ref in func._callbacks_to_update:
             ref(attr_name)
 
-    def add_state(cls, id, state):
+    def add_state(cls, id, state: State):
         state._set_id(id)
         cls.states.append(state)
         cls.states_map[state.value] = state

statemachine/factory.py

@@ -15,11 +15,16 @@ class State:
     in the way that state describes.
 
     Args:
-        name: An human readable representation of the state.
+        name: A human-readable representation of the state. Default is derived
+            from the name of the variable assigned to the state machine class.
+            The name is derived from the id using this logic::
+
+                name = id.replace("_", " ").capitalize()
+
         value: A specific value to the storage and retrieval of states.
             If specified, you can use It to map a more friendly representation to a low-level
             value.
-        initial: Set `' True`` if the ``State`` is the initial one. There must be one and only
+        initial: Set ``True`` if the ``State`` is the initial one. There must be one and only
             one initial state in a statemachine. Defaults to ``False``.
         final: Set ``True`` if represents a final state. A machine can have
             optionally many final states. Final states have no :ref:`transition` starting from It.
@@ -83,16 +88,21 @@ class State:
     """
 
     def __init__(
-        self, name, value=None, initial=False, final=False, enter=None, exit=None
+        self,
+        name: str = "",
+        value: Any = None,
+        initial: bool = False,
+        final: bool = False,
+        enter: Any = None,
+        exit: Any = None,
     ):
-        # type: (str, Optional[Any], bool, bool, Optional[Any], Optional[Any]) -> None
         self.name = name
         self.value = value
-        self._id = None  # type: Optional[str]
-        self._storage = ""
         self._initial = initial
-        self.transitions = TransitionList()
         self._final = final
+        self._id: str = ""
+        self._storage: str = ""
+        self.transitions = TransitionList()
         self.enter = Callbacks().add(enter)
         self.exit = Callbacks().add(exit)
 
@@ -144,23 +154,25 @@ def clone(self):
         return deepcopy(self)
 
     @property
-    def id(self):
+    def id(self) -> str:
         return self._id
 
-    def _set_id(self, id):
+    def _set_id(self, id: str):
         self._id = id
         self._storage = f"_{id}"
         if self.value is None:
             self.value = id
+        if not self.name:
+            self.name = self._id.replace("_", " ").capitalize()
 
-    def _to_(self, *states, **kwargs):
+    def _to_(self, *states: "State", **kwargs):
         transitions = TransitionList(
             Transition(self, state, **kwargs) for state in states
         )
         self.transitions.add_transitions(transitions)
         return transitions
 
-    def _from_(self, *states, **kwargs):
+    def _from_(self, *states: "State", **kwargs):
         transitions = TransitionList()
         for origin in states:
             transition = Transition(origin, self, **kwargs)
@@ -169,7 +181,7 @@ def _from_(self, *states, **kwargs):
         return transitions
 
     def _get_proxy_method_to_itself(self, method):
-        def proxy(*states, **kwargs):
+        def proxy(*states: "State", **kwargs):
             return method(*states, **kwargs)
 
         def proxy_to_itself(**kwargs):