chartflow 0.1__py3-none-any.whl

chartflow/fsm/__init__.py

@@ -0,0 +1,84 @@
+"""
+QFSM - Quick Finite State Machine Library
+
+A Python 3.14+ finite state machine library with decorators and event system.
+
+Basic Usage:
+    from chartflow.fsm import Stage, Logic, Scheduler
+    from chartflow.fsm.decorators import recursive, listen, sequence
+
+    class MyLogic(Logic):
+        NAME = "MyLogic"
+
+        def initial(self, inst):
+            return "running"
+
+        def running(self, inst):
+            return None
+
+    # Auto-registered with Scheduler
+    logic = MyLogic()
+
+    # Run scheduler
+    scheduler = Scheduler()
+    scheduler.handle()
+"""
+
+from chartflow.fsm.meta import (
+    StageMachineMeta,
+    GetPrototype,
+    ListPrototypes,
+    ClearPrototypes,
+)
+
+from chartflow.fsm.scheduler import Scheduler
+
+from chartflow.fsm.stage import Stage, _NamedNode
+
+from chartflow.fsm.logic import Logic
+
+from chartflow.fsm.decorators import (
+    recursive,
+    listen,
+    behavior,
+    sequence,
+    selector,
+    parallel,
+    process_fsm_markers,
+)
+
+from chartflow.fsm.utils import (
+    EventSystem,
+    GetES,
+)
+
+# Note: chartflow is a standalone library. It intentionally does NOT register its
+# classes into any external registry (e.g. qwork's), so importing chartflow has no
+# side effects on other libraries. If you want chartflow classes in a registry,
+# call the registry's register API explicitly from your application code.
+
+
+__version__ = '0.1.0'
+__all__ = [
+    # Core classes
+    'StageMachineMeta',
+    'Scheduler',
+    'Stage',
+    'Logic',
+    '_NamedNode',
+    # Decorators
+    'recursive',
+    'listen',
+    'behavior',
+    'sequence',
+    'selector',
+    'parallel',
+    'process_fsm_markers',
+    # Events
+    'EventSystem',
+    'GetES',
+    # Utility functions
+    'GetPrototype',
+    'ListPrototypes',
+    'ClearPrototypes',
+]

chartflow/fsm/decorators.py

@@ -0,0 +1,395 @@
+from __future__ import annotations
+"""
+QFSM Decorators - Finite State Machine decorators for Python 3.14+
+
+This module provides decorators for marking states with various behaviors
+in a finite state machine system.
+"""
+
+
+import functools
+from typing import Any, Callable, Concatenate, ParamSpec, TypeVar
+
+# Type variables for better type inference
+P = ParamSpec('P')
+R = TypeVar('R')
+T = TypeVar('T')
+
+
+class _StateMarker:
+    """Base descriptor for state markers using descriptor protocol."""
+    
+    def __init__(self, attr_name: str, value: Any) -> None:
+        self.attr_name = attr_name
+        self.value = value
+    
+    def __set_name__(self, owner: type, name: str) -> None:
+        # Initialize the class-level attribute when descriptor is assigned
+        if not hasattr(owner, self.attr_name):
+            setattr(owner, self.attr_name, set() if isinstance(self.value, set) else {})
+        
+        # Add this method to the marker set/dict
+        marker = getattr(owner, self.attr_name)
+        if isinstance(marker, set):
+            marker.add(name)
+        elif isinstance(marker, dict):
+            marker[name] = self.value
+    
+    def __get__(self, instance: Any, owner: type) -> Any:
+        return self.value
+    
+    def __set__(self, instance: Any, value: Any) -> None:
+        raise AttributeError(f"Cannot modify {self.attr_name} marker")
+
+
+class _RecursiveDescriptor:
+    """Descriptor that marks a method as recursive (can execute multiple times per tick)."""
+    
+    def __set_name__(self, owner: type, name: str) -> None:
+        if not hasattr(owner, '__recursive__'):
+            owner.__recursive__ = set()
+        owner.__recursive__.add(name)
+    
+    def __get__(self, instance: Any, owner: type) -> bool:
+        return True
+
+
+class _ListenDescriptor:
+    """Descriptor that marks a method as an event listener."""
+    
+    def __init__(self, event_name: str, sources: tuple[str, ...]) -> None:
+        self.event_name = event_name
+        self.sources = sources
+    
+    def __set_name__(self, owner: type, name: str) -> None:
+        if not hasattr(owner, '__listens__'):
+            owner.__listens__ = {}
+        
+        if self.event_name not in owner.__listens__:
+            owner.__listens__[self.event_name] = []
+        
+        owner.__listens__[self.event_name].append((name, self.sources))
+    
+    def __get__(self, instance: Any, owner: type) -> tuple[str, tuple[str, ...]]:
+        return (self.event_name, self.sources)
+
+
+class _BehaviorDescriptor:
+    """Descriptor that marks a state with transition behavior."""
+    
+    def __init__(self, target: str | None = None, 
+                 children: list[str] | None = None,
+                 composite: str | None = None) -> None:
+        self.target = target
+        self.children = children
+        self.composite = composite
+    
+    def __set_name__(self, owner: type, name: str) -> None:
+        if not hasattr(owner, '__behaviors__'):
+            owner.__behaviors__ = {}
+        
+        if self.children is not None:
+            # Composite behavior
+            owner.__behaviors__[name] = {
+                'children': self.children,
+                'composite': self.composite
+            }
+        else:
+            # Simple behavior
+            owner.__behaviors__[name] = {
+                'children': self.target,
+                'composite': None
+            }
+    
+    def __get__(self, instance: Any, owner: type) -> dict[str, Any]:
+        if self.children is not None:
+            return {'children': self.children, 'composite': self.composite}
+        return {'children': self.target, 'composite': None}
+
+
+# =============================================================================
+# Public Decorators
+# =============================================================================
+
+def recursive(method: Callable[Concatenate[T, P], R]) -> Callable[Concatenate[T, P], R]:
+    """
+    Marks a state method as recursive.
+    
+    Recursive states can be called multiple times per tick until they
+    return a new state transition.
+    
+    The marked method name is stored in class.__recursive__ set.
+    
+    Example:
+        class MyFSM:
+            @recursive
+            def processing(self):
+                # This can be called multiple times per tick
+                return self.next_state
+    """
+    @functools.wraps(method)
+    def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+        return method(self, *args, **kwargs)
+    
+    # Mark the wrapper with the recursive descriptor
+    wrapper._recursive_marker = True
+    wrapper.__name__ = method.__name__
+    wrapper.__doc__ = method.__doc__
+    
+    return wrapper
+
+
+def listen(event_name: str, *sources: str) -> Callable[[Callable[Concatenate[T, P], R]], Callable[Concatenate[T, P], R]]:
+    """
+    Marks a method as an event listener.
+    
+    Args:
+        event_name: The name of the event to listen for
+        *sources: Optional source filters for the event
+    
+    The listener info is stored in class.__listens__ as:
+        {event_name: [(func_name, sources), ...]}
+    
+    Example:
+        class MyFSM:
+            @listen('player_died', 'game', 'combat')
+            def on_player_died(self, data):
+                print(f"Player died: {data}")
+    """
+    def decorator(method: Callable[Concatenate[T, P], R]) -> Callable[Concatenate[T, P], R]:
+        @functools.wraps(method)
+        def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+            return method(self, *args, **kwargs)
+
+        if method.__name__.startswith("_"):
+            raise ValueError(
+                f"[def] Cannot @listen method with name startswith '_'. ('{method.__name__}')"
+            )
+
+        # Store listen metadata on the wrapper
+        wrapper._listen_event = event_name
+        wrapper._listen_sources = sources
+        wrapper.__name__ = method.__name__
+        wrapper.__doc__ = method.__doc__
+        
+        return wrapper
+    
+    return decorator
+
+
+def behavior(target: str) -> Callable[[Callable[Concatenate[T, P], R]], Callable[Concatenate[T, P], R]]:
+    """
+    Marks a simple state transition behavior.
+    
+    Args:
+        target: The target state name to transition to
+    
+    The behavior is stored in class.__behaviors__ as:
+        {state_name: {'children': target, 'composite': None}}
+    
+    Example:
+        class MyFSM:
+            @behavior('running')
+            def idle(self):
+                pass  # Will transition to 'running'
+    """
+    def decorator(method: Callable[Concatenate[T, P], R]) -> Callable[Concatenate[T, P], R]:
+        @functools.wraps(method)
+        def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+            return method(self, *args, **kwargs)
+        
+        # Store behavior metadata
+        wrapper._behavior_target = target
+        wrapper._behavior_composite = None
+        wrapper.__name__ = method.__name__
+        wrapper.__doc__ = method.__doc__
+        
+        return wrapper
+    
+    return decorator
+
+
+def sequence(*states: str) -> Callable[[Callable[Concatenate[T, P], R]], Callable[Concatenate[T, P], R]]:
+    """
+    Marks a sequence composite behavior.
+    
+    A sequence executes all child states in order and fails if any child fails.
+    
+    Args:
+        *states: The child state names to execute in sequence
+    
+    The behavior is stored in class.__behaviors__ as:
+        {state_name: {'children': [...], 'composite': 'sequence'}}
+    
+    Example:
+        class MyFSM:
+            @sequence('approach', 'attack', 'retreat')
+            def combat_sequence(self):
+                pass  # Executes approach, then attack, then retreat
+    """
+    def decorator(method: Callable[Concatenate[T, P], R]) -> Callable[Concatenate[T, P], R]:
+        @functools.wraps(method)
+        def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+            return method(self, *args, **kwargs)
+        
+        # Store sequence metadata
+        wrapper._behavior_children = list(states)
+        wrapper._behavior_composite = 'sequence'
+        wrapper.__name__ = method.__name__
+        wrapper.__doc__ = method.__doc__
+        
+        return wrapper
+    
+    return decorator
+
+
+def selector(*states: str) -> Callable[[Callable[Concatenate[T, P], R]], Callable[Concatenate[T, P], R]]:
+    """
+    Marks a selector composite behavior.
+    
+    A selector executes child states until one succeeds (returns a truthy value).
+    
+    Args:
+        *states: The child state names to try in order
+    
+    The behavior is stored in class.__behaviors__ as:
+        {state_name: {'children': [...], 'composite': 'selector'}}
+    
+    Example:
+        class MyFSM:
+            @selector('attack_melee', 'attack_ranged', 'flee')
+            def choose_attack(self):
+                pass  # Tries melee, then ranged, then flees
+    """
+    def decorator(method: Callable[Concatenate[T, P], R]) -> Callable[Concatenate[T, P], R]:
+        @functools.wraps(method)
+        def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+            return method(self, *args, **kwargs)
+        
+        # Store selector metadata
+        wrapper._behavior_children = list(states)
+        wrapper._behavior_composite = 'selector'
+        wrapper.__name__ = method.__name__
+        wrapper.__doc__ = method.__doc__
+        
+        return wrapper
+    
+    return decorator
+
+
+def parallel(*states: str) -> Callable[[Callable[Concatenate[T, P], R]], Callable[Concatenate[T, P], R]]:
+    """
+    Marks a parallel composite behavior.
+    
+    A parallel executes all child states and succeeds if any succeeds.
+    
+    Args:
+        *states: The child state names to execute in parallel
+    
+    The behavior is stored in class.__behaviors__ as:
+        {state_name: {'children': [...], 'composite': 'parallel'}}
+    
+    Example:
+        class MyFSM:
+            @parallel('check_enemies', 'check_allies', 'check_obstacles')
+            def assess_situation(self):
+                pass  # Runs all checks in parallel
+    """
+    def decorator(method: Callable[Concatenate[T, P], R]) -> Callable[Concatenate[T, P], R]:
+        @functools.wraps(method)
+        def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+            return method(self, *args, **kwargs)
+        
+        # Store parallel metadata
+        wrapper._behavior_children = list(states)
+        wrapper._behavior_composite = 'parallel'
+        wrapper.__name__ = method.__name__
+        wrapper.__doc__ = method.__doc__
+        
+        return wrapper
+    
+    return decorator
+
+
+# =============================================================================
+# Class Decorator for Processing Markers
+# =============================================================================
+
+def process_fsm_markers(cls: type[T]) -> type[T]:
+    """
+    Class decorator that processes all FSM markers on methods.
+    
+    This should be applied to any class using the FSM decorators to ensure
+    the __recursive__, __listens__, and __behaviors__ attributes are properly
+    populated.
+    
+    Example:
+        @process_fsm_markers
+        class MyFSM:
+            @recursive
+            def processing(self): ...
+            
+            @listen('event')
+            def on_event(self, data): ...
+    """
+    # Initialize class-level attributes if not present
+    if not hasattr(cls, '__recursive__'):
+        cls.__recursive__ = set()
+    if not hasattr(cls, '__listens__'):
+        cls.__listens__ = {}
+    if not hasattr(cls, '__behaviors__'):
+        cls.__behaviors__ = {}
+    
+    # Scan all methods for markers
+    for name in dir(cls):
+        if name.startswith('_'):
+            continue
+        
+        try:
+            attr = getattr(cls, name)
+        except AttributeError:
+            continue
+        
+        if not callable(attr):
+            continue
+        
+        # Check for recursive marker
+        if hasattr(attr, '_recursive_marker'):
+            cls.__recursive__.add(name)
+        
+        # Check for listen marker
+        if hasattr(attr, '_listen_event'):
+            event = attr._listen_event
+            sources = attr._listen_sources
+            if event not in cls.__listens__:
+                cls.__listens__[event] = []
+            cls.__listens__[event].append((name, sources))
+        
+        # Check for behavior marker
+        if hasattr(attr, '_behavior_target'):
+            cls.__behaviors__[name] = {
+                'children': attr._behavior_target,
+                'composite': None
+            }
+        elif hasattr(attr, '_behavior_children'):
+            cls.__behaviors__[name] = {
+                'children': attr._behavior_children,
+                'composite': attr._behavior_composite
+            }
+    
+    return cls
+
+
+# =============================================================================
+# Convenience Exports
+# =============================================================================
+
+__all__ = [
+    'recursive',
+    'listen',
+    'behavior',
+    'sequence',
+    'selector',
+    'parallel',
+    'process_fsm_markers',
+]