chore: Observers rebranded to listeners (#448)

* chore: Observers rebranded to listeners

* tests: Fixing warnings

* chore: updating deps

Author: fgmacedo

docs/index.md

@@ -12,7 +12,7 @@ transitions
 actions
 guards
 models
-observers
+listeners
 async
 mixins
 integrations

docs/listeners.md

@@ -0,0 +1,107 @@
+
+(observers)=
+# Listeners
+
+Listeners are a way to generically add behavior to a state machine without
+changing its internal implementation.
+
+One possible use case is to add a listener 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 LogListener(object):
+...     def __init__(self, name):
+...         self.name = name
+...
+...     def after_transition(self, event, source, target):
+...         print(f"{self.name} after: {source.id}--({event})-->{target.id}")
+...
+...     def on_enter_state(self, target, event):
+...         print(f"{self.name} enter: {target.id} from {event}")
+
+
+>>> sm = TrafficLightMachine(listeners=[LogListener("Paulista Avenue")])
+Paulista Avenue enter: green from __initial__
+
+>>> sm.cycle()
+Paulista Avenue enter: yellow from cycle
+Paulista Avenue after: green--(cycle)-->yellow
+'Running cycle from green to yellow'
+
+```
+
+## Adding listeners to an instance
+
+Attach listeners to an already running state machine instance using `add_listener`.
+
+Exploring our example, imagine that you can implement the LED panel as a listener, that
+reacts to state changes and turn on/off automatically.
+
+
+``` py
+>>> class LedPanel:
+...
+...     def __init__(self, color: str):
+...         self.color = color
+...
+...     def on_enter_state(self, target: State):
+...         if target.id == self.color:
+...             print(f"{self.color} turning on")
+...
+...     def on_exit_state(self, source: State):
+...         if source.id == self.color:
+...             print(f"{self.color} turning off")
+
+```
+
+Adding a listener for each traffic light indicator
+
+```
+>>> sm.add_listener(LedPanel("green"), LedPanel("yellow"), LedPanel("red"))  # doctest: +ELLIPSIS
+TrafficLightMachine...
+
+```
+
+Now each "LED panel" reacts to changes in state from the state machine:
+
+```py
+>>> sm.cycle()
+yellow turning off
+Paulista Avenue enter: red from cycle
+red turning on
+Don't move.
+Paulista Avenue after: yellow--(cycle)-->red
+'Running cycle from yellow to red'
+
+>>> sm.cycle()
+red turning off
+Go ahead!
+Paulista Avenue enter: green from cycle
+green turning on
+Paulista Avenue after: red--(cycle)-->green
+'Running cycle from red to green'
+
+```
+
+
+```{hint}
+The `StateMachine` itself is registered as a listener, so by using `listeners` an
+external object can have the same level of functionalities provided to the built-in class.
+```
+
+```{tip}
+{ref}`domain models` are also registered as a listener.
+```
+
+
+```{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/models.md

@@ -20,7 +20,7 @@ domain object to hold attributes and methods to be used on the `StateMachine` de
 ```
 
 ```{hint}
-Domain models are registered as {ref}`observers`, so you can have the same level of functionalities
+Domain models are registered as {ref}`listeners`, so you can have the same level of functionalities
 provided to the built-in {ref}`StateMachine`, such as implementing all {ref}`actions` and
 {ref}`guards` on your domain model and keeping only the definition of {ref}`states` and
 {ref}`transitions` on the {ref}`StateMachine`.

docs/observers.md

@@ -0,0 +1,52 @@
+# StateMachine 2.3.2
+
+*Not released yet*
+
+## What's new in 2.3.2
+
+Observers are now rebranded to {ref}`listeners`. With expanted support for adding listeners when
+instantiating a state machine. This allows covering more use cases.
+
+### Listeners at class initialization
+
+Listeners are a way to generically add behavior to a state machine without changing its internal implementation.
+
+Example:
+
+```py
+>>> from tests.examples.traffic_light_machine import TrafficLightMachine
+
+>>> class LogListener(object):
+...     def __init__(self, name):
+...         self.name = name
+...
+...     def after_transition(self, event, source, target):
+...         print(f"{self.name} after: {source.id}--({event})-->{target.id}")
+...
+...     def on_enter_state(self, target, event):
+...         print(f"{self.name} enter: {target.id} from {event}")
+
+
+>>> sm = TrafficLightMachine(listeners=[LogListener("Paulista Avenue")])
+Paulista Avenue enter: green from __initial__
+
+>>> sm.cycle()
+Paulista Avenue enter: yellow from cycle
+Paulista Avenue after: green--(cycle)-->yellow
+'Running cycle from green to yellow'
+
+```
+
+```{seealso}
+See {ref}`listeners` for more details.
+```
+
+## Bugfixes in 2.3.2
+
+-
+
+## Deprecation notes
+
+### Statemachine class
+
+- `StateMachine.add_observer` is deprecated in favor of `StateMachine.add_listener`.

docs/releases/2.3.2.md

@@ -15,6 +15,7 @@ Below are release notes through StateMachine and its patch releases.
 ```{toctree}
 :maxdepth: 2
 
+2.3.2
 2.3.1
 2.3.0
 2.2.0

docs/releases/index.md

@@ -18,8 +18,8 @@
 
 
 @dataclass
-class ObjectConfig:
-    """Configuration for objects passed to resolver_factory.
+class Listener:
+    """Object reference that provides attributes to be used as callbacks.
 
     Args:
         obj: Any object that will serve as lookup for attributes.
@@ -31,8 +31,8 @@ class ObjectConfig:
     resolver_id: str
 
     @classmethod
-    def from_obj(cls, obj, skip_attrs=None) -> "ObjectConfig":
-        if isinstance(obj, ObjectConfig):
+    def from_obj(cls, obj, skip_attrs=None) -> "Listener":
+        if isinstance(obj, Listener):
             return obj
         else:
             if skip_attrs is None:
@@ -42,17 +42,17 @@ def from_obj(cls, obj, skip_attrs=None) -> "ObjectConfig":
 
 
 @dataclass
-class ObjectConfigs:
-    """Configuration for objects passed to resolver_factory."""
+class Listeners:
+    """Listeners that provides attributes to be used as callbacks."""
 
-    items: Tuple[ObjectConfig, ...]
+    items: Tuple[Listener, ...]
     all_attrs: Set[str]
 
     @classmethod
-    def from_configs(cls, configs: Iterable["ObjectConfig"]) -> "ObjectConfigs":
-        configs = tuple(configs)
-        all_attrs = set().union(*(config.all_attrs for config in configs))
-        return cls(configs, all_attrs)
+    def from_listeners(cls, listeners: Iterable["Listener"]) -> "Listeners":
+        listeners = tuple(listeners)
+        all_attrs = set().union(*(listener.all_attrs for listener in listeners))
+        return cls(listeners, all_attrs)
 
     def resolve(self, specs: "CallbackSpecList", registry):
         found_convention_specs = specs.conventional_specs & self.all_attrs
@@ -155,4 +155,4 @@ async def method(*args, **kwargs):
 
 
 def resolver_factory_from_objects(*objects: Tuple[Any, ...]):
-    return ObjectConfigs.from_configs(ObjectConfig.from_obj(o) for o in objects)
+    return Listeners.from_listeners(Listener.from_obj(o) for o in objects)

poetry.lock

@@ -129,12 +129,6 @@ def _setup(self):
         self.exit.add("on_exit_state", priority=CallbackPriority.GENERIC, is_convention=True)
         self.exit.add(f"on_exit_{self.id}", priority=CallbackPriority.NAMING, is_convention=True)
 
-    def _add_observer(self, register):
-        register(self._specs)
-
-    def _check_callbacks(self, check):
-        check(self._specs)
-
     def __repr__(self):
         return (
             f"{type(self).__name__}({self.name!r}, id={self.id!r}, value={self.value!r}, "