feature: expect_override decorator to mark model methods safe for ove…

…rriding

Changelog.md

@@ -4,7 +4,8 @@
 
 - Bug #610: Decorate models appropriately when `HierarchicalMachine` is passed to `add_state` (thanks @e0lithic)
 - Bug #647: Let `may_<trigger>` check all parallel states in processing order (thanks @spearsear)
-- Bug: `HSM.is_state` works with parallel states now 
+- Bug: `HSM.is_state` works with parallel states now
+- Experimental feature: Use the `transitions.experimental.typing.expect_override` decorator to mark methods as safe for overriding `Machine._checked_assignment` will now override _existing_ model methods (e.g. existing trigger like `melt` or convenience functions like `is_<state>`) if they have a `expect_override` attribute set to `True`. 
 
 ## 0.9.1 (May 2024)
 

tests/test_experimental.py

@@ -0,0 +1,46 @@
+from unittest import TestCase
+from unittest.mock import MagicMock
+
+from transitions import Machine
+from transitions.experimental.decoration import expect_override
+
+
+class TestExperimental(TestCase):
+
+    def setUp(self) -> None:
+        self.machine_cls = Machine
+        return super().setUp()
+
+    def test_override_decorator(self):
+        b_mock = MagicMock()
+        c_mock = MagicMock()
+
+        class Model:
+
+            @expect_override
+            def is_A(self) -> bool:
+                raise RuntimeError("Should be overridden")
+
+            def is_B(self) -> bool:
+                b_mock()
+                return False
+
+            @expect_override
+            def is_C(self) -> bool:
+                c_mock()
+                return False
+
+        model = Model()
+        machine = self.machine_cls(model, states=["A", "B"], initial="A")
+        self.assertTrue(model.is_A())
+        self.assertTrue(model.to_B())
+        self.assertFalse(model.is_B())  # not overridden with convenience function
+        self.assertTrue(b_mock.called)
+        self.assertFalse(model.is_C())  # not overridden yet
+        self.assertTrue(c_mock.called)
+        machine.add_state("C")
+        self.assertFalse(model.is_C())  # now it is!
+        self.assertEqual(1, c_mock.call_count)   # call_count is not increased
+        self.assertTrue(model.to_C())
+        self.assertTrue(model.is_C())
+        self.assertEqual(1, c_mock.call_count)

transitions/core.py

@@ -886,10 +886,11 @@ def _add_model_to_state(self, state, model):
                 state.add_callback(callback[3:], method)
 
     def _checked_assignment(self, model, name, func):
-        if hasattr(model, name):
-            _LOGGER.warning("%sModel already contains an attribute '%s'. Skip binding.", self.name, name)
-        else:
+        bound_func = getattr(model, name, None)
+        if bound_func is None or getattr(bound_func, "expect_override", False):
             setattr(model, name, func)
+        else:
+            _LOGGER.warning("%sModel already contains an attribute '%s'. Skip binding.", self.name, name)
 
     def _can_trigger(self, model, trigger, *args, **kwargs):
         state = self.get_model_state(model)

transitions/experimental/decoration.py

@@ -0,0 +1,8 @@
+from typing import Callable, ParamSpec
+
+P = ParamSpec("P")
+
+
+def expect_override(func: Callable[P, bool | None]) -> Callable[P, bool | None]:
+    setattr(func, "expect_override", True)
+    return func