qstate 1.0.0__py3-none-any.whl

qsm/__init__.py

@@ -0,0 +1,10 @@
+"""Queued state machine package."""
+
+from .qsm import QSM
+from .states import State, StateContext
+
+__all__ = [
+    "QSM",
+    "State",
+    "StateContext",
+]

qsm/deque.py

@@ -0,0 +1,82 @@
+from queue import Full, Queue
+from time import monotonic
+from typing import Optional
+
+
+class StringDequeQueue(Queue[str]):
+    """Thread-safe string queue that supports appending to either end.
+
+    This queue follows the synchronization behavior of ``queue.Queue`` while
+    adding prepend operations backed by the underlying deque.
+    """
+
+    def put(self, *items: str, block: bool = True, timeout: Optional[float] = None) -> None:
+        """Append one or more strings using the standard ``Queue.put`` name."""
+        self.append(*items, block=block, timeout=timeout)
+
+    def append(self, *items: str, block: bool = True, timeout: Optional[float] = None) -> None:
+        """Add one or more strings to the back of the queue."""
+        for item in items:
+            self._put_string(item, left=False, block=block, timeout=timeout)
+
+    def prepend(self, *items: str, block: bool = True, timeout: Optional[float] = None) -> None:
+        """Add one or more strings to the front of the queue."""
+        for item in items:
+            self._put_string(item, left=True, block=block, timeout=timeout)
+
+    def append_nowait(self, *items: str) -> None:
+        """Add one or more strings to the back without blocking."""
+        self.append(*items, block=False)
+
+    def prepend_nowait(self, *items: str) -> None:
+        """Add one or more strings to the front without blocking."""
+        self.prepend(*items, block=False)
+
+    def flush(self) -> int:
+        """Remove all queued strings and count them as completed.
+
+        Returns:
+            The number of queued items removed.
+        """
+        with self.mutex:
+            removed = self._qsize()
+            if removed == 0:
+                return 0
+
+            self.queue.clear()
+            self.unfinished_tasks -= removed
+            if self.unfinished_tasks == 0:
+                self.all_tasks_done.notify_all()
+            self.not_full.notify_all()
+            return removed
+
+    def _put_string(self, item: str, left: bool, block: bool, timeout: Optional[float]) -> None:
+        """Add a single string while holding the queue's producer lock."""
+        if not isinstance(item, str):
+            raise TypeError("StringDequeQueue only accepts strings")
+        if timeout is not None and timeout < 0:
+            raise ValueError("'timeout' must be either 0 or non-negative")
+
+        with self.not_full:
+            if self.maxsize > 0:
+                if not block:
+                    if self._qsize() >= self.maxsize:
+                        raise Full
+                elif timeout is None:
+                    while self._qsize() >= self.maxsize:
+                        self.not_full.wait()
+                else:
+                    endtime = monotonic() + timeout
+                    while self._qsize() >= self.maxsize:
+                        remaining = endtime - monotonic()
+                        if remaining <= 0.0:
+                            raise Full
+                        self.not_full.wait(remaining)
+
+            if left:
+                self.queue.appendleft(item)
+            else:
+                self.queue.append(item)
+
+            self.unfinished_tasks += 1
+            self.not_empty.notify()

qsm/exceptions.py

@@ -0,0 +1,4 @@
+class NoSuchStateException(Exception):
+    """Raised when a state name is not registered with a QSM."""
+
+    pass

qsm/qsm.py

@@ -0,0 +1,72 @@
+from queue import Empty
+from typing import Any, Dict, Optional
+
+from .deque import StringDequeQueue
+from .exceptions import NoSuchStateException
+from .states import State, StateContext
+
+
+class QSM:
+    """Queued state machine.
+
+    A ``QSM`` stores pending state names in a queue, resolves each name through
+    ``state_map``, and executes states until no pending states remain.
+    """
+
+    def __init__(self, initial_context: Any = None, initial_state: str = "initial_state", max_queue_size: Optional[int] = None):
+        """Create a queued state machine.
+
+        Args:
+            initial_context: Shared workflow data passed to every state.
+            initial_state: State name used when ``loop`` is called without an
+                explicit initial state.
+            max_queue_size: Optional maximum number of queued states.
+        """
+        self.queue = StringDequeQueue(maxsize=max_queue_size) if max_queue_size is not None else StringDequeQueue()
+        self.state_map: Dict[str, State] = {}
+        self.initial_state = initial_state
+        self.current_state: str = initial_state
+        self.context = initial_context
+
+    def get_next_state(self) -> Optional[str]:
+        """Dequeues the next state name and makes it current.
+
+        Returns ``None`` when no state is queued.
+        """
+        try:
+            self.current_state = self.queue.get_nowait()
+            return self.current_state
+        except Empty:
+            return None
+
+    def execute_state(self, name: str):
+        """Execute a registered state by name.
+
+        Raises:
+            NoSuchStateException: If ``name`` is not registered in
+                ``state_map``.
+        """
+        if name not in self.state_map:
+            raise NoSuchStateException(name)
+        ctx = StateContext(
+            queue=self.queue,
+            context=self.context,
+        )
+        self.state_map[name].execute(ctx)
+
+    def execute_current_state(self):
+        """Execute the state named by ``current_state``."""
+        self.execute_state(self.current_state)
+
+    def loop(self, flush: bool = True):
+        """Run queued states until the queue is empty.
+
+        If ``flush`` is True, the loop will flush the current queue and enqueue self.initial_state
+        """
+        if flush:
+            self.queue.flush()
+            self.queue.append(self.initial_state)
+        while not self.queue.empty():
+            state = self.get_next_state()
+            if state is not None:
+                self.execute_current_state()

qsm/states.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+import logging
+from typing import Any
+
+from .deque import StringDequeQueue
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class StateContext:
+    """Execution context passed into each state.
+
+    Attributes:
+        queue: Queue used to schedule additional state names.
+        context: Shared workflow data owned by the ``QSM`` instance.
+    """
+
+    queue: StringDequeQueue
+    context: Any
+
+
+class State(ABC):
+    """Base class for queued state machine states."""
+
+    @abstractmethod
+    def execute(self, ctx: StateContext):
+        """Run this state with the provided context."""
+        pass