semantic-state-machine 0.1.0__tar.gz

semantic_state_machine-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.3
+Name: semantic-state-machine
+Version: 0.1.0
+Summary: A lightweight, type-safe Python state machine implementation using modern Python 3.13+ features.
+Keywords: state-machine,finite-state-machine,type-safety,audit
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/rjdw/semantic-state-machine
+Project-URL: Repository, https://github.com/rjdw/semantic-state-machine
+Project-URL: Issues, https://github.com/rjdw/semantic-state-machine/issues
+Description-Content-Type: text/markdown
+
+# State Machine
+
+A lightweight, type-safe Python state machine implementation using modern Python 3.13+ features like PEP 695 type parameters.
+
+## Features
+
+- **Type Safety**: Leverage Python's type system to ensure consistent states, events, and contexts.
+- **Decorator Support**: Easily define transitions using the `@sm.transition` decorator.
+- **Auditing**: Built-in support for recording transition history via `AuditedStateMachine` and `AuditContext`.
+- **Flexible Context**: Pass a custom context object to transition actions to maintain state outside the machine.
+
+## Installation
+
+This project uses `uv` for dependency management. To get started, ensure you have `uv` installed and run:
+
+```bash
+uv sync
+```
+
+You can install the package via pip:
+
+```bash
+pip install semantic-state-machine
+```
+
+## Usage
+
+### Basic State Machine
+
+Define your states and events as `Enum`s and create a context class.
+
+```python
+from enum import Enum
+from semantic_state_machine import StateMachine
+
+class State(Enum):
+    LOCKED = 1
+    UNLOCKED = 2
+
+class Event(Enum):
+    PUSH = 1
+    COIN = 2
+
+class TurnstileContext:
+    def __init__(self):
+        self.total_coins = 0
+
+sm = StateMachine[State, Event, TurnstileContext]()
+
+@sm.transition(State.LOCKED, Event.COIN, State.UNLOCKED)
+def insert_coin(ctx: TurnstileContext):
+    ctx.total_coins += 1
+    print("Coin inserted. Turnstile unlocked.")
+
+@sm.transition(State.UNLOCKED, Event.PUSH, State.LOCKED)
+def push_turnstile(ctx: TurnstileContext):
+    print("Turnstile pushed. Turnstile locked.")
+
+# Usage
+ctx = TurnstileContext()
+current_state = State.LOCKED
+current_state = sm.handle_transition(ctx, current_state, Event.COIN)
+# current_state is now State.UNLOCKED
+```
+
+### Audited State Machine
+
+Use `AuditedStateMachine` and `AuditContext` to automatically track the history of transitions.
+
+```python
+from semantic_state_machine import AuditedStateMachine, AuditContext
+
+class MyContext(AuditContext[State, Event]):
+    pass
+
+sm = AuditedStateMachine[State, Event, MyContext]()
+
+# Transitions are defined the same way
+@sm.transition(State.LOCKED, Event.COIN, State.UNLOCKED)
+def insert_coin(ctx: MyContext):
+    pass
+
+ctx = MyContext()
+sm.handle_transition(ctx, State.LOCKED, Event.COIN)
+
+# The transition is automatically recorded
+print(ctx._audit)  # [(State.LOCKED, Event.COIN)]
+```
+
+## Testing
+
+The project includes a comprehensive suite of unit and integration tests.
+
+### Run All Tests
+```bash
+uv run pytest tests/
+```
+
+### Run with Coverage
+```bash
+uv run pytest --cov=src tests/
+```
+
+The current implementation maintains **100% code coverage** across the core logic and integration workflows.
+
+## Project Structure
+
+- `src/semantic_state_machine/`: Core implementation.
+- `tests/unit/`: Focused unit tests for individual components.
+- `tests/integration/`: End-to-end workflow simulations.

semantic_state_machine-0.1.0/README.md

@@ -0,0 +1,110 @@
+# State Machine
+
+A lightweight, type-safe Python state machine implementation using modern Python 3.13+ features like PEP 695 type parameters.
+
+## Features
+
+- **Type Safety**: Leverage Python's type system to ensure consistent states, events, and contexts.
+- **Decorator Support**: Easily define transitions using the `@sm.transition` decorator.
+- **Auditing**: Built-in support for recording transition history via `AuditedStateMachine` and `AuditContext`.
+- **Flexible Context**: Pass a custom context object to transition actions to maintain state outside the machine.
+
+## Installation
+
+This project uses `uv` for dependency management. To get started, ensure you have `uv` installed and run:
+
+```bash
+uv sync
+```
+
+You can install the package via pip:
+
+```bash
+pip install semantic-state-machine
+```
+
+## Usage
+
+### Basic State Machine
+
+Define your states and events as `Enum`s and create a context class.
+
+```python
+from enum import Enum
+from semantic_state_machine import StateMachine
+
+class State(Enum):
+    LOCKED = 1
+    UNLOCKED = 2
+
+class Event(Enum):
+    PUSH = 1
+    COIN = 2
+
+class TurnstileContext:
+    def __init__(self):
+        self.total_coins = 0
+
+sm = StateMachine[State, Event, TurnstileContext]()
+
+@sm.transition(State.LOCKED, Event.COIN, State.UNLOCKED)
+def insert_coin(ctx: TurnstileContext):
+    ctx.total_coins += 1
+    print("Coin inserted. Turnstile unlocked.")
+
+@sm.transition(State.UNLOCKED, Event.PUSH, State.LOCKED)
+def push_turnstile(ctx: TurnstileContext):
+    print("Turnstile pushed. Turnstile locked.")
+
+# Usage
+ctx = TurnstileContext()
+current_state = State.LOCKED
+current_state = sm.handle_transition(ctx, current_state, Event.COIN)
+# current_state is now State.UNLOCKED
+```
+
+### Audited State Machine
+
+Use `AuditedStateMachine` and `AuditContext` to automatically track the history of transitions.
+
+```python
+from semantic_state_machine import AuditedStateMachine, AuditContext
+
+class MyContext(AuditContext[State, Event]):
+    pass
+
+sm = AuditedStateMachine[State, Event, MyContext]()
+
+# Transitions are defined the same way
+@sm.transition(State.LOCKED, Event.COIN, State.UNLOCKED)
+def insert_coin(ctx: MyContext):
+    pass
+
+ctx = MyContext()
+sm.handle_transition(ctx, State.LOCKED, Event.COIN)
+
+# The transition is automatically recorded
+print(ctx._audit)  # [(State.LOCKED, Event.COIN)]
+```
+
+## Testing
+
+The project includes a comprehensive suite of unit and integration tests.
+
+### Run All Tests
+```bash
+uv run pytest tests/
+```
+
+### Run with Coverage
+```bash
+uv run pytest --cov=src tests/
+```
+
+The current implementation maintains **100% code coverage** across the core logic and integration workflows.
+
+## Project Structure
+
+- `src/semantic_state_machine/`: Core implementation.
+- `tests/unit/`: Focused unit tests for individual components.
+- `tests/integration/`: End-to-end workflow simulations.

semantic_state_machine-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "semantic-state-machine"
+version = "0.1.0"
+description = "A lightweight, type-safe Python state machine implementation using modern Python 3.13+ features."
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = []
+keywords = ["state-machine", "finite-state-machine", "type-safety", "audit"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+license = { text = "MIT" }
+
+[project.urls]
+Homepage = "https://github.com/rjdw/semantic-state-machine"
+Repository = "https://github.com/rjdw/semantic-state-machine"
+Issues = "https://github.com/rjdw/semantic-state-machine/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "pytest-gitignore>=1.3",
+    "pytest-html-plus>=0.5.2",
+    "pytest-isort>=4.0.0",
+    "pytest-randomly>=4.0.1",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.15.10",
+    "ty>=0.0.29",
+]

semantic_state_machine-0.1.0/src/semantic_state_machine/__init__.py

@@ -0,0 +1,17 @@
+from .state_machine import (
+    Action,
+    AuditContext,
+    AuditedStateMachine,
+    InvalidTransition,
+    StateMachine,
+    Transition,
+)
+
+__all__ = [
+    "Action",
+    "AuditContext",
+    "AuditedStateMachine",
+    "InvalidTransition",
+    "StateMachine",
+    "Transition",
+]

semantic_state_machine-0.1.0/src/semantic_state_machine/state_machine.py

@@ -0,0 +1,180 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable, Iterable, cast
+
+type Action[C] = Callable[[C], None]
+"""A callable that performs an action on a context object."""
+
+type Transition[S: Enum, E: Enum, C] = dict[tuple[S, E], tuple[S, Action[C]]]
+"""A mapping of (state, event) to (target_state, action)."""
+
+
+@dataclass
+class AuditContext[S: Enum, E: Enum]:
+    """A context class that records the history of state transitions.
+
+    Args:
+        S: The Enum type representing the states.
+        E: The Enum type representing the events.
+
+    Notes:
+        Architectural Intent: Provides a standardized mixin for state machine
+        contexts that require auditing capabilities. It is designed to be
+        inherited by user-defined context classes.
+    """
+
+    _audit: list[tuple[S, E]] = field(default_factory=list)
+
+    def record_transition(self, from_state: S, event: E) -> None:
+        """Records a transition from a given state triggered by an event.
+
+        Args:
+            from_state: The state the machine is transitioning from.
+            event: The event that triggered the transition.
+        """
+        self._audit.append((from_state, event))
+
+
+class InvalidTransition(Exception):
+    """Raised when a transition is not defined for a given state and event."""
+
+    pass
+
+
+@dataclass
+class StateMachine[S: Enum, E: Enum, C]:
+    """A lightweight, type-safe state machine.
+
+    The state machine is stateless; the current state must be managed externally
+    and passed to the `handle_transition` method.
+
+    Args:
+        S: The Enum type representing the states.
+        E: The Enum type representing the events.
+        C: The type of the context object passed to actions.
+
+    Notes:
+        Architectural Intent: Leverages PEP 695 type parameters to ensure
+        strict type safety across states, events, and context objects without
+        sacrificing flexibility.
+    """
+
+    _transitions: Transition[S, E, C] = field(default_factory=dict)
+
+    def add_transition(
+        self, from_state: S, event: E, to_state: S, func: Action[C]
+    ) -> None:
+        """Manually registers a transition between states.
+
+        Args:
+            from_state: The starting state for the transition.
+            event: The event that triggers the transition.
+            to_state: The target state after the transition.
+            func: The action to execute during the transition.
+        """
+        self._transitions[(from_state, event)] = (to_state, func)
+
+    def handle_transition(self, ctx: C, from_state: S, event: E) -> S:
+        """Executes a transition and returns the new state.
+
+        Args:
+            ctx: The context object to pass to the transition's action.
+            from_state: The current state of the machine.
+            event: The event to process.
+
+        Returns:
+            S: The new state of the machine.
+
+        Raises:
+            InvalidTransition: If the transition is not defined for the
+                given state and event.
+        """
+        to_state, action = self._next_transition(from_state, event)
+        action(ctx)
+        return to_state
+
+    def _next_transition(self, from_state: S, event: E) -> tuple[S, Action[C]]:
+        """Internal helper to retrieve the next transition.
+
+        Args:
+            from_state: The current state.
+            event: The event.
+
+        Returns:
+            tuple[S, Action[C]]: A tuple of (target_state, action).
+
+        Raises:
+            InvalidTransition: If the transition key is missing.
+        """
+        try:
+            return self._transitions[(from_state, event)]
+        except KeyError as e:
+            raise InvalidTransition(
+                f"Cannot {event.name} when {from_state.name}"
+            ) from e
+
+    def transition(
+        self, from_state: S | Iterable[S], event: E, to_state: S
+    ) -> Callable[[Action[C]], Action[C]]:
+        """A decorator to register a transition for a function.
+
+        Args:
+            from_state: A single state or an iterable of states that can
+                trigger this transition.
+            event: The event that triggers the transition.
+            to_state: The target state after the transition.
+
+        Returns:
+            Callable[[Action[C]], Action[C]]: The decorator function.
+
+        Notes:
+            Architectural Intent: Allows for a declarative way to map
+            multiple source states to a single target state and action.
+        """
+        states: list[S]
+        if isinstance(from_state, Enum):
+            states = [cast(S, from_state)]
+        else:
+            states = list(cast(Iterable[S], from_state))
+
+        def decorator(func: Action[C]) -> Action[C]:
+            for s in states:
+                self.add_transition(s, event, to_state, func)
+            return func
+
+        return decorator
+
+
+@dataclass
+class AuditedStateMachine[S: Enum, E: Enum, C: AuditContext](StateMachine[S, E, C]):
+    """A state machine that automatically records transitions in the context.
+
+    Requires a context that inherits from `AuditContext`.
+
+    Args:
+        S: The Enum type representing the states.
+        E: The Enum type representing the events.
+        C: A context type that implements `AuditContext`.
+
+    Notes:
+        Architectural Intent: Simplifies auditing by automatically calling
+        `record_transition` on the context before executing the standard
+        transition logic.
+    """
+
+    def handle_transition(self, ctx: C, from_state: S, event: E) -> S:
+        """Records the transition and then executes it.
+
+        Args:
+            ctx: The audit context.
+            from_state: The current state.
+            event: The event to process.
+
+        Returns:
+            S: The new state.
+
+        Raises:
+            InvalidTransition: If the transition is not defined.
+        """
+        ctx.record_transition(from_state, event)
+        return super().handle_transition(ctx, from_state, event)