chartflow 0.1__py3-none-any.whl

chartflow/fsm/meta.py

@@ -0,0 +1,569 @@
+from __future__ import annotations
+"""
+qfsm - Finite State Machine Metaclass
+
+This module provides the StageMachineMeta metaclass for automatic state discovery,
+class registration, and inheritance handling for state machines.
+"""
+
+
+import inspect
+import weakref
+from collections.abc import Callable
+from typing import Any, ClassVar, Final, Self, TypeAlias
+
+# Global prototype registry for all state machine classes
+__protos__: dict[str, type] = {}
+
+# Methods to ignore when discovering states
+IGNORES: Final[frozenset[str]] = frozenset({
+    'ref', 'refLast', 'refNext', 'refAdjacent', 'refEnd', 'refHead',
+    'link', 'transform', 'listenFor', 'cancelListen', 'pushEvent',
+    'schedule', 'cancelSchedule', 'handleStage', 'onStart', 'onStop',
+    'onStep', 'onChanged', 'onKilled', 'onDraw', 'onLoading',
+    'productQueue', 'showQueue', 'jumpQueue', 'accelerate',
+    'goto', 'kill', 'enable', 'disable'
+})
+
+# Base classes that should not be registered
+BASE_CLASSES: Final[frozenset[str]] = frozenset({'Stage', 'Logic'})
+
+# Type aliases for class attribute structures
+StateList: TypeAlias = list[str]
+RecursiveSet: TypeAlias = set[str]
+ListenDict: TypeAlias = dict[str, list[tuple[str, tuple[str, ...]]]]
+BehaviorDict: TypeAlias = dict[str, dict[str, Any]]
+
+
+class StageMachineMeta(type):
+    """
+    Metaclass for finite state machines with automatic state discovery.
+    
+    Features:
+    - Automatic discovery of state methods (callable, non-private, non-UPPERCASE, not in IGNORES)
+    - Class registration to global __protos__ registry
+    - Inheritance of __states__, __recursive__, __listens__, __behaviors__
+    - Tracking of decorator-marked methods
+    
+    Class Attributes Created:
+        __states__: List of discovered state method names
+        __recursive__: Set of recursive state names
+        __listens__: Dict of event listeners {event_name: [(func_name, sources), ...]}
+        __behaviors__: Dict of behavior tree nodes {state_name: {children: ..., composite: ...}}
+    """
+    __ID_PROTOS__ = {}
+    __INSTANCES__ = {}
+    IGNORES = IGNORES
+
+
+    @staticmethod
+    def _remove_ref(_ref):
+        for _name, _d in list(StageMachineMeta.__INSTANCES__.items()):
+            for _id, _r in list(_d.items()):
+                if _r is _ref:
+                    _d.pop(_id, None)
+                    if not _d:
+                        StageMachineMeta.__INSTANCES__.pop(_name, None)
+                    return
+
+
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        **kwargs: Any
+    ) -> Self:
+        """
+        Create a new state machine class with automatic state discovery.
+        
+        Args:
+            name: Class name
+            bases: Base classes
+            namespace: Class namespace
+            **kwargs: Additional keyword arguments
+            
+        Returns:
+            New class instance
+        """
+        # Create the class first
+        cls = super().__new__(mcs, name, bases, namespace)
+        
+        # Discover states from current class namespace
+        _extra_ignores = set(namespace.get('IGNORES', []))
+        current_states = mcs._discover_states(namespace, _extra_ignores)
+        
+        # Inherit and merge attributes from base classes
+        cls.__states__ = mcs._merge_states(bases, current_states)
+        cls.__recursive__ = mcs._merge_recursive(bases, namespace)
+        cls.__listens__ = mcs._merge_listens(bases, namespace)
+        cls.__behaviors__ = mcs._merge_behaviors(bases, namespace)
+
+        # Validate behavior children exist (must happen after states and behaviors are set)
+        mcs._validate_behaviors(cls, name, current_states)
+
+        # Calculate max state name length for aligned output
+        if cls.__states__:
+            cls.__max_state_len__ = max(len(s) for s in cls.__states__)
+        else:
+            cls.__max_state_len__ = 0
+
+        # Register class if it has a NAME and is not a base class
+        mcs._register_class(cls, name)
+        
+        return cls
+
+
+    def __call__(cls, *args, **kwargs):
+        _skip_proto = getattr(cls, '__no_proto_call__', False)
+        if len(args) and isinstance(args[0], str) and not _skip_proto:
+            prototype = StageMachineMeta.proto(args[0])
+            if prototype is None:
+                raise TypeError(
+                    f"[{cls.__name__}]: The given prototype name '{args[0]}' is not defined.\n\t* Please make sure import that file.")
+            return prototype(*args[1:], **kwargs)
+        instance = cls.__new__(cls, *args, **kwargs)
+        if isinstance(instance, cls):
+            instance.__init__(*args, **kwargs)
+            _name = getattr(instance, 'NAME', None)
+            if _name is not None:
+                _uid = getattr(instance, '_uid', id(instance))
+                ref = weakref.ref(instance, StageMachineMeta._remove_ref)
+                StageMachineMeta.__INSTANCES__.setdefault(_name, {})[_uid] = ref
+        return instance
+
+    @staticmethod
+    def _discover_states(namespace: dict[str, Any], extra_ignores: set[str] | None = None) -> StateList:
+        """
+        Discover state methods from class namespace.
+
+        A method is considered a state if:
+        - It's callable
+        - Doesn't start with '_' (not private)
+        - Is not ALL UPPERCASE constant (lambda assignment)
+        - Is not in the IGNORES list
+        - Is not marked with @listen decorator
+
+        Args:
+            namespace: Class namespace dictionary
+            extra_ignores: Additional method names to ignore (from class-level IGNORES)
+
+        Returns:
+            List of discovered state method names
+        """
+        _ignores = IGNORES | (extra_ignores or set())
+
+        def _is_method(name: str, obj: Any) -> bool:
+            """Check if obj is a method defined in this class (not lambda assignment)."""
+            if not callable(obj):
+                return False
+            if name.startswith('_'):
+                return False
+            if name in _ignores:
+                return False
+            if isinstance(obj, (staticmethod, classmethod)):
+                return False
+            if hasattr(obj, '_listen_event'):
+                return False
+            # Exclude ALL UPPERCASE method names (treat as constants)
+            if name.isupper():
+                return False
+            return True
+
+        return [
+            name for name, obj in namespace.items()
+            if _is_method(name, obj)
+        ]
+
+    @staticmethod
+    def _merge_states(bases: tuple[type, ...], current_states: StateList) -> StateList:
+        """
+        Merge states from base classes with current class states.
+        
+        Base class states come first, then current class states.
+        Preserves order and removes duplicates.
+        
+        Args:
+            bases: Base classes
+            current_states: States discovered in current class
+            
+        Returns:
+            Merged list of state names
+        """
+        inherited: StateList = []
+        
+        # Collect states from base classes
+        for base in bases:
+            if hasattr(base, '__states__'):
+                for state in base.__states__:
+                    if state not in inherited:
+                        inherited.append(state)
+        
+        # Add current class states (avoiding duplicates)
+        for state in current_states:
+            if state not in inherited:
+                inherited.append(state)
+        
+        return inherited
+    
+    @staticmethod
+    def _merge_recursive(bases: tuple[type, ...], namespace: dict[str, Any]) -> RecursiveSet:
+        """
+        Merge recursive state markers from base classes and current class.
+
+        Args:
+            bases: Base classes
+            namespace: Class namespace
+
+        Returns:
+            Set of recursive state names
+        """
+        recursive: RecursiveSet = set()
+
+        # Inherit from base classes
+        for base in bases:
+            if hasattr(base, '__recursive__'):
+                recursive.update(base.__recursive__)
+
+        # Add from current class (methods marked with @recursive decorator)
+        for name, obj in namespace.items():
+            if name.startswith('_'):
+                continue
+            if callable(obj) and getattr(obj, '_recursive_marker', False):
+                recursive.add(name)
+
+        return recursive
+    
+    @staticmethod
+    def _merge_listens(bases: tuple[type, ...], namespace: dict[str, Any]) -> ListenDict:
+        """
+        Merge event listeners from base classes and current class.
+
+        Args:
+            bases: Base classes
+            namespace: Class namespace
+
+        Returns:
+            Dict of event listeners
+        """
+        listens: ListenDict = {}
+
+        # Inherit from base classes
+        for base in bases:
+            if hasattr(base, '__listens__'):
+                for event, handlers in base.__listens__.items():
+                    listens.setdefault(event, []).extend(handlers)
+
+        # Add from current class (methods marked with @listen decorator)
+        for name, obj in namespace.items():
+            if name.startswith('_'):
+                continue
+            if callable(obj):
+                listen_event = getattr(obj, '_listen_event', None)
+                if listen_event:
+                    sources = getattr(obj, '_listen_sources', ())
+                    listens.setdefault(listen_event, []).append((name, sources))
+
+        return listens
+    
+    @staticmethod
+    def _merge_behaviors(bases: tuple[type, ...], namespace: dict[str, Any]) -> BehaviorDict:
+        """
+        Merge behavior tree nodes from base classes and current class.
+
+        Args:
+            bases: Base classes
+            namespace: Class namespace
+
+        Returns:
+            Dict of behavior tree nodes
+        """
+        behaviors: BehaviorDict = {}
+
+        # Inherit from base classes
+        for base in bases:
+            if hasattr(base, '__behaviors__'):
+                behaviors.update(base.__behaviors__)
+
+        # Add from current class (methods marked with behavior decorators)
+        for name, obj in namespace.items():
+            if name.startswith('_'):
+                continue
+            if callable(obj):
+                # Check for composite behaviors (@sequence, @selector, @parallel)
+                behavior_children = getattr(obj, '_behavior_children', None)
+                if behavior_children:
+                    behavior_composite = getattr(obj, '_behavior_composite', None)
+                    behaviors[name] = {
+                        'children': behavior_children,
+                        'composite': behavior_composite
+                    }
+                else:
+                    # Check for simple @behavior
+                    behavior_target = getattr(obj, '_behavior_target', None)
+                    if behavior_target:
+                        behaviors[name] = {
+                            'children': behavior_target,
+                            'composite': None
+                        }
+
+        return behaviors
+
+    @staticmethod
+    def _validate_behaviors(cls: type, class_name: str, current_states: list[str]) -> None:
+        """
+        Validate that all behavior children reference existing states.
+
+        This check happens at class definition time to catch errors early.
+        A behavior child must either be a regular state (in __states__) or
+        another behavior node (in __behaviors__).
+
+        Args:
+            cls: The class being created
+            class_name: The class name
+            current_states: States defined in the current class namespace
+
+        Raises:
+            TypeError: If a behavior references an unknown state
+        """
+        valid_states = set(cls.__states__)
+        valid_behaviors = set(cls.__behaviors__.keys())
+
+        for behavior_name, behavior_info in cls.__behaviors__.items():
+            children = behavior_info.get('children', [])
+            # Handle both list and single string children
+            if isinstance(children, str):
+                children = [children]
+            elif not isinstance(children, (list, tuple)):
+                continue
+
+            for child in children:
+                if child not in valid_states and child not in valid_behaviors:
+                    raise TypeError(
+                        f"[{cls.__name__}]: Behavior '{behavior_name}' "
+                        f"references unknown state '{child}'. "
+                        f"Available states: {sorted(valid_states)}"
+                    )
+
+    @staticmethod
+    def _register_class(cls: type, name: str) -> None:
+        """
+        Register class to global prototype registry.
+        
+        Registration rules:
+        - Class must have a 'NAME' attribute
+        - Class name must not be in BASE_CLASSES
+        - NAME must not end with a digit
+        
+        Args:
+            cls: Class to register
+            name: Class name
+        """
+        # Skip base classes
+        if name in BASE_CLASSES:
+            return
+        
+        # Check for NAME attribute
+        class_name = getattr(cls, 'NAME', None)
+        if class_name is None:
+            return
+        
+        # Validate NAME doesn't end with digit
+        if class_name and class_name[-1].isdigit():
+            raise ValueError(
+                f"Class '{name}' has invalid NAME '{class_name}': "
+                "NAME must not end with a digit"
+            )
+        
+        # Register to global prototype registry
+        __protos__[class_name] = cls
+
+    @staticmethod
+    def proto(name:str):
+        return __protos__.get(name)
+
+    @staticmethod
+    def instances(name: str | type) -> list[Any]:
+        """
+        Get all living instances with the given NAME.
+
+        Args:
+            name: Instance NAME (class NAME attribute) or class type
+
+        Returns:
+            List of living instances
+        """
+        _n = name.NAME if isinstance(name, type) else name
+        _refs = StageMachineMeta.__INSTANCES__.get(_n, {})
+        _ret = []
+        for _ref in _refs.values():
+            _inst = _ref()
+            if _inst is not None:
+                _ret.append(_inst)
+        return _ret
+
+    @classmethod
+    def requireId(cls, name:str):
+        if not name:
+            raise ValueError("NAME cannot be empty")
+        ret = cls.__ID_PROTOS__[name] = cls.__ID_PROTOS__.get(name, -1) + 1
+        return ret
+
+    @staticmethod
+    def removeInstance(name: str | type, uid: int) -> bool:
+        """从 __INSTANCES__ 中移除指定 uid 的实例。
+
+        Args:
+            name: Instance NAME (class NAME attribute) or class type
+            uid: 实例 uid (通常为 id(instance))
+
+        Returns:
+            True if removed, False if not found
+        """
+        _n = name.NAME if isinstance(name, type) else name
+        _d = StageMachineMeta.__INSTANCES__.get(_n)
+        if _d is None:
+            return False
+        _removed = _d.pop(uid, None) is not None
+        if not _d:
+            StageMachineMeta.__INSTANCES__.pop(_n, None)
+        return _removed
+
+
+# Decorator functions for marking methods
+def recursive(func: Callable) -> Callable:
+    """
+    Decorator to mark a state method as recursive.
+    
+    Recursive states can transition to themselves.
+    
+    Args:
+        func: Method to mark
+        
+    Returns:
+        Marked method
+    """
+    func._is_recursive = True  # type: ignore[attr-defined]
+    return func
+
+
+def listen(event: str, *sources: str) -> Callable[[Callable], Callable]:
+    """
+    Decorator to mark a method as an event listener.
+    
+    Args:
+        event: Event name to listen for
+        *sources: Optional source filters
+        
+    Returns:
+        Decorator function
+        
+    Example:
+        @listen('onComplete', 'loader')
+        def handle_complete(self, event): ...
+    """
+    def decorator(func: Callable) -> Callable:
+        func._listen_info = (event, sources)  # type: ignore[attr-defined]
+        return func
+    return decorator
+
+
+def behavior(*, children: list[str] | None = None, composite: str | None = None) -> Callable[[Callable], Callable]:
+    """
+    Decorator to mark a method as a behavior tree node.
+    
+    Args:
+        children: List of child state names
+        composite: Composite type (e.g., 'selector', 'sequence')
+        
+    Returns:
+        Decorator function
+        
+    Example:
+        @behavior(children=['idle', 'walk', 'run'], composite='selector')
+        def movement(self): ...
+    """
+    def decorator(func: Callable) -> Callable:
+        func._behavior_info = {  # type: ignore[attr-defined]
+            'children': children or [],
+            'composite': composite
+        }
+        return func
+    return decorator
+
+
+def state(func: Callable) -> Callable:
+    """
+    Decorator to explicitly mark a method as a state.
+    
+    This is optional since states are auto-discovered, but can be used
+    for clarity or to include methods that might otherwise be excluded.
+    
+    Args:
+        func: Method to mark
+        
+    Returns:
+        Marked method
+    """
+    func._is_state = True  # type: ignore[attr-defined]
+    return func
+
+
+# Utility functions for prototype management
+def GetPrototype(name: str) -> type | None:
+    """
+    Get a registered prototype by name.
+
+    Args:
+        name: Prototype name (class NAME attribute)
+
+    Returns:
+        The prototype class or None if not found
+    """
+    return __protos__.get(name)
+
+
+# 小写别名，保持向后兼容
+get_prototype = GetPrototype
+
+
+def ListPrototypes() -> list[str]:
+    """
+    List all registered prototype names.
+
+    Returns:
+        List of registered prototype names
+    """
+    return list(__protos__.keys())
+
+
+# 小写别名，保持向后兼容
+list_prototypes = ListPrototypes
+
+
+def ClearPrototypes() -> None:
+    """Clear all registered prototypes. Mainly for testing."""
+    __protos__.clear()
+
+
+# 小写别名，保持向后兼容
+clear_prototypes = ClearPrototypes
+
+
+# Export all public symbols
+__all__ = [
+    'StageMachineMeta',
+    'recursive',
+    'listen',
+    'behavior',
+    'state',
+    'GetPrototype',
+    'get_prototype',
+    'ListPrototypes',
+    'list_prototypes',
+    'ClearPrototypes',
+    'clear_prototypes',
+    '__protos__',
+    'IGNORES',
+    'BASE_CLASSES',
+]