feat: StateMachine observers (#312)

* feat: StateMachine.add_observer

Author: fgmacedo

README.rst

@@ -307,3 +307,6 @@ True
 >>> control.completed.is_active
 True
 
+
+There's a lot more to cover, please take a look at our docs:
+https://python-statemachine.readthedocs.io.

docs/actions.md

@@ -332,21 +332,34 @@ you'll be fine, if you declare an expected parameter, you'll also be covered.
 
 For your convenience, all these parameters are available for you on any Action or Guard:
 
-- `*args`: All positional arguments provided on the {ref}`Event`.
 
-- `**kwargs`: All keyword arguments provided on the {ref}`Event`.
+`*args`
+: All positional arguments provided on the {ref}`Event`.
 
-- `event_data`: A reference to `EventData` instance.
+`**kwargs`
+: All keyword arguments provided on the {ref}`Event`.
 
-- `event`: The {ref}`Event` that was triggered.
+`event_data`
+: A reference to `EventData` instance.
 
-- `source`: The {ref}`State` the statemachine was when the {ref}`Event` started.
+`event`
+: The {ref}`Event` that was triggered.
 
-- `state`: The current {ref}`State` of the statemachine.
+`source`
+: The {ref}`State` the statemachine was when the {ref}`Event` started.
 
-- `model`: A reference to the underlying model that holds the current {ref}`State`.
+`state`
+: The current {ref}`State` of the statemachine.
+
+`target`
+: The destination {ref}`State` of the transition.
+
+`model`
+: A reference to the underlying model that holds the current {ref}`State`.
+
+`transition`
+: The {ref}`Transition` instance that was activated by the {ref}`Event`.
 
-- `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

docs/index.rst

@@ -12,6 +12,7 @@ Contents:
    transitions
    actions
    guards
+   observers
    mixins
    integrations
    diagram

docs/observers.md

@@ -0,0 +1,49 @@
+
+# Observers
+
+Observers are a way do generically add behavior to a StateMachine without
+changing its internal implementation.
+
+One possible use case is to add an observer that prints a log message when the SM runs a
+transition or enters a new state.
+
+Giving the {ref}`sphx_glr_auto_examples_traffic_light_machine.py` as example:
+
+
+```py
+>>> from tests.examples.traffic_light_machine import TrafficLightMachine
+
+>>> class LogObserver(object):
+...     def __init__(self, name):
+...         self.name = name
+...
+...     def after_transition(self, event, source, target):
+...         print("{} after: {}--({})-->{}".format(self.name, source.id, event, target.id))
+...
+...     def on_enter_state(self, target, event):
+...         print("{} enter: {} from {}".format(self.name, target.id, event))
+
+
+>>> sm = TrafficLightMachine()
+
+>>> sm.add_observer(LogObserver("Paulista Avenue"))  # doctest: +ELLIPSIS
+TrafficLightMachine...
+
+>>> sm.cycle()
+Paulista Avenue enter: yellow from cycle
+Paulista Avenue after: green--(cycle)-->yellow
+'Running cycle from green to yellow'
+
+```
+
+```{hint}
+The `StateMachine` itself is registered as an observer, so by using `.add_observer()` an
+external object can have the same level of functionalities provided to the built-in class.
+```
+
+```{seealso}
+See {ref}`actions`, {ref}`validators-and-guards` for a list of possible callbacks.
+
+And also {ref}`dynamic-dispatch` to know more about how the lib calls methods to match
+their signature.
+```

docs/releases/1.0.0.md

@@ -79,6 +79,18 @@ def action_or_guard_method_name(self, *args, event_data, event, source, state, m
 See {ref}`dynamic-dispatch` for more details.
 ```
 
+### Add observers to a running StateMachine
+
+Observers are a way do generically add behaviour to a StateMachine without
+changing it's internal implementation.
+
+The `StateMachine` itself is registered as an observer, so by using `StateMachine.add_observer()`
+an external object can have the same level of functionalities provided to the built-in class.
+
+```{seealso}
+See {ref}`observers` for more details.
+```
+
 ## Minor features in 1.0
 
 - Fixed mypy complaining about incorrect type for ``StateMachine`` class.

statemachine/callbacks.py

@@ -128,12 +128,14 @@ def clear(self):
     def call(self, *args, **kwargs):
         return [callback(*args, **kwargs) for callback in self.items]
 
-    def _add(self, func, prepend=False, **kwargs):
+    def _add(self, func, resolver=None, prepend=False, **kwargs):
         if func in self.items:
             return
 
+        resolver = resolver or self._resolver
+
         callback = self.factory(func, **kwargs)
-        if self._resolver is not None and not callback.setup(self._resolver):
+        if resolver is not None and not callback.setup(resolver):
             return
 
         if prepend:

statemachine/contrib/diagram.py

@@ -2,7 +2,6 @@
 import pydot
 import importlib
 
-from ..factory import StateMachineMetaclass
 from ..statemachine import BaseStateMachine
 
 
@@ -29,13 +28,10 @@ def __init__(self, machine):
 
     def _get_graph(self):
         machine = self.machine
-        sm_class = (
-            machine if isinstance(machine, StateMachineMetaclass) else machine.__class__
-        )
         return pydot.Dot(
             "list",
             graph_type="digraph",
-            label=sm_class.__name__,
+            label=machine.name,
             fontsize=self.state_font_size,
             rankdir=self.graph_rankdir,
         )

statemachine/dispatcher.py

@@ -18,8 +18,8 @@ class ObjectConfig(namedtuple("ObjectConfig", "obj skip_attrs")):
 
     @classmethod
     def from_obj(cls, obj):
-        if isinstance(obj, (tuple, list)):
-            return cls(*obj)
+        if isinstance(obj, ObjectConfig):
+            return obj
         else:
             return cls(obj, set())
 

statemachine/factory.py

@@ -17,6 +17,7 @@ def __init__(cls, name, bases, attrs):
         super(StateMachineMetaclass, cls).__init__(name, bases, attrs)
         registry.register(cls)
         cls._abstract = True
+        cls.name = cls.__name__
         cls.states = []
         cls._events = OrderedDict()
         cls.states_map = {}

statemachine/state.py

@@ -91,10 +91,13 @@ def __init__(
     def _setup(self, resolver):
         self.enter.setup(resolver)
         self.exit.setup(resolver)
-        self.enter.add("on_enter_state", prepend=True, suppress_errors=True)
-        self.enter.add("on_enter_{}".format(self.id), suppress_errors=True)
-        self.exit.add("on_exit_state", prepend=True, suppress_errors=True)
-        self.exit.add("on_exit_{}".format(self.id), suppress_errors=True)
+
+    def _add_observer(self, *resolvers):
+        for r in resolvers:
+            self.enter.add("on_enter_state", resolver=r, prepend=True, suppress_errors=True)
+            self.enter.add("on_enter_{}".format(self.id), resolver=r, suppress_errors=True)
+            self.exit.add("on_exit_state", resolver=r, prepend=True, suppress_errors=True)
+            self.exit.add("on_exit_{}".format(self.id), resolver=r, suppress_errors=True)
 
     def __repr__(self):
         return "{}({!r}, id={!r}, value={!r}, initial={!r}, final={!r})".format(