xstate-statemachine 0.1.0__py3-none-any.whl

xstate_statemachine/__init__.py

@@ -0,0 +1,31 @@
+# src/xstate_statemachine/__init__.py
+
+__version__ = "0.2.0"  # Version bump for new features
+
+from .factory import create_machine
+from .interpreter import Interpreter
+from .machine_logic import MachineLogic
+from .events import Event
+from .plugins import PluginBase, LoggingInspector
+from .exceptions import (
+    XStateMachineError,
+    InvalidConfigError,
+    StateNotFoundError,
+    ImplementationMissingError,
+    ActorSpawningError,
+)
+
+# This is the public API of the library.
+__all__ = [
+    "create_machine",
+    "Interpreter",
+    "MachineLogic",
+    "Event",
+    "PluginBase",
+    "LoggingInspector",
+    "XStateMachineError",
+    "InvalidConfigError",
+    "StateNotFoundError",
+    "ImplementationMissingError",
+    "ActorSpawningError",
+]

xstate_statemachine/events.py

@@ -0,0 +1,39 @@
+# src/xstate_statemachine/events.py
+from typing import Any, Dict, Literal, NamedTuple
+
+
+# -----------------------------------------------------------------------------
+# ✉️ Event Definitions
+# -----------------------------------------------------------------------------
+# Standardizing event structures within the machine ensures consistency and
+# clear communication between components.
+# -----------------------------------------------------------------------------
+
+
+class Event(NamedTuple):
+    """Represents an event sent to the machine."""
+
+    type: str
+    payload: Dict[str, Any] = {}
+
+
+class DoneEvent(NamedTuple):
+    """
+    Represents the completion of an invoked service.
+
+    The type follows the convention 'done.invoke.<service_id>'.
+    """
+
+    type: str
+    data: Any
+    src: str
+
+
+class AfterEvent(NamedTuple):
+    """
+    Represents the firing of a delayed transition.
+
+    The type follows the convention 'after.<delay>.<state_id>'.
+    """
+
+    type: str

xstate_statemachine/exceptions.py

@@ -0,0 +1,43 @@
+# src/xstate_statemachine/exceptions.py
+
+# -----------------------------------------------------------------------------
+# 🚨 Custom Exceptions
+# -----------------------------------------------------------------------------
+# Defining specific exceptions improves error handling and makes the library's
+# failure modes clearer to the user.
+# -----------------------------------------------------------------------------
+
+
+class XStateMachineError(Exception):
+    """Base exception for all errors raised by this library."""
+
+    pass
+
+
+class InvalidConfigError(XStateMachineError):
+    """Raised when the machine configuration JSON is invalid."""
+
+    pass
+
+
+class StateNotFoundError(XStateMachineError):
+    """Raised when a target state cannot be resolved."""
+
+    def __init__(self, target: str, reference_id: str):
+        self.target = target
+        self.reference_id = reference_id
+        super().__init__(
+            f"Could not resolve target state '{target}' from state '{reference_id}'."
+        )
+
+
+class ImplementationMissingError(XStateMachineError):
+    """Raised when an action, guard, or service implementation is missing."""
+
+    pass
+
+
+class ActorSpawningError(XStateMachineError):
+    """Raised when there is an error spawning or communicating with an actor."""
+
+    pass

xstate_statemachine/factory.py

@@ -0,0 +1,46 @@
+# src/xstate_statemachine/factory.py
+from typing import Any, Dict
+from .models import MachineNode
+from .machine_logic import MachineLogic
+from .exceptions import InvalidConfigError
+from .logger import logger
+
+# -----------------------------------------------------------------------------
+# 🏭 Machine Factory
+# -----------------------------------------------------------------------------
+# This module provides a single entry point for creating a state machine
+# instance from its configuration, applying the Factory design pattern.
+# -----------------------------------------------------------------------------
+
+
+def create_machine(
+    config: Dict[str, Any], logic: MachineLogic = None
+) -> MachineNode:
+    """
+    Creates a state machine instance from a JSON-like config and implementation logic.
+
+    Args:
+        config: The state machine's definition.
+        logic: An object containing the implementations for all actions, guards, etc.
+
+    Returns:
+        The root node of the fully constructed state machine graph.
+
+    Raises:
+        InvalidConfigError: If the configuration is malformed.
+    """
+    if logic is None:
+        logic = MachineLogic()
+
+    machine_id = config.get("id")
+    logger.info(f"🏭 Creating machine with id: '{machine_id}'")
+    if (
+        not isinstance(config, dict)
+        or "states" not in config
+        or not machine_id
+    ):
+        raise InvalidConfigError(
+            "Invalid config: must be a dict with 'id' and 'states' keys."
+        )
+
+    return MachineNode(config, logic)