chore: Improved docs. Conditions renamed to 'cond' to follow SCXML

Author: fgmacedo

README.rst

@@ -231,10 +231,10 @@ A simple didactic state machine for controlling an ``Order``:
 ...
 ...     add_to_order = waiting_for_payment.to(waiting_for_payment)
 ...     receive_payment = (
-...         waiting_for_payment.to(processing, conditions="payments_enough")
+...         waiting_for_payment.to(processing, cond="payments_enough")
 ...         | waiting_for_payment.to(waiting_for_payment, unless="payments_enough")
 ...     )
-...     process_order = processing.to(shipping, conditions="payment_received")
+...     process_order = processing.to(shipping, cond="payment_received")
 ...     ship_order = shipping.to(completed)
 ...
 ...     def __init__(self):

docs/actions.md

@@ -44,8 +44,6 @@ For each event, you can register `before_<event>` and `after_<event>`
 - `after_<event>(event_data)`
 
 
-(validators-and-guards)=
-
 ## Other callbacks
 
 In addition to {ref}`actions`, you can specify {ref}`validators-and-guards` that are checked
@@ -60,27 +58,32 @@ See {ref}`guards` and {ref}`validators`.
 
 Actions and Guards will be executed in the following order:
 
-- `validators(event_data)`  (attached to the transition)
+- `validators()`  (attached to the transition)
 
-- `conditions(event_data)`  (attached to the transition)
+- `conditions()`  (attached to the transition)
 
-- `unless(event_data)`  (attached to the transition)
+- `unless()`  (attached to the transition)
 
-- `before_transition(event_data)`
+- `before_transition()`
 
-- `before_<event>(event_data)`
+- `before_<event>()`
 
-- `on_exit_state(event_data)`
+- `on_exit_state()`
 
-- `on_exit_<state_identifier>(event_data)`
+- `on_exit_<state_identifier>()`
 
-- `on_enter_state(event_data)`
+- `on_transition()`
 
-- `on_enter_<state_identifier>(event_data)`
+- `on_<event>()`
 
-- `after_<event>(event_data)`
+- `on_enter_state()`
+
+- `on_enter_<state_identifier>()`
+
+- `after_<event>()`
+
+- `after_transition()`
 
-- `after_transition(event_data)`
 
 
 (dynamic-dispatch)=
@@ -90,8 +93,8 @@ python-statemachine implements a custom dispatch mechanism on all those availabl
 Guards, this means that you can declare an arbitrary number of `*args` and `**kwargs`, and the
 library will match your method signature of what's expect to receive with the provided arguments.
 
-This means that if on your `on_enter_<state>()` or `on_execute_<event>()` method, you also
-need to know the `source` ({ref}`state`), or the `event` ({ref}`event`), or access a keyword
+This means that if on your `on_enter_<state>()` or `on_execute_<event>()` method, you need to know
+the `source` ({ref}`state`), or the `event` ({ref}`event`), or access a keyword
 argument passed with the trigger, just add this parameter to the method and It will be passed
 by the dispatch mechanics.
 
@@ -116,7 +119,8 @@ For your convenience, all these parameters are available for you on any Action o
 
 - `transition`: The {ref}`Transition` instance that was activated by the {ref}`Event`.
 
-So, you can implement Actions and Guards like these, but this list is not exaustive, it's only to give you a few examples...  any combination of parameters will work, including extra parameters
+So, you can implement Actions and Guards like these, but this list is not exaustive, it's only
+to give you a few examples...  any combination of parameters will work, including extra parameters
 that you may inform when triggering an {ref}`event`:
 
 ```py

docs/auto_examples/all_actions_machine.ipynb

@@ -26,7 +26,7 @@
       },
       "outputs": [],
       "source": [
-        "import mock\n\nfrom statemachine import StateMachine, State\n\n\nclass AllActionsMachine(StateMachine):\n\n    initial = State(\"Initial\", initial=True)\n    final = State(\"Final\", final=True)\n\n    go = initial.to(\n        final,\n        validators=[\"validation_1\", \"validation_2\"],\n        conditions=[\"condition_1\", \"condition_2\"],\n        unless=[\"unless_1\", \"unless_2\"],\n        on_execute=[\"on_execute_1\", \"on_execute_2\"],\n        before=[\"before_go_inline_1\", \"before_go_inline_2\"],\n        after=[\"after_go_inline_1\", \"after_go_inline_2\"],\n    )\n\n    def __init__(self, *args, **kwargs):\n        self.spy = mock.Mock(side_effect=lambda x: x)\n        super(AllActionsMachine, self).__init__(*args, **kwargs)\n\n    # validations and conditions\n\n    def validation_1(self):\n        # this method may raise an exception\n        return self.spy(\"validation_1\")\n\n    def validation_2(self):\n        # this method may raise an exception\n        return self.spy(\"validation_2\")\n\n    def condition_1(self):\n        self.spy(\"condition_1\")\n        return True\n\n    def condition_2(self):\n        self.spy(\"condition_2\")\n        return True\n\n    def unless_1(self):\n        self.spy(\"unless_1\")\n        return False\n\n    def unless_2(self):\n        self.spy(\"unless_2\")\n        return False\n\n    # generics state\n\n    def on_enter_state(self):\n        return self.spy(\"on_enter_state\")\n\n    def on_exit_state(self):\n        return self.spy(\"on_exit_state\")\n\n    # generics transition\n\n    def before_transition(self):\n        return self.spy(\"before_transition\")\n\n    def after_transition(self):\n        return self.spy(\"after_transition\")\n\n    # before / after specific\n\n    def on_execute_1(self):\n        return self.spy(\"on_execute_1\")\n\n    def on_execute_2(self):\n        return self.spy(\"on_execute_2\")\n\n    def before_go_inline_1(self):\n        return self.spy(\"before_go_inline_1\")\n\n    def before_go_inline_2(self):\n        return self.spy(\"before_go_inline_2\")\n\n    def before_go(self):\n        return self.spy(\"before_go\")\n\n    def on_go(self):\n        return self.spy(\"on_go\")\n\n    def after_go_inline_1(self):\n        return self.spy(\"after_go_inline_1\")\n\n    def after_go_inline_2(self):\n        return self.spy(\"after_go_inline_2\")\n\n    def after_go(self):\n        return self.spy(\"after_go\")\n\n    # enter / exit specific\n\n    def on_enter_initial(self):\n        return self.spy(\"on_enter_initial\")\n\n    def on_exit_initial(self):\n        return self.spy(\"on_exit_initial\")\n\n    def on_enter_final(self):\n        return self.spy(\"on_enter_final\")\n\n    def on_exit_final(self):\n        \"hopefully this will not be called\"\n        return self.spy(\"on_exit_final\")"
+        "import mock\n\nfrom statemachine import StateMachine, State\n\n\nclass AllActionsMachine(StateMachine):\n\n    initial = State(\"Initial\", initial=True)\n    final = State(\"Final\", final=True)\n\n    go = initial.to(\n        final,\n        validators=[\"validation_1\", \"validation_2\"],\n        cond=[\"condition_1\", \"condition_2\"],\n        unless=[\"unless_1\", \"unless_2\"],\n        on_execute=[\"on_execute_1\", \"on_execute_2\"],\n        before=[\"before_go_inline_1\", \"before_go_inline_2\"],\n        after=[\"after_go_inline_1\", \"after_go_inline_2\"],\n    )\n\n    def __init__(self, *args, **kwargs):\n        self.spy = mock.Mock(side_effect=lambda x: x)\n        super(AllActionsMachine, self).__init__(*args, **kwargs)\n\n    # validators and guards\n\n    def validation_1(self):\n        # this method may raise an exception\n        return self.spy(\"validation_1\")\n\n    def validation_2(self):\n        # this method may raise an exception\n        return self.spy(\"validation_2\")\n\n    def condition_1(self):\n        self.spy(\"condition_1\")\n        return True\n\n    def condition_2(self):\n        self.spy(\"condition_2\")\n        return True\n\n    def unless_1(self):\n        self.spy(\"unless_1\")\n        return False\n\n    def unless_2(self):\n        self.spy(\"unless_2\")\n        return False\n\n    # generics state\n\n    def on_enter_state(self):\n        return self.spy(\"on_enter_state\")\n\n    def on_exit_state(self):\n        return self.spy(\"on_exit_state\")\n\n    # generics transition\n\n    def before_transition(self):\n        return self.spy(\"before_transition\")\n\n    def on_transition(self):\n        return self.spy(\"on_transition\")\n\n    def after_transition(self):\n        return self.spy(\"after_transition\")\n\n    # before / after specific\n\n    def before_go_inline_1(self):\n        return self.spy(\"before_go_inline_1\")\n\n    def before_go_inline_2(self):\n        return self.spy(\"before_go_inline_2\")\n\n    def before_go(self):\n        return self.spy(\"before_go\")\n\n    def on_execute_1(self):\n        return self.spy(\"on_execute_1\")\n\n    def on_execute_2(self):\n        return self.spy(\"on_execute_2\")\n\n    def on_go(self):\n        return self.spy(\"on_go\")\n\n    def after_go_inline_1(self):\n        return self.spy(\"after_go_inline_1\")\n\n    def after_go_inline_2(self):\n        return self.spy(\"after_go_inline_2\")\n\n    def after_go(self):\n        return self.spy(\"after_go\")\n\n    # enter / exit specific\n\n    def on_enter_initial(self):\n        return self.spy(\"on_enter_initial\")\n\n    def on_exit_initial(self):\n        return self.spy(\"on_exit_initial\")\n\n    def on_enter_final(self):\n        return self.spy(\"on_enter_final\")\n\n    def on_exit_final(self):\n        \"hopefully this will not be called\"\n        return self.spy(\"on_exit_final\")"
       ]
     },
     {
@@ -51,7 +51,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "Only before actions have their result collected.\n\n"
+        "Only before/on actions have their result collected.\n\n"
       ]
     },
     {
@@ -62,7 +62,7 @@
       },
       "outputs": [],
       "source": [
-        "result = machine.go()\nassert result == [\n    \"before_transition\",\n    \"before_go_inline_1\",\n    \"before_go_inline_2\",\n    \"on_execute_1\",\n    \"on_execute_2\",\n    \"before_go\",\n    \"on_go\",\n]"
+        "result = machine.go()\nassert result == [\n    \"before_transition\",\n    \"before_go_inline_1\",\n    \"before_go_inline_2\",\n    \"before_go\",\n    \"on_transition\",\n    \"on_execute_1\",\n    \"on_execute_2\",\n    \"on_go\",\n]"
       ]
     },
     {
@@ -80,7 +80,7 @@
       },
       "outputs": [],
       "source": [
-        "assert spy.call_args_list == [\n    mock.call(\"on_enter_state\"),\n    mock.call(\"on_enter_initial\"),\n    mock.call(\"validation_1\"),\n    mock.call(\"validation_2\"),\n    mock.call(\"condition_1\"),\n    mock.call(\"condition_2\"),\n    mock.call(\"unless_1\"),\n    mock.call(\"unless_2\"),\n    mock.call(\"before_transition\"),\n    mock.call(\"before_go_inline_1\"),\n    mock.call(\"before_go_inline_2\"),\n    mock.call(\"on_execute_1\"),\n    mock.call(\"on_execute_2\"),\n    mock.call(\"before_go\"),\n    mock.call(\"on_go\"),\n    mock.call(\"on_exit_state\"),\n    mock.call(\"on_exit_initial\"),\n    mock.call(\"on_enter_state\"),\n    mock.call(\"on_enter_final\"),\n    mock.call(\"after_go_inline_1\"),\n    mock.call(\"after_go_inline_2\"),\n    mock.call(\"after_go\"),\n    mock.call(\"after_transition\"),\n]"
+        "assert spy.call_args_list == [\n    mock.call(\"on_enter_state\"),\n    mock.call(\"on_enter_initial\"),\n\n    mock.call(\"validation_1\"),\n    mock.call(\"validation_2\"),\n\n    mock.call(\"condition_1\"),\n    mock.call(\"condition_2\"),\n\n    mock.call(\"unless_1\"),\n    mock.call(\"unless_2\"),\n\n    mock.call(\"before_transition\"),\n    mock.call(\"before_go_inline_1\"),\n    mock.call(\"before_go_inline_2\"),\n    mock.call(\"before_go\"),\n\n    mock.call(\"on_exit_state\"),\n    mock.call(\"on_exit_initial\"),\n\n    mock.call(\"on_transition\"),\n    mock.call(\"on_execute_1\"),\n    mock.call(\"on_execute_2\"),\n    mock.call(\"on_go\"),\n\n    mock.call(\"on_enter_state\"),\n    mock.call(\"on_enter_final\"),\n\n    mock.call(\"after_go_inline_1\"),\n    mock.call(\"after_go_inline_2\"),\n    mock.call(\"after_go\"),\n    mock.call(\"after_transition\"),\n]"
       ]
     }
   ],

docs/auto_examples/all_actions_machine.py

@@ -19,7 +19,7 @@ class AllActionsMachine(StateMachine):
     go = initial.to(
         final,
         validators=["validation_1", "validation_2"],
-        conditions=["condition_1", "condition_2"],
+        cond=["condition_1", "condition_2"],
         unless=["unless_1", "unless_2"],
         on_execute=["on_execute_1", "on_execute_2"],
         before=["before_go_inline_1", "before_go_inline_2"],
@@ -30,7 +30,7 @@ def __init__(self, *args, **kwargs):
         self.spy = mock.Mock(side_effect=lambda x: x)
         super(AllActionsMachine, self).__init__(*args, **kwargs)
 
-    # validations and conditions
+    # validators and guards
 
     def validation_1(self):
         # this method may raise an exception
@@ -69,17 +69,14 @@ def on_exit_state(self):
     def before_transition(self):
         return self.spy("before_transition")
 
+    def on_transition(self):
+        return self.spy("on_transition")
+
     def after_transition(self):
         return self.spy("after_transition")
 
     # before / after specific
 
-    def on_execute_1(self):
-        return self.spy("on_execute_1")
-
-    def on_execute_2(self):
-        return self.spy("on_execute_2")
-
     def before_go_inline_1(self):
         return self.spy("before_go_inline_1")
 
@@ -89,6 +86,12 @@ def before_go_inline_2(self):
     def before_go(self):
         return self.spy("before_go")
 
+    def on_execute_1(self):
+        return self.spy("on_execute_1")
+
+    def on_execute_2(self):
+        return self.spy("on_execute_2")
+
     def on_go(self):
         return self.spy("on_go")
 
@@ -126,16 +129,17 @@ def on_exit_final(self):
 
 
 # %%
-# Only before actions have their result collected.
+# Only before/on actions have their result collected.
 
 result = machine.go()
 assert result == [
     "before_transition",
     "before_go_inline_1",
     "before_go_inline_2",
+    "before_go",
+    "on_transition",
     "on_execute_1",
     "on_execute_2",
-    "before_go",
     "on_go",
 ]
 
@@ -145,23 +149,32 @@ def on_exit_final(self):
 assert spy.call_args_list == [
     mock.call("on_enter_state"),
     mock.call("on_enter_initial"),
+
     mock.call("validation_1"),
     mock.call("validation_2"),
+
     mock.call("condition_1"),
     mock.call("condition_2"),
+
     mock.call("unless_1"),
     mock.call("unless_2"),
+
     mock.call("before_transition"),
     mock.call("before_go_inline_1"),
     mock.call("before_go_inline_2"),
-    mock.call("on_execute_1"),
-    mock.call("on_execute_2"),
     mock.call("before_go"),
-    mock.call("on_go"),
+
     mock.call("on_exit_state"),
     mock.call("on_exit_initial"),
+
+    mock.call("on_transition"),
+    mock.call("on_execute_1"),
+    mock.call("on_execute_2"),
+    mock.call("on_go"),
+
     mock.call("on_enter_state"),
     mock.call("on_enter_final"),
+
     mock.call("after_go_inline_1"),
     mock.call("after_go_inline_2"),
     mock.call("after_go"),

docs/auto_examples/all_actions_machine.py.md5

@@ -1 +1 @@
-7979f9d577527eade21568387d8b23c5
+ff6a3215a488de0dcf9626396f8640c4

docs/auto_examples/all_actions_machine.rst

@@ -23,7 +23,7 @@ All actions machine
 
 A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
 
-.. GENERATED FROM PYTHON SOURCE LINES 8-120
+.. GENERATED FROM PYTHON SOURCE LINES 8-123
 
 .. code-block:: default
 
@@ -41,7 +41,7 @@ A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
         go = initial.to(
             final,
             validators=["validation_1", "validation_2"],
-            conditions=["condition_1", "condition_2"],
+            cond=["condition_1", "condition_2"],
             unless=["unless_1", "unless_2"],
             on_execute=["on_execute_1", "on_execute_2"],
             before=["before_go_inline_1", "before_go_inline_2"],
@@ -52,7 +52,7 @@ A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
             self.spy = mock.Mock(side_effect=lambda x: x)
             super(AllActionsMachine, self).__init__(*args, **kwargs)
 
-        # validations and conditions
+        # validators and guards
 
         def validation_1(self):
             # this method may raise an exception
@@ -91,17 +91,14 @@ A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
         def before_transition(self):
             return self.spy("before_transition")
 
+        def on_transition(self):
+            return self.spy("on_transition")
+
         def after_transition(self):
             return self.spy("after_transition")
 
         # before / after specific
 
-        def on_execute_1(self):
-            return self.spy("on_execute_1")
-
-        def on_execute_2(self):
-            return self.spy("on_execute_2")
-
         def before_go_inline_1(self):
             return self.spy("before_go_inline_1")
 
@@ -111,6 +108,12 @@ A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
         def before_go(self):
             return self.spy("before_go")
 
+        def on_execute_1(self):
+            return self.spy("on_execute_1")
+
+        def on_execute_2(self):
+            return self.spy("on_execute_2")
+
         def on_go(self):
             return self.spy("on_go")
 
@@ -151,12 +154,12 @@ A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
 
 
 
-.. GENERATED FROM PYTHON SOURCE LINES 121-123
+.. GENERATED FROM PYTHON SOURCE LINES 124-126
 
 Testing
 -------
 
-.. GENERATED FROM PYTHON SOURCE LINES 123-128
+.. GENERATED FROM PYTHON SOURCE LINES 126-131
 
 .. code-block:: default
 
@@ -172,11 +175,11 @@ Testing
 
 
 
-.. GENERATED FROM PYTHON SOURCE LINES 129-130
+.. GENERATED FROM PYTHON SOURCE LINES 132-133
 
-Only before actions have their result collected.
+Only before/on actions have their result collected.
 
-.. GENERATED FROM PYTHON SOURCE LINES 130-142
+.. GENERATED FROM PYTHON SOURCE LINES 133-146
 
 .. code-block:: default
 
@@ -186,9 +189,10 @@ Only before actions have their result collected.
         "before_transition",
         "before_go_inline_1",
         "before_go_inline_2",
+        "before_go",
+        "on_transition",
         "on_execute_1",
         "on_execute_2",
-        "before_go",
         "on_go",
     ]
 
@@ -199,35 +203,44 @@ Only before actions have their result collected.
 
 
 
-.. GENERATED FROM PYTHON SOURCE LINES 143-144
+.. GENERATED FROM PYTHON SOURCE LINES 147-148
 
 Checking the method resolution order
 
-.. GENERATED FROM PYTHON SOURCE LINES 144-170
+.. GENERATED FROM PYTHON SOURCE LINES 148-183
 
 .. code-block:: default
 
 
     assert spy.call_args_list == [
         mock.call("on_enter_state"),
         mock.call("on_enter_initial"),
+
         mock.call("validation_1"),
         mock.call("validation_2"),
+
         mock.call("condition_1"),
         mock.call("condition_2"),
+
         mock.call("unless_1"),
         mock.call("unless_2"),
+
         mock.call("before_transition"),
         mock.call("before_go_inline_1"),
         mock.call("before_go_inline_2"),
-        mock.call("on_execute_1"),
-        mock.call("on_execute_2"),
         mock.call("before_go"),
-        mock.call("on_go"),
+
         mock.call("on_exit_state"),
         mock.call("on_exit_initial"),
+
+        mock.call("on_transition"),
+        mock.call("on_execute_1"),
+        mock.call("on_execute_2"),
+        mock.call("on_go"),
+
         mock.call("on_enter_state"),
         mock.call("on_enter_final"),
+
         mock.call("after_go_inline_1"),
         mock.call("after_go_inline_2"),
         mock.call("after_go"),