feat!: change States.from_enum default to use_enum_instance=True

Fulfills the deprecation promise from v2.3.3. The enum instance is now
used as the state value by default. Pass use_enum_instance=False to get
the previous behavior of using the raw enum value.

Author: fgmacedo

statemachine/states.py

@@ -83,7 +83,7 @@ def items(self):
         return self._states.items()
 
     @classmethod
-    def from_enum(cls, enum_type: EnumType, initial, final=None, use_enum_instance: bool = False):
+    def from_enum(cls, enum_type: EnumType, initial, final=None, use_enum_instance: bool = True):
         """
         Creates a new instance of the ``States`` class from an enumeration.
 
@@ -93,10 +93,10 @@ def from_enum(cls, enum_type: EnumType, initial, final=None, use_enum_instance:
         ...     pending = 1
         ...     completed = 2
 
-        A :ref:`StateMachine` that uses this enum can be declared as follows:
+        A :ref:`StateChart` that uses this enum can be declared as follows:
 
-        >>> from statemachine import StateMachine
-        >>> class ApprovalMachine(StateMachine):
+        >>> from statemachine import StateChart
+        >>> class ApprovalMachine(StateChart):
         ...
         ...     _ = States.from_enum(Status, initial=Status.pending, final=Status.completed)
         ...
@@ -107,7 +107,7 @@ def from_enum(cls, enum_type: EnumType, initial, final=None, use_enum_instance:
 
         .. tip::
             When you assign the result of ``States.from_enum`` to a class-level variable in your
-            :ref:`StateMachine`, you're all set. You can use any name for this variable. In this
+            :ref:`StateChart`, you're all set. You can use any name for this variable. In this
             example, we used ``_`` to show that the name doesn't matter. The metaclass will inspect
             the variable of type :ref:`States (class)` and automatically assign the inner
             :ref:`State` instances to the state machine.
@@ -128,25 +128,25 @@ def from_enum(cls, enum_type: EnumType, initial, final=None, use_enum_instance:
         True
 
         >>> sm.current_state_value
-        2
+        <Status.completed: 2>
 
-        If you need to use the enum instance as the state value, you can set the
-        ``use_enum_instance=True``:
+        If you need to use the raw enum value instead of the enum instance, you can set
+        ``use_enum_instance=False``:
 
-        >>> states = States.from_enum(Status, initial=Status.pending, use_enum_instance=True)
+        >>> states = States.from_enum(Status, initial=Status.pending, use_enum_instance=False)
         >>> states.completed.value
-        <Status.completed: 2>
+        2
 
-        .. deprecated:: 2.3.3
+        .. versionchanged:: 3.0.0
 
-            On the next major release, ``use_enum_instance=True`` will be the default.
+            The default changed from ``False`` to ``True``.
 
         Args:
             enum_type: An enumeration containing the states of the machine.
             initial: The initial state of the machine.
             final: A set of final states of the machine.
             use_enum_instance: If ``True``, the value of the state will be the enum item instance,
-                otherwise the enum item value. Defaults to ``False``.
+                otherwise the enum item value. Defaults to ``True``.
 
         Returns:
             A new instance of the :ref:`States (class)`.

tests/examples/enum_campaign_machine.py

@@ -27,7 +27,6 @@ class CampaignMachine(StateChart):
         CampaignStatus,
         initial=CampaignStatus.DRAFT,
         final=CampaignStatus.CLOSED,
-        use_enum_instance=True,
     )
 
     add_job = states.DRAFT.to(states.DRAFT) | states.PRODUCING.to(states.PRODUCING)