vention-state-machine 0.2.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

vention_state_machine-0.3.1.dist-info/METADATA

@@ -0,0 +1,392 @@
+Metadata-Version: 2.1
+Name: vention-state-machine
+Version: 0.3.1
+Summary: Declarative state machine framework for machine apps
+License: Proprietary
+Author: VentionCo
+Requires-Python: >=3.10,<3.11
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Dist: asyncio (>=3.4.3,<4.0.0)
+Requires-Dist: coverage (>=7.10.1,<8.0.0)
+Requires-Dist: fastapi (==0.121.1)
+Requires-Dist: graphviz (>=0.21,<0.22)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: transitions (>=0.9.3,<0.10.0)
+Requires-Dist: uvicorn (>=0.35.0,<0.36.0)
+Description-Content-Type: text/markdown
+
+# vention-state-machine
+
+A lightweight wrapper around `transitions` for building async-safe, recoverable hierarchical state machines with minimal boilerplate.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [🧠 Concepts & Overview](#-concepts--overview)
+- [⚙️ Installation & Setup](#️-installation--setup)
+- [🚀 Quickstart Tutorial](#-quickstart-tutorial)
+- [🛠 How-to Guides](#-how-to-guides)
+- [📖 API Reference](#-api-reference)
+- [🔍 Troubleshooting & FAQ](#-troubleshooting--faq)
+
+## ✨ Features
+
+- Built-in `ready` / `fault` states
+- Global transitions: `to_fault`, `reset`
+- Optional state recovery (`recover__state`)
+- Async task spawning and cancellation
+- Timeouts and auto-fault handling
+- Transition history recording with timestamps + durations
+- Guard conditions for blocking transitions
+- Global state change callbacks for logging/MQTT
+- Optional FastAPI router for HTTP access and visualization
+
+## 🧠 Concepts & Overview
+
+This library uses a **declarative domain-specific language (DSL)** to define state machines in a readable, strongly typed way.
+
+- **State** → A leaf node in the state machine
+- **StateGroup** → Groups related states, creating hierarchical namespaces
+- **Trigger** → Named events that initiate transitions
+
+Example:
+
+```python
+class MyStates(StateGroup):
+    idle: State = State()
+    working: State = State()
+
+class Triggers:
+    begin = Trigger("begin")
+    finish = Trigger("finish")
+
+TRANSITIONS = [
+    Triggers.finish.transition(MyStates.working, MyStates.idle),
+]
+```
+
+
+### Base States and Triggers
+
+All machines include:
+
+**States:**
+- `ready` (initial)
+- `fault` (global error)
+
+**Triggers:**
+- `start`, `to_fault`, `reset`
+
+```python
+from state_machine.core import BaseStates, BaseTriggers
+
+state_machine.trigger(BaseTriggers.RESET.value)
+assert state_machine.state == BaseStates.READY.value
+```
+
+## ⚙️ Installation & Setup
+
+```bash
+pip install vention-state-machine
+```
+
+**Optional dependencies:**
+- Graphviz (required for diagram generation)
+- FastAPI (for HTTP exposure of state machine)
+
+**Install optional tools:**
+
+MacOS:
+```bash
+brew install graphviz
+pip install fastapi
+```
+
+Linux (Debian/Ubuntu)
+```bash
+sudo apt-get install graphviz
+pip install fastapi
+```
+
+
+## 🚀 Quickstart Tutorial
+
+### 1. Define States and Triggers
+
+```python
+from state_machine.defs import StateGroup, State, Trigger
+
+class Running(StateGroup):
+    picking: State = State()
+    placing: State = State()
+    homing: State = State()
+
+class States:
+    running = Running()
+
+class Triggers:
+    start = Trigger("start")
+    finished_picking = Trigger("finished_picking")
+    finished_placing = Trigger("finished_placing")
+    finished_homing = Trigger("finished_homing")
+    to_fault = Trigger("to_fault")
+    reset = Trigger("reset")
+```
+
+### 2. Define Transitions
+
+```python
+TRANSITIONS = [
+    Triggers.start.transition("ready", States.running.picking),
+    Triggers.finished_picking.transition(States.running.picking, States.running.placing),
+    Triggers.finished_placing.transition(States.running.placing, States.running.homing),
+    Triggers.finished_homing.transition(States.running.homing, States.running.picking),
+]
+```
+
+### 3. Implement Your State Machine
+
+```python
+from state_machine.core import StateMachine
+from state_machine.decorators import on_enter_state, auto_timeout, guard, on_state_change
+
+class CustomMachine(StateMachine):
+    def __init__(self):
+        super().__init__(states=States, transitions=TRANSITIONS)
+
+    @on_enter_state(States.running.picking)
+    @auto_timeout(5.0, Triggers.to_fault)
+    def enter_picking(self, _):
+        print("🔹 Entering picking")
+
+    @on_enter_state(States.running.placing)
+    def enter_placing(self, _):
+        print("🔸 Entering placing")
+
+    @on_enter_state(States.running.homing)
+    def enter_homing(self, _):
+        print("🔺 Entering homing")
+
+    @guard(Triggers.reset)
+    def check_safety_conditions(self) -> bool:
+        return not self.estop_pressed
+
+    @on_state_change
+    def publish_state_to_mqtt(self, old_state: str, new_state: str, trigger: str):
+        mqtt_client.publish("machine/state", {
+            "old_state": old_state,
+            "new_state": new_state,
+            "trigger": trigger
+        })
+```
+
+### 4. Start It
+
+```python
+state_machine = StateMachine()
+state_machine.start()
+```
+
+## 🛠 How-to Guides
+
+### Expose Over HTTP with FastAPI
+
+```python
+from fastapi import FastAPI
+from state_machine.router import build_router
+from state_machine.core import StateMachine
+
+state_machine = StateMachine(...)
+state_machine.start()
+
+app = FastAPI()
+app.include_router(build_router(state_machine))
+```
+
+**Endpoints:**
+- `GET /state` → Current state
+- `GET /history` → Transition history
+- `POST /<trigger>` → Trigger a transition
+- `GET /diagram.svg` → Graphviz diagram
+
+### Timeout Example
+
+```python
+@auto_timeout(5.0, Triggers.to_fault)
+def enter_state(self, _):
+    ...
+```
+
+### Recovery Example
+
+```python
+state_machine = StateMachine(enable_last_state_recovery=True)
+state_machine.start()  # will attempt recover__{last_state}
+```
+
+### Triggering state transitions via I/O
+
+Here's an example of hooking up state transitions to I/O events via MQTT
+
+```python
+import asyncio
+import paho.mqtt.client as mqtt
+from state_machine.core import StateMachine
+from state_machine.defs import State, StateGroup, Trigger
+from state_machine.decorators import on_enter_state
+
+class MachineStates(StateGroup):
+    idle: State = State()
+    running: State = State()
+
+class States:
+    machine = MachineStates()
+
+class Triggers:
+    start_button = Trigger("start_button")
+    box_missing = Trigger("box_missing")
+
+TRANSITIONS = [
+    Triggers.start_button.transition(States.machine.idle, States.machine.running),
+    Triggers.box_missing.transition(States.machine.running, States.machine.idle),
+]
+
+class MachineController(StateMachine):
+    def __init__(self):
+        super().__init__(states=States, transitions=TRANSITIONS)
+        self.mqtt_client = mqtt.Client()
+        self.setup_mqtt()
+
+    def setup_mqtt(self):
+        """Configure MQTT client to listen for I/O signals."""
+        self.mqtt_client.on_connect = self.on_mqtt_connect
+        self.mqtt_client.on_message = self.on_mqtt_message
+        self.mqtt_client.connect("localhost", 1883, 60)
+        
+        # Start MQTT loop in background
+        self.spawn(self.mqtt_loop())
+
+    async def mqtt_loop(self):
+        """Background task to handle MQTT messages."""
+        self.mqtt_client.loop_start()
+        while True:
+            await asyncio.sleep(0.1)
+
+    def on_mqtt_connect(self, client, userdata, flags, rc):
+        """Subscribe to I/O topics when connected."""
+        client.subscribe("machine/io/start_button")
+        client.subscribe("machine/sensors/box_sensor")
+
+    def on_mqtt_message(self, client, userdata, msg):
+        """Handle incoming MQTT messages and trigger state transitions."""
+        topic = msg.topic
+        payload = msg.payload.decode()
+        
+        # Map MQTT topics to state machine triggers
+        if topic == "machine/io/start_button" and payload == "pressed":
+            self.trigger(Triggers.start_button.value)
+        elif topic == "machine/sensors/box_sensor" and payload == "0":
+            self.trigger(Triggers.box_missing.value)
+
+    @on_enter_state(States.machine.running)
+    def enter_running(self, _):
+        print("🔧 Machine started - processing parts")
+        self.mqtt_client.publish("machine/status", "running")
+
+    @on_enter_state(States.machine.idle)
+    def enter_idle(self, _):
+        print("⏸️ Machine idle - ready for start")
+        self.mqtt_client.publish("machine/status", "idle")
+```
+
+## 📖 API Reference
+
+### StateMachine
+
+```python
+class StateMachine(HierarchicalGraphMachine):
+    def __init__(
+        self,
+        states: Union[object, list[dict[str, Any]], None],
+        *,
+        transitions: Optional[list[dict[str, str]]] = None,
+        history_size: Optional[int] = None,
+        enable_last_state_recovery: bool = True,
+        **kw: Any,
+    )
+```
+
+**Parameters:**
+- `states`: Either a container of StateGroups or a list of state dicts.
+- `transitions`: List of transition dictionaries, or `[]`.
+- `history_size`: Max number of entries in transition history (default 1000).
+- `enable_last_state_recovery`: If True, machine can resume from last recorded state.
+
+### Methods
+
+**`spawn(coro: Coroutine) -> asyncio.Task`**
+Start a background coroutine and track it. Auto-cancelled on fault/reset.
+
+**`cancel_tasks() -> None`**
+Cancel all tracked tasks and timeouts.
+
+**`set_timeout(state_name: str, seconds: float, trigger_fn: Callable[[], str]) -> None`**
+Schedule a trigger if state_name stays active too long.
+
+**`record_last_state() -> None`**
+Save current state for recovery.
+
+**`get_last_state() -> Optional[str]`**
+Return most recently recorded state.
+
+**`start() -> None`**
+Enter machine (recover__... if applicable, else start).
+
+### Properties
+
+**`history -> list[dict[str, Any]]`**
+Full transition history with timestamps/durations.
+
+**`get_last_history_entries(n: int) -> list[dict[str, Any]]`**
+Return last n transitions.
+
+### Decorators
+
+**`@on_enter_state(state: State)`**
+Bind function to run on entry.
+
+**`@on_exit_state(state: State)`**
+Bind function to run on exit.
+
+**`@auto_timeout(seconds: float, trigger: Trigger)`**
+Auto-trigger if timeout expires.
+
+**`@guard(*triggers: Trigger)`**
+Guard transition; blocks if function returns False.
+
+**`@on_state_change`**
+Global callback `(old_state, new_state, trigger)` fired after each transition.
+
+### Router
+
+```python
+def build_router(
+    machine: StateMachine,
+    triggers: Optional[list[Trigger]] = None
+) -> fastapi.APIRouter
+```
+
+Exposes endpoints:
+- `GET /state`
+- `GET /history`
+- `POST /<trigger>`
+- `GET /diagram.svg`
+
+## 🔍 Troubleshooting & FAQ
+
+- **Diagram endpoint returns 503** → Graphviz not installed.
+- **Transitions blocked unexpectedly** → Check guard conditions.
+- **Callbacks not firing** → Only successful transitions trigger them.
+- **State not restored after restart** → Ensure `enable_last_state_recovery=True`.

{vention_state_machine-0.2.0.dist-info → vention_state_machine-0.3.1.dist-info}/RECORD

@@ -7,6 +7,6 @@ state_machine/defs.py,sha256=eYtkTqRMm89ZHFKs3p7H3HyGNZbrOnoCzAJbSeMxSDg,2836
 state_machine/machine_protocols.py,sha256=Yxs4aw2-NJ1RluygbthsquVKn35-xMYae7PB7xlqQmE,826
 state_machine/router.py,sha256=tRJyigrGpQo99_dWGdZ-ZirN50s0CbQF_v4kjAXlpWk,5560
 state_machine/utils.py,sha256=z58CBQCsFWwJzPn8ZhoB2y1K2BH8UP7OZ8XaUx9etN8,1833
-vention_state_machine-0.2.0.dist-info/METADATA,sha256=sScnkkjOabVty6PQWAtsfyaRI8WoN5Fw2rj_jmVr7XM,9972
-vention_state_machine-0.2.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-vention_state_machine-0.2.0.dist-info/RECORD,,
+vention_state_machine-0.3.1.dist-info/METADATA,sha256=EVMmxDmwb67RVbY6N_Ohig5hDLQCCSnOL2M7tSf12DU,10812
+vention_state_machine-0.3.1.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+vention_state_machine-0.3.1.dist-info/RECORD,,

{vention_state_machine-0.2.0.dist-info → vention_state_machine-0.3.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.9.0
+Generator: poetry-core 1.9.1
 Root-Is-Purelib: true
 Tag: py3-none-any

vention_state_machine-0.2.0.dist-info/METADATA

@@ -1,295 +0,0 @@
-Metadata-Version: 2.1
-Name: vention-state-machine
-Version: 0.2.0
-Summary: Declarative state machine framework for machine apps
-License: Proprietary
-Author: VentionCo
-Requires-Python: >=3.9,<3.11
-Classifier: License :: Other/Proprietary License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Requires-Dist: asyncio (>=3.4.3,<4.0.0)
-Requires-Dist: coverage (>=7.10.1,<8.0.0)
-Requires-Dist: fastapi (>=0.116.1,<0.117.0)
-Requires-Dist: graphviz (>=0.21,<0.22)
-Requires-Dist: httpx (>=0.28.1,<0.29.0)
-Requires-Dist: transitions (>=0.9.3,<0.10.0)
-Requires-Dist: uvicorn (>=0.35.0,<0.36.0)
-Description-Content-Type: text/markdown
-
-# vention-state-machine
-
-A lightweight wrapper around `transitions` for building async-safe, recoverable hierarchical state machines with minimal boilerplate.
-
-## ✨ Features
-
-- Built-in `ready` / `fault` states
-- Global transitions: `to_fault`, `reset`
-- Optional state recovery (`recover__state`)
-- Async task spawning and cancellation
-- Timeouts and auto-fault handling
-- Transition history recording with timestamps + durations
-- Guard conditions for blocking transitions
-- Global state change callbacks for logging/MQTT
-
-## 🧠 Domain-Specific Language
-
-This library uses a **declarative domain-specific language (DSL)** to define state machines in a readable and structured way. The key building blocks are:
-
-- **`State`**: Represents a single leaf node in the state machine. Declared as a class attribute.
-    
-- **`StateGroup`**: A container for related states. It generates a hierarchical namespace for its child states (e.g. `MyGroup.my_state` becomes `"MyGroup_my_state"`).
-    
-- **`Trigger`**: Defines a named event that can cause state transitions. It is both callable (returns its name as a string) and composable (can generate transition dictionaries via `.transition(...)`).
-    
-This structure allows you to define states and transitions with strong typing and full IDE support — without strings scattered across your codebase.
-
-For Example: 
-```python
-class MyStates(StateGroup):
-    idle: State = State()
-    working: State = State()
-
-class Triggers:
-    begin = Trigger("begin")
-    finish = Trigger("finish")
-```
-You can then define transitions declaratively:
-```python
-TRANSITIONS = [
-    Triggers.finish.transition(MyStates.working, MyStates.idle),
-]
-```
-
-## 🧱 Base States and Triggers
-
-Every machine comes with built-in:
-
-- **States**:
-  - `ready`: initial state
-  - `fault`: global error state
-- **Triggers**:
-  - `start`: transition into the first defined state
-  - `to_fault`: jump to fault from any state
-  - `reset`: recover from fault back to ready
-
-You can reference these via:
-
-```python
-from state_machine.core import BaseStates, BaseTriggers
-
-state_machine.trigger(BaseTriggers.RESET.value)
-assert state_machine.state == BaseStates.READY.value
-```
-
-## 🚀 Quick Start
-### 1. Define Your States and Triggers
-
-```python
-from state_machine.defs import StateGroup, State, Trigger
-
-class Running(StateGroup):
-	picking: State = State()
-	placing: State = State()
-	homing: State = State()
-
-class States:
-	running = Running()
-
-class Triggers:
-	start = Trigger("start")
-	finished_picking = Trigger("finished_picking")
-	finished_placing = Trigger("finished_placing")
-	finished_homing = Trigger("finished_homing")
-	to_fault = Trigger("to_fault")
-	reset = Trigger("reset")
-```
-
-### 2. Define Transitions
-```python
-TRANSITIONS  = [
-	Triggers.start.transition("ready", States.running.picking),
-	Triggers.finished_picking.transition(States.running.picking, States.running.placing),
-	Triggers.finished_placing.transition(States.running.placing, States.running.homing),
-	Triggers.finished_homing.transition(States.running.homing, States.running.picking)
-]
-```
-
-### 3. Implement Your State Machine
-
-```python
-from state_machine.core import StateMachine
-
-from state_machine.decorators import on_enter_state, auto_timeout, guard, on_state_change
-
-class CustomMachine(StateMachine):
-
-def __init__(self):
-	super().__init__(states=States, transitions=TRANSITIONS)
-
-	# Automatically trigger to_fault after 5s if no progress
-	@on_enter_state(States.running.picking)
-	@auto_timeout(5.0, Triggers.to_fault)
-	def enter_picking(self, _):
-		print("🔹 Entering picking")
-
-	@on_enter_state(States.running.placing)
-	def enter_placing(self, _):
-		print("🔸 Entering placing")
-		
-	@on_enter_state(States.running.homing)
-	def enter_homing(self, _):
-		print("🔺 Entering homing")
-
-	# Guard condition - only allow reset when safety conditions are met
-	@guard(Triggers.reset)
-	def check_safety_conditions(self) -> bool:
-		"""Only allow reset when estop is not pressed."""
-		return not self.estop_pressed
-
-	# Global state change callback for MQTT publishing
-	@on_state_change
-	def publish_state_to_mqtt(self, old_state: str, new_state: str, trigger: str):
-		"""Publish state changes to MQTT."""
-		mqtt_client.publish("machine/state", {
-		    "old_state": old_state,
-		    "new_state": new_state,
-		    "trigger": trigger
-		})
-```
-
-### 4. Start It
-```python
-state_machine = StateMachine()
-state_machine.start() # Enters last recorded state (if recovery enabled), else first state
-```
-
-## 🌐 Optional FastAPI Router
-This library provides a FastAPI-compatible router that automatically exposes your state machine over HTTP. This is useful for:
-
-- Triggering transitions via HTTP POST
-- Inspecting current state and state history
- #### Example
- ```python
-from fastapi import FastAPI
-from state_machine.router import build_router
-from state_machine.core import StateMachine
-
-state_machine = StateMachine(...)
-state_machine.start()
-
-app = FastAPI()
-app.include_router(build_router(state_machine))
-```
-
-### Available Routes
-* `GET /state`: Returns current and last known state
-* `GET /history`: Returns list of recent state transitions
-* `POST /<trigger_name>`: Triggers a transition by name
-
-You can expose only a subset of triggers by passing them explicitly:
-```python
-from state_machine.defs import Trigger
-# Only create endpoints for 'start' and 'reset'
-router = build_router(state_machine, triggers=[Trigger("start"), Trigger("reset")])
-```
-
-## Diagram Visualization
-
-- `GET /diagram.svg`: Returns a Graphviz-generated SVG of the state machine.
-- Current state is highlighted in red.
-- Previous state and the transition taken are highlighted in blue.
-- Requires Graphviz installed on the system. If Graphviz is missing, the endpoint returns 503 Service Unavailable.
-
-Example usage:
-```bash
-curl http://localhost:8000/diagram.svg > machine.svg
-open machine.svg
-```
-
-## 🧪 Testing & History
--  `state_machine.history`: List of all transitions with timestamps and durations
--  `state_machine.last(n)`: Last `n` transitions
--  `state_machine.record_last_state()`: Manually record current state for later recovery
--  `state_machine.get_last_state()`: Retrieve recorded state
-  
-## ⏲ Timeout Example
-Any `on_enter_state` method can be wrapped with `@auto_timeout(seconds, trigger_fn)`, e.g.:
-
-```python
-@auto_timeout(5.0, Triggers.to_fault)
-```
-This automatically triggers `to_fault()` if the state remains active after 5 seconds.
-
-## 🔁 Recovery Example
-Enable `enable_last_state_recovery=True` and use:
-```python
-state_machine.start()
-```
-If a last state was recorded, it will trigger `recover__{last_state}` instead of `start`.
-
-## 🧩 How Decorators Work
-
-Decorators attach metadata to your methods:
-
-- `@on_enter_state(state)` binds to the state's entry callback
-- `@on_exit_state(state)` binds to the state's exit callback
-- `@auto_timeout(seconds, trigger)` schedules a timeout once the state is entered
-- `@guard(trigger)` adds a condition that must be true for the transition to proceed
-- `@on_state_change` registers a global callback that fires on every state transition
-
-The library automatically discovers and wires these up when your machine is initialized.
-
-## 🛡️ Guard Conditions
-
-Guard conditions allow you to block transitions based on runtime conditions. They can be applied to single or multiple triggers:
-
-```python
-# Single trigger
-@guard(Triggers.reset)
-def check_safety_conditions(self) -> bool:
-    """Only allow reset when estop is not pressed."""
-    return not self.estop_pressed
-
-# Multiple triggers - same guard applies to both
-@guard(Triggers.reset, Triggers.start)
-def check_safety_conditions(self) -> bool:
-    """Check safety conditions for both reset and start."""
-    return not self.estop_pressed and self.safety_system_ok
-
-# Multiple guard functions for the same trigger - ALL must pass
-@guard(Triggers.reset)
-def check_estop(self) -> bool:
-    return not self.estop_pressed
-
-@guard(Triggers.reset)
-def check_safety_system(self) -> bool:
-    return self.safety_system_ok
-```
-
-If any guard function returns `False`, the transition is blocked and the state machine remains in its current state. When multiple guard functions are applied to the same trigger, **ALL conditions must pass** for the transition to be allowed.
-
-## 📡 State Change Callbacks
-
-Global state change callbacks are perfect for logging, MQTT publishing, or other side effects. They fire after every successful state transition:
-
-```python
-@on_state_change
-def publish_to_mqtt(self, old_state: str, new_state: str, trigger: str) -> None:
-    """Publish state changes to MQTT."""
-    mqtt_client.publish("machine/state", {
-        "old_state": old_state,
-        "new_state": new_state,
-        "trigger": trigger,
-        "timestamp": datetime.now().isoformat()
-    })
-
-@on_state_change
-def log_transitions(self, old_state: str, new_state: str, trigger: str) -> None:
-    """Log all state transitions."""
-    print(f"State change: {old_state} -> {new_state} (trigger: {trigger})")
-```
-
-Multiple state change callbacks can be registered and they will all be called in the order they were defined. Callbacks only fire on **successful transitions** - blocked transitions (due to guard conditions) do not trigger callbacks.
-```