flask-stateflow 0.1.0__py3-none-any.whl

flask_stateflow/__init__.py

@@ -0,0 +1,11 @@
+from src.flask_stateflow.stateflow import (
+    StateMachine,
+    transition,
+    guard,
+    on_enter,
+    on_exit,
+    validate,
+    InvalidTransitionError,
+    StateNotFoundError,
+    GuardBlockedError,
+)

flask_stateflow/stateflow.py

@@ -0,0 +1,169 @@
+#A decorator that marks a method as a state transition handler.
+def transition(from_state, to_state, guards=None):
+    def decorator(fn):
+        fn._sf = {'from': from_state, 'to': to_state, 'guards': guards or []}
+        return fn
+    return decorator
+
+#A decorator that marks a method as guard, which is a check before a transition.
+def guard(name=None):
+    def decorator(fn):
+        fn._sf_guard = name or fn.__name__
+        return fn
+    return decorator
+
+#A decorator that marks a method as a hook that is called when the specified state is entered
+def on_enter(state):
+    def decorator(fn):
+        fn._sf_enter = state
+        return fn
+    return decorator
+
+#A decorator that marks a method as a hook that is called when the specified state is exited.
+def on_exit(state):
+    def decorator(fn):
+        fn._sf_exit = state
+        return fn
+    return decorator
+
+def validate(cls):
+    errs = []
+    states = set(cls.__states__)
+    for fr, tos in cls.__transitions__.items():
+        if fr not in states:
+            errs.append(f"Unknown from-state: '{fr}'")
+        for to in tos:
+            if to not in states:
+                errs.append(f"Unknown to-state: '{to}'")
+    for fr, tos in cls._sf_trans.items():
+        for to, cfg in tos.items():
+            for g in cfg.get('guards', []):
+                if g not in cls._sf_guards:
+                    errs.append(f"Missing guard '{g}' for {fr}->{to}")
+    return errs
+
+#A metaclass is a class that creates classes.
+class _Meta(type):
+    def __new__(mcs, name, bases, ns):
+        cls = super().__new__(mcs, name, bases, ns)
+        trans, guards, enters, exits = {}, {}, {}, {}
+
+        for base in bases:
+            trans.update(getattr(base, '_sf_trans', {}))
+            guards.update(getattr(base, '_sf_guards', {}))
+            for st, fns in getattr(base, '_sf_enters', {}).items():
+                enters.setdefault(st, []).extend(fns)
+            for st, fns in getattr(base, '_sf_exits', {}).items():
+                exits.setdefault(st, []).extend(fns)
+
+        for attr in ns.values():
+            if not callable(attr):
+                continue
+            if hasattr(attr, '_sf'):
+                c = attr._sf
+                trans.setdefault(c['from'], {})[c['to']] = {
+                    'fn': attr.__name__, 'guards': c['guards']
+                }
+            if hasattr(attr, '_sf_guard'):
+                guards[attr._sf_guard] = attr
+            if hasattr(attr, '_sf_enter'):
+                enters.setdefault(attr._sf_enter, []).append(attr)
+            if hasattr(attr, '_sf_exit'):
+                exits.setdefault(attr._sf_exit, []).append(attr)
+
+        cls._sf_trans = trans
+        cls._sf_guards = guards
+        cls._sf_enters = enters
+        cls._sf_exits = exits
+        return cls
+
+class InvalidTransitionError(Exception):
+    def __init__(self, current, target, allowed=None):
+        msg = f"'{current}' -> '{target}' not allowed"
+        if allowed:
+            msg += f", allowed from '{current}': {allowed}"
+        super().__init__(msg)
+
+class GuardBlockedError(Exception):
+    def __init__(self, name, reason=None):
+        msg = f"Guard '{name}' blocked"
+        if reason:
+            msg += f": {reason}"
+        super().__init__(msg)
+
+
+class StateNotFoundError(Exception):
+    def __init__(self, state, available=None):
+        msg = f"State '{state}' not found"
+        if available:
+            msg += f", available: {available}"
+        super().__init__(msg)
+
+class StateMachine(metaclass=_Meta):
+    __states__ = []
+    __transitions__ = {}
+    __state_column__ = 'state'
+    __state_default__ = None
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._sf_state = self.__state_default__ or (self.__states__[0] if self.__states__ else None)
+
+    @property
+    def current_state(self):
+        col = self.__state_column__
+        if hasattr(self, col) and not col.startswith('_'):
+            v = getattr(self, col)
+            if v is not None:
+                return v
+        return self._sf_state
+
+    @current_state.setter
+    def current_state(self, v):
+        col = self.__state_column__
+        if hasattr(self, col) and not col.startswith('_'):
+            setattr(self, col, v)
+        self._sf_state = v
+
+    @classmethod
+    def can_transition(cls, fr, to):
+        return to in cls.__transitions__.get(fr, [])
+
+    @classmethod
+    def get_allowed(cls, fr):
+        return list(cls.__transitions__.get(fr, []))
+
+    def transition_to(self, new_state, **kwargs):
+        cur = self.current_state
+
+        if new_state not in self.__states__:
+            raise StateNotFoundError(new_state, self.__states__)
+        if not self.can_transition(cur, new_state):
+            raise InvalidTransitionError(cur, new_state, self.get_allowed(cur))
+
+        cfg = self._sf_trans.get(cur, {}).get(new_state, {})
+
+        for gname in cfg.get('guards', []):
+            g = self._sf_guards.get(gname)
+            if not g:
+                raise GuardBlockedError(gname, "not found")
+            r = g(self)
+            if r is not True:
+                raise GuardBlockedError(gname, r if isinstance(r, str) else None)
+
+        for h in self._sf_exits.get(cur, []):
+            h(self)
+
+        fn = cfg.get('fn')
+        if fn:
+            getattr(self, fn)(**kwargs)
+
+        self.current_state = new_state
+
+        for h in self._sf_enters.get(new_state, []):
+            h(self)
+
+        return True
+
+    def __repr__(self):
+        return f"<{type(self).__name__} {self.current_state}>"

flask_stateflow-0.1.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: flask-stateflow
+Version: 0.1.0
+Summary: Minimal declarative state machine
+Requires-Python: >=3.8
+Dynamic: requires-python
+Dynamic: summary

flask_stateflow-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+flask_stateflow/__init__.py,sha256=c_o3CeHJGNMuQ2fh6R8ypwGHiINLJ7rqQVNDR9GAcb8,216
+flask_stateflow/stateflow.py,sha256=KiQxJwYOBZpYw8nGpTefbTxSoMhfkkyZYVVK-QXAf_o,5728
+flask_stateflow-0.1.0.dist-info/METADATA,sha256=YHtR3AXWEJovn3-YF7Zk-JVmDa-X_Yrubo_HKnoadKg,174
+flask_stateflow-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+flask_stateflow-0.1.0.dist-info/top_level.txt,sha256=EeMKGhxUP3Uropg2_jsD9dSgRdBwu_LkhVka0J37SsA,16
+flask_stateflow-0.1.0.dist-info/RECORD,,

flask_stateflow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flask_stateflow-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flask_stateflow