feat: Improved dispatcher of methods, now with protected attributes; Example with rich models. (#305)

Author: fgmacedo

AUTHORS.rst

@@ -15,8 +15,8 @@ Contributors
 * Raphael Schrader <raphael@schradercloud.de>
 
 
-Credits
--------
+Scaffolding
+-----------
 
 This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
 

docs/actions.md

@@ -1,5 +1,3 @@
-(actions)=
-
 # Actions
 
 
@@ -34,6 +32,9 @@ For each defined state, you can register `on_enter_<state>` and `on_exit_<state>
 
 - `on_exit_<state_identifier>(event_data)`
 
+
+The initial {ref}`state` is entered when the machine starts and the corresponding actions `on_enter_state` or `on_enter_<state>` are called if defined.
+
 ## Event actions
 
 For each event, you can register `before_<event>` and `after_<event>`
@@ -82,12 +83,17 @@ Actions and Guards will be executed in the following order:
 - `after_transition(event_data)`
 
 
+(dynamic-dispatch)=
 ## Dynamic dispatch
 
 python-statemachine implements a custom dispatch mechanism on all those available Actions and
 Guards, this means that you can declare an arbitrary number of `*args` and `**kwargs`, and the
-library will to it's best to match your method signature of what's expect to receive with the
-provided arguments.
+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
+argument passed with the trigger, just add this parameter to the method and It will be passed
+by the dispatch mechanics.
 
 In other words, if you implement a method to handle an event and don't declare any parameter,
 you'll be fine, if you declare an expected parameter, you'll also be covered.
@@ -110,7 +116,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:
+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
 def action_or_guard_method_name(self):
@@ -127,12 +134,7 @@ def action_or_guard_method_name(self, *args, event_data, event, source, state, m
 
 ```
 
-
-## Example
-
-See this test for a complete example of order resolution of callbacks.
-
-```{literalinclude} ../tests/test_actions.py
-:language: python
-:linenos:
+```{seealso}
+See the example {ref}`sphx_glr_auto_examples_all_actions_machine.py` for a complete example of
+order resolution of callbacks.
 ```

docs/api.rst

@@ -28,6 +28,60 @@
       "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\")"
       ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Testing\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "machine = AllActionsMachine()\nspy = machine.spy"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Only before actions have their result collected.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "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]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Checking the method resolution order\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "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]"
+      ]
     }
   ],
   "metadata": {

docs/auto_examples/all_actions_machine.ipynb

@@ -115,3 +115,55 @@ def on_enter_final(self):
     def on_exit_final(self):
         "hopefully this will not be called"
         return self.spy("on_exit_final")
+
+
+# %%
+# Testing
+# -------
+
+machine = AllActionsMachine()
+spy = machine.spy
+
+
+# %%
+# Only before actions have their result collected.
+
+result = machine.go()
+assert result == [
+    "before_transition",
+    "before_go_inline_1",
+    "before_go_inline_2",
+    "on_execute_1",
+    "on_execute_2",
+    "before_go",
+    "on_go",
+]
+
+# %%
+# Checking the method resolution order
+
+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_enter_state"),
+    mock.call("on_enter_final"),
+    mock.call("after_go_inline_1"),
+    mock.call("after_go_inline_2"),
+    mock.call("after_go"),
+    mock.call("after_transition"),
+]

docs/auto_examples/all_actions_machine.py

@@ -1 +1 @@
-2132b4efc59380ceee5e938f475144a6
+1c02de6db5c0a074eb68328c9fdef075

docs/auto_examples/all_actions_machine.py.md5

@@ -23,18 +23,7 @@ All actions machine
 
 A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
 
-.. GENERATED FROM PYTHON SOURCE LINES 8-118
-
-
-
-.. image-sg:: /auto_examples/images/sphx_glr_all_actions_machine_001.svg
-   :alt: all actions machine
-   :srcset: /auto_examples/images/sphx_glr_all_actions_machine_001.svg
-   :class: sphx-glr-single-img
-
-
-
-
+.. GENERATED FROM PYTHON SOURCE LINES 8-120
 
 .. code-block:: default
 
@@ -150,6 +139,108 @@ A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
             return self.spy("on_exit_final")
 
 
+
+
+
+.. image-sg:: /auto_examples/images/sphx_glr_all_actions_machine_001.svg
+   :alt: all actions machine
+   :srcset: /auto_examples/images/sphx_glr_all_actions_machine_001.svg
+   :class: sphx-glr-single-img
+
+
+
+
+
+.. GENERATED FROM PYTHON SOURCE LINES 121-123
+
+Testing
+-------
+
+.. GENERATED FROM PYTHON SOURCE LINES 123-128
+
+.. code-block:: default
+
+
+    machine = AllActionsMachine()
+    spy = machine.spy
+
+
+
+
+
+
+
+
+
+.. GENERATED FROM PYTHON SOURCE LINES 129-130
+
+Only before actions have their result collected.
+
+.. GENERATED FROM PYTHON SOURCE LINES 130-142
+
+.. code-block:: default
+
+
+    result = machine.go()
+    assert result == [
+        "before_transition",
+        "before_go_inline_1",
+        "before_go_inline_2",
+        "on_execute_1",
+        "on_execute_2",
+        "before_go",
+        "on_go",
+    ]
+
+
+
+
+
+
+
+
+.. GENERATED FROM PYTHON SOURCE LINES 143-144
+
+Checking the method resolution order
+
+.. GENERATED FROM PYTHON SOURCE LINES 144-170
+
+.. 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_enter_state"),
+        mock.call("on_enter_final"),
+        mock.call("after_go_inline_1"),
+        mock.call("after_go_inline_2"),
+        mock.call("after_go"),
+        mock.call("after_transition"),
+    ]
+
+
+
+
+
+
+
+
 .. _sphx_glr_download_auto_examples_all_actions_machine.py:
 
 .. only:: html