replace 'self' with Machine.self_literal

This enables identity checks to determine whether a machine should add itself as a model (#545)

Author: aleneum

Changelog.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.8.10 
+
+- Feature #545: The literal 'self' (default model parameter of `Machine`) has been replaced by the class variable `Machine.self_literal = 'self'`. `Machine` now performs an identity check (instead of a value check) with `mod is self.self_literal` to determine whether it should act as a model. While 'self' should still work when passed to the `model` parameter, we encourage using `Machine.self_literal` from now on. This was done to enable easier override of `Machine.__eq__` in subclasses (thanks @VKSolovev).
+
 ## 0.8.9 (September 2021)
 
 Release 0.8.9 is a minor release and contains a bugfix for HSM, a feature for `GraphSupport` and changes internal cache handling:

README.md

@@ -987,7 +987,7 @@ lump.state
 Here you get to consolidate all state machine functionality into your existing model, which often feels more natural way than sticking all of the functionality we want in a separate standalone `Machine` instance.
 
 A machine can handle multiple models which can be passed as a list like `Machine(model=[model1, model2, ...])`.
-In cases where you want to add models *as well as* the machine instance itself, you can pass the string placeholder `'self'` during initialization like `Machine(model=['self', model1, ...])`.
+In cases where you want to add models *as well as* the machine instance itself, you can pass the class variable placeholder (string) `Machine.self_literal` during initialization like `Machine(model=[Machine.self_literal, model1, ...])`.
 You can also create a standalone machine, and register models dynamically via `machine.add_model` by passing `model=None` to the constructor.
 Furthermore, you can use `machine.dispatch` to trigger events on all currently added models.
 Remember to call `machine.remove_model` if machine is long-lasting and your models are temporary and should be garbage collected:

examples/Frequently asked questions.ipynb

@@ -546,7 +546,7 @@
     "    # override Machine.add_model to assign 'can_trigger' to the model\n",
     "    def add_model(self, model, initial=None):\n",
     "        for mod in listify(model):\n",
-    "            mod = self if mod == 'self' else mod\n",
+    "            mod = self if mod is self.self_literal else mod\n",
     "            if mod not in self.models:\n",
     "                setattr(mod, 'can_trigger', partial(self._can_trigger, mod))\n",
     "                super(PeekMachine, self).add_model(mod, initial)\n",

transitions/core.py

@@ -502,17 +502,18 @@ class Machine(object):
     state_cls = State
     transition_cls = Transition
     event_cls = Event
+    self_literal = 'self'
 
-    def __init__(self, model='self', states=None, initial='initial', transitions=None,
+    def __init__(self, model=self_literal, states=None, initial='initial', transitions=None,
                  send_event=False, auto_transitions=True,
                  ordered_transitions=False, ignore_invalid_triggers=None,
                  before_state_change=None, after_state_change=None, name=None,
                  queued=False, prepare_event=None, finalize_event=None, model_attribute='state', on_exception=None,
                  **kwargs):
         """
         Args:
-            model (object or list): The object(s) whose states we want to manage. If 'self',
-                the current Machine instance will be used the model (i.e., all
+            model (object or list): The object(s) whose states we want to manage. If set to `Machine.self_literal`
+                (default value), the current Machine instance will be used as the model (i.e., all
                 triggering events will be attached to the Machine itself). Note that an empty list
                 is treated like no model.
             states (list or Enum): A list or enumeration of valid states. Each list element can be either a
@@ -616,7 +617,7 @@ def add_model(self, model, initial=None):
                 initial = self.initial
 
         for mod in models:
-            mod = self if mod == 'self' else mod
+            mod = self if mod is self.self_literal else mod
             if mod not in self.models:
                 self._checked_assignment(mod, 'trigger', partial(self._get_trigger, mod))
 

transitions/extensions/asyncio.py

@@ -326,7 +326,7 @@ def add_model(self, model, initial=None):
         super().add_model(model, initial)
         if self.has_queue == 'model':
             for mod in listify(model):
-                self._transition_queue_dict[id(mod) if mod != 'self' else id(self)] = deque()
+                self._transition_queue_dict[id(self) if mod is self.self_literal else id(mod)] = deque()
 
     async def dispatch(self, trigger, *args, **kwargs):  # ToDo: not tested
         """ Trigger an event on all models assigned to the machine.

transitions/extensions/diagrams.py

@@ -224,7 +224,7 @@ def add_model(self, model, initial=None):
         models = listify(model)
         super(GraphMachine, self).add_model(models, initial)
         for mod in models:
-            mod = self if mod == 'self' else mod
+            mod = self if mod is self.self_literal else mod
             if hasattr(mod, 'get_graph'):
                 raise AttributeError('Model already has a get_graph attribute. Graph retrieval cannot be bound.')
             setattr(mod, 'get_graph', partial(self._get_graph, mod))

transitions/extensions/locking.py

@@ -145,7 +145,7 @@ def add_model(self, model, initial=None, model_context=None):
         output = _super(LockedMachine, self).add_model(models, initial)
 
         for mod in models:
-            mod = self if mod == 'self' else mod
+            mod = self if mod is self.self_literal else mod
             self.model_context_map[id(mod)].extend(self.machine_context)
             self.model_context_map[id(mod)].extend(model_context)
 

transitions/extensions/nesting.py

@@ -418,7 +418,7 @@ def add_model(self, model, initial=None):
         """ Extends transitions.core.Machine.add_model by applying a custom 'to' function to
             the added model.
         """
-        models = [mod if mod != 'self' else self for mod in listify(model)]
+        models = [self if mod is self.self_literal else mod for mod in listify(model)]
         _super(HierarchicalMachine, self).add_model(models, initial=initial)
         initial_name = getattr(models[0], self.model_attribute)
         if hasattr(initial_name, 'name'):

transitions/extensions/nesting_legacy.py

@@ -259,7 +259,7 @@ def add_model(self, model, initial=None):
         _super(HierarchicalMachine, self).add_model(model, initial=initial)
         models = listify(model)
         for mod in models:
-            mod = self if mod == 'self' else mod
+            mod = self if mod is self.self_literal else mod
             # TODO: Remove 'mod != self' in 0.7.0
             if hasattr(mod, 'to') and mod != self:
                 _LOGGER.warning("%sModel already has a 'to'-method. It will NOT "