feat: Examples gallery; Deprecating 'State.identifier' (#303)

Author: fgmacedo

CONTRIBUTING.rst

@@ -76,17 +76,39 @@ Ready to contribute? Here's how to set up `python-statemachine` for local develo
 
    Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
+5. When you're done making changes, check that your changes pass flake8 and the tests, including
+   testing other Python versions with tox::
 
     $ flake8 statemachine tests
-    $ python setup.py test or py.test
+    $ py.test
     $ tox
 
    To get flake8 and tox, just pip install them into your virtualenv.
 
+6. To build the documentation locally, run::
+
+    $ sphinx-build docs docs/_build/html
+
+   Now you can serve the local documentation using a webserver, like the built-in included
+   with python::
+
+    $ python -m http.server --directory docs/_build/html
+
+   And access your browser at http://localhost:8000/
+
+   If you're specially writting documentation, I strongly recommend using ``sphinx-autobuild``
+   as it improves the workflow watching for file changes and with live reloading::
+
+    $ sphinx-autobuild docs docs/_build/html --re-ignore "auto_examples/.*"
+
+   Sometimes you need a full fresh of the files being build for docs, you can use::
+
+    $ rm -rf docs/_build/ docs/auto_examples
+
 .. note::
 
-    In order to get the tox working for all versions, I usually run pyenv enabling shell for those versions:
+    In order to get the tox working for all versions, I usually run pyenv enabling shell for
+    those versions::
 
     $ pyenv shell 3.8.1/envs/python-statemachine 3.7.6 3.6.10 3.5.9 2.7.17
 

README.rst

@@ -88,8 +88,8 @@ Define your state machine:
 ...         message = ". " + message if message else ""
 ...         return "Running {} from {} to {}{}".format(
 ...             event_data.event,
-...             event_data.transition.source.identifier,
-...             event_data.transition.destination.identifier,
+...             event_data.transition.source.id,
+...             event_data.transition.destination.id,
 ...             message,
 ...         )
 ...
@@ -111,13 +111,13 @@ Then start sending events:
 
 You can inspect about the current state:
 
->>> traffic_light.current_state.identifier
+>>> traffic_light.current_state.id
 'yellow'
 
 Or get a complete state repr for debugging purposes:
 
 >>> traffic_light.current_state
-State('Yellow', identifier='yellow', value='yellow', initial=False, final=False)
+State('Yellow', id='yellow', value='yellow', initial=False, final=False)
 
 The ``State`` instance can also be checked by equality:
 
@@ -127,7 +127,7 @@ True
 >>> traffic_light.current_state == traffic_light.yellow
 True
 
-But for your convenience, a dynamically property ``is_<state.identifier>`` is created for each state,
+But for your convenience, a dynamically property ``is_<state.id>`` is created for each state,
 so you can easily check if a machine is at a specific state at any time:
 
 >>> traffic_light.is_green
@@ -141,7 +141,7 @@ False
 
 Easily iterate over all states:
 
->>> [s.identifier for s in traffic_light.states]
+>>> [s.id for s in traffic_light.states]
 ['green', 'red', 'yellow']
 
 Or over events:
@@ -276,7 +276,7 @@ You can use this machine as follows.
 >>> control.receive_payment(4)
 [4]
 
->>> control.current_state.identifier
+>>> control.current_state.id
 'waiting_for_payment'
 
 >>> control.process_order()
@@ -287,7 +287,7 @@ statemachine.exceptions.TransitionNotAllowed: Can't process_order when in Waitin
 >>> control.receive_payment(6)
 [4, 6]
 
->>> control.current_state.identifier
+>>> control.current_state.id
 'processing'
 
 >>> control.process_order()

docs/_static/custom_machine.css

@@ -0,0 +1,57 @@
+/* div.sphx-glr-download {
+    height: 0px;
+    visibility: hidden;
+} */
+
+.sphx-glr-thumbnails {
+    grid-template-columns: repeat(auto-fill, minmax(600px, 1fr)) !important;
+}
+
+.sphx-glr-thumbcontainer {
+    min-height: 320px !important;
+    margin: 20px !important;
+    justify-content: center;
+}
+.sphx-glr-thumbcontainer .figure {
+    width: 600px !important;
+}
+.sphx-glr-thumbcontainer img {
+    max-height: 250px !important;
+    max-width: 600px !important;
+    width: 100% !important;
+}
+.sphx-glr-thumbcontainer a.internal {
+    padding: 20px 10px 0 !important;
+}
+
+
+/* Gallery Donwload buttons */
+div.sphx-glr-download a {
+    color: #404040 !important;
+    background-color: #f3f6f6 !important;
+    background-image: none;
+    border-radius: 4px;
+    border: none;
+    color: #404040 !important;
+    display: inline-block;
+    font-weight: bold;
+    padding: 1ex;
+    text-align: center;
+  }
+
+  div.sphx-glr-download code.download {
+    display: inline-block;
+    white-space: normal;
+    word-break: normal;
+    overflow-wrap: break-word;
+    /* border and background are given by the enclosing 'a' */
+    border: none;
+    background: none;
+  }
+
+  div.sphx-glr-download a:hover {
+    box-shadow: none;
+    text-decoration: none;
+    background-image: none;
+    background-color: #e5ebeb !important;
+  }

docs/auto_examples/all_actions_machine.ipynb

@@ -0,0 +1,54 @@
+{
+  "cells": [
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "%matplotlib inline"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# All actions machine\n\nA StateMachine that exercices all possible `Actions` and `Guards`.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "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\")"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.8.1"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

docs/auto_examples/all_actions_machine.py

@@ -0,0 +1,117 @@
+"""
+All actions machine
+-------------------
+
+A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
+
+"""
+
+import mock
+
+from statemachine import StateMachine, State
+
+
+class AllActionsMachine(StateMachine):
+
+    initial = State("Initial", initial=True)
+    final = State("Final", final=True)
+
+    go = initial.to(
+        final,
+        validators=["validation_1", "validation_2"],
+        conditions=["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"],
+        after=["after_go_inline_1", "after_go_inline_2"],
+    )
+
+    def __init__(self, *args, **kwargs):
+        self.spy = mock.Mock(side_effect=lambda x: x)
+        super(AllActionsMachine, self).__init__(*args, **kwargs)
+
+    # validations and conditions
+
+    def validation_1(self):
+        # this method may raise an exception
+        return self.spy("validation_1")
+
+    def validation_2(self):
+        # this method may raise an exception
+        return self.spy("validation_2")
+
+    def condition_1(self):
+        self.spy("condition_1")
+        return True
+
+    def condition_2(self):
+        self.spy("condition_2")
+        return True
+
+    def unless_1(self):
+        self.spy("unless_1")
+        return False
+
+    def unless_2(self):
+        self.spy("unless_2")
+        return False
+
+    # generics state
+
+    def on_enter_state(self):
+        return self.spy("on_enter_state")
+
+    def on_exit_state(self):
+        return self.spy("on_exit_state")
+
+    # generics transition
+
+    def before_transition(self):
+        return self.spy("before_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")
+
+    def before_go_inline_2(self):
+        return self.spy("before_go_inline_2")
+
+    def before_go(self):
+        return self.spy("before_go")
+
+    def on_go(self):
+        return self.spy("on_go")
+
+    def after_go_inline_1(self):
+        return self.spy("after_go_inline_1")
+
+    def after_go_inline_2(self):
+        return self.spy("after_go_inline_2")
+
+    def after_go(self):
+        return self.spy("after_go")
+
+    # enter / exit specific
+
+    def on_enter_initial(self):
+        return self.spy("on_enter_initial")
+
+    def on_exit_initial(self):
+        return self.spy("on_exit_initial")
+
+    def on_enter_final(self):
+        return self.spy("on_enter_final")
+
+    def on_exit_final(self):
+        "hopefully this will not be called"
+        return self.spy("on_exit_final")

docs/auto_examples/all_actions_machine.py.md5

@@ -0,0 +1 @@
+2132b4efc59380ceee5e938f475144a6