quantalogic 0.33.4__py3-none-any.whl → 0.40.0__py3-none-any.whl

quantalogic/console_print_events.py

@@ -15,7 +15,7 @@ def console_print_events(event: str, data: dict[str, Any] | None = None):
     if not data:
         console.print(
             Panel.fit(
-                Text(f"ⓘ No event data", justify="center", style="italic cyan"),
+                Text("ⓘ No event data", justify="center", style="italic cyan"),
                 title=f"✨ {event}",
                 border_style="cyan",
                 box=box.ROUNDED,
@@ -40,11 +40,7 @@ def console_print_events(event: str, data: dict[str, Any] | None = None):
                     else:
                         branch.add(Text(f"• {item}", style="dim green"))
             else:
-                tree.add(Text.assemble(
-                    key_text, 
-                    (" → ", "dim"), 
-                    str(value), style="bright_white"
-                ))
+                tree.add(Text.assemble(key_text, (" → ", "dim"), str(value), style="bright_white"))
 
     # Create a compact tree with subtle styling
     tree = Tree("", guide_style="dim cyan", hide_root=True)
@@ -61,5 +57,5 @@ def console_print_events(event: str, data: dict[str, Any] | None = None):
             subtitle=f"[dim]Items: {len(data)}[/dim]",
             subtitle_align="right",
         ),
-        no_wrap=True
-    )
+        no_wrap=True,
+    )

quantalogic/console_print_token.py

@@ -7,10 +7,10 @@ from rich.console import Console
 
 def console_print_token(event: str, data: Any | None = None):
     """Print a token with rich formatting.
-    
+
     Args:
         event (str): The event name (e.g., 'stream_chunk')
         data (Any | None): The token data to print
     """
     console = Console()
-    console.print(data, end="")
+    console.print(data.content if hasattr(data, "content") else data, end="")

quantalogic/docs_cli.py

@@ -1,49 +1,54 @@
-import subprocess
 import os
+import subprocess
 import sys
 
+
 def get_config_path():
     """Get the absolute path to the mkdocs configuration file."""
-    return os.path.join(os.path.dirname(os.path.dirname(__file__)), 'mkdocs', 'mkdocs.yml')
+    return os.path.join(os.path.dirname(os.path.dirname(__file__)), "mkdocs", "mkdocs.yml")
+
 
 def serve_docs():
     """Serve MkDocs documentation locally."""
     config_path = get_config_path()
     try:
-        subprocess.run(['mkdocs', 'serve', '--config-file', config_path], check=True)
+        subprocess.run(["mkdocs", "serve", "--config-file", config_path], check=True)
     except subprocess.CalledProcessError as e:
         print(f"Error serving documentation: {e}")
         sys.exit(1)
 
+
 def build_docs():
     """Build MkDocs documentation."""
     config_path = get_config_path()
     try:
-        subprocess.run(['mkdocs', 'build', '--config-file', config_path], check=True)
+        subprocess.run(["mkdocs", "build", "--config-file", config_path], check=True)
         print("Documentation built successfully.")
     except subprocess.CalledProcessError as e:
         print(f"Error building documentation: {e}")
         sys.exit(1)
 
+
 def deploy_docs():
     """Deploy MkDocs documentation to GitHub Pages."""
     config_path = get_config_path()
     try:
-        subprocess.run(['mkdocs', 'gh-deploy', '--config-file', config_path], check=True)
+        subprocess.run(["mkdocs", "gh-deploy", "--config-file", config_path], check=True)
         print("Documentation deployed successfully.")
     except subprocess.CalledProcessError as e:
         print(f"Error deploying documentation: {e}")
         sys.exit(1)
 
+
 # Ensure the script can be run directly for testing
-if __name__ == '__main__':
+if __name__ == "__main__":
     command = sys.argv[1] if len(sys.argv) > 1 else None
-    
-    if command == 'serve':
+
+    if command == "serve":
         serve_docs()
-    elif command == 'build':
+    elif command == "build":
         build_docs()
-    elif command == 'deploy':
+    elif command == "deploy":
         deploy_docs()
     else:
         print("Usage: python docs_cli.py [serve|build|deploy]")

quantalogic/event_emitter.py

@@ -1,29 +1,109 @@
+import asyncio
+import inspect
 import threading
-from typing import Any, Callable
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from loguru import logger
 
 
 class EventEmitter:
-    """A thread-safe event emitter class for managing event listeners and emissions."""
+    """A thread-safe event emitter class for managing event listeners and emissions with enhanced features.
+
+    This class allows registering listeners for specific events or all events using a wildcard ('*').
+    Listeners can be registered with priorities and metadata for better control and debugging.
+    The class is backward compatible with the original EventEmitter and includes additional features
+    like error handling and debugging tools.
+
+    Now supports both synchronous and asynchronous listeners (coroutines). Synchronous listeners are
+    executed immediately, while asynchronous listeners are scheduled in a background asyncio event loop.
+    Note that errors from async listeners may be handled in a background thread, so error handlers must be
+    thread-safe if provided.
+    """
 
     def __init__(self) -> None:
         """Initialize an empty EventEmitter instance.
 
         Creates an empty dictionary to store event listeners,
-        where each event can have multiple callable listeners.
+        where each event can have multiple callable listeners with priorities and metadata.
         Also initializes a list for wildcard listeners that listen to all events.
+        Starts a background asyncio event loop in a daemon thread to handle async listeners.
         """
-        self._listeners: dict[str, list[Callable[..., Any]]] = {}
-        self._wildcard_listeners: list[Callable[..., Any]] = []
+        # Listeners stored as (callable, priority, metadata) tuples
+        self._listeners: dict[str, list[Tuple[Callable[..., Any], int, Optional[Dict[str, Any]]]]] = {}
+        self._wildcard_listeners: list[Tuple[Callable[..., Any], int, Optional[Dict[str, Any]]]] = []
         self._lock = threading.RLock()
+        self.context: dict[str, Any] = {}  # Store context data like task_id
+
+        # Initialize background asyncio event loop
+        self._loop = asyncio.new_event_loop()
+        self._stop_future = self._loop.create_future()
+        self._thread = threading.Thread(target=self._run_loop, daemon=True)
+        self._thread.start()
+
+    def _run_loop(self) -> None:
+        """Run the background asyncio event loop until stopped."""
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_until_complete(self._stop_future)
+
+    def _schedule_async_listener(
+        self,
+        listener: Callable[..., Any],
+        event: str,
+        listener_args: Tuple[Any, ...],
+        error_handler: Optional[Callable[[Exception], None]],
+        metadata: Optional[Dict[str, Any]],
+        kwargs: Dict[str, Any],
+    ) -> None:
+        """Schedule an async listener in the background loop and handle errors."""
+        kwargs = kwargs or {}  # Ensure kwargs is a dict if None
+        coro = listener(event, *listener_args, **kwargs)  # Pass event, args, and kwargs
+        task = self._loop.create_task(coro)
+        if error_handler:
+            task.add_done_callback(lambda t: self._handle_task_error(t, error_handler, metadata))
+
+    def _handle_task_error(
+        self,
+        task: asyncio.Task,
+        error_handler: Optional[Callable[[Exception], None]],
+        metadata: Optional[Dict[str, Any]],
+    ) -> None:
+        """Handle exceptions from async listeners."""
+        try:
+            task.result()
+        except Exception as e:
+            if error_handler:
+                error_handler(e)
+            else:
+                error_msg = f"Error in async listener {task.get_coro().__name__}: {e}"
+                if metadata:
+                    error_msg += f" (Metadata: {metadata})"
+                logger.error(error_msg)
+
+    def close(self) -> None:
+        """Optional method to shut down the background event loop.
+
+        Not required for existing users, as the loop runs in a daemon thread.
+        Useful for explicit resource cleanup when using async listeners.
+        """
+        self._loop.call_soon_threadsafe(lambda: self._stop_future.set_result(None))
+        self._thread.join()
 
-    def on(self, event: str | list[str], listener: Callable[..., Any]) -> None:
-        """Register an event listener for one or more events.
+    def on(
+        self,
+        event: str | list[str],
+        listener: Callable[..., Any],
+        priority: int = 0,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Register an event listener for one or more events with optional priority and metadata.
 
         If event is a list, the listener is registered for each event in the list.
 
         Parameters:
         - event (str | list[str]): The event name or a list of event names to listen to.
         - listener (Callable): The function to call when the specified event(s) are emitted.
+        - priority (int): Priority level (lower number = higher priority), defaults to 0.
+        - metadata (dict, optional): Additional info about the listener for debugging or error handling.
         """
         if isinstance(event, str):
             events = [event]
@@ -34,35 +114,49 @@ class EventEmitter:
 
         with self._lock:
             for evt in events:
+                if not evt or (evt != "*" and not isinstance(evt, str)):
+                    raise ValueError("Event names must be non-empty strings or '*'")
+                listener_tuple = (listener, priority, metadata)
                 if evt == "*":
-                    if listener not in self._wildcard_listeners:
-                        self._wildcard_listeners.append(listener)
+                    if listener_tuple not in self._wildcard_listeners:
+                        self._wildcard_listeners.append(listener_tuple)
                 else:
                     if evt not in self._listeners:
                         self._listeners[evt] = []
-                    if listener not in self._listeners[evt]:
-                        self._listeners[evt].append(listener)
+                    if listener_tuple not in self._listeners[evt]:
+                        self._listeners[evt].append(listener_tuple)
 
-    def once(self, event: str | list[str], listener: Callable[..., Any]) -> None:
-        """Register a one-time event listener for one or more events.
+    def once(
+        self,
+        event: str | list[str],
+        listener: Callable[..., Any],
+        priority: int = 0,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Register a one-time event listener for one or more events with optional priority and metadata.
 
         The listener is removed after it is invoked the first time the event is emitted.
 
         Parameters:
         - event (str | list[str]): The event name or a list of event names to listen to.
+        - listener (Callable): The function to call once when the specified event(s) are emitted.
+        - priority (int): Priority level (lower number = higher priority), defaults to 0.
+        - metadata (dict, optional): Additional info about the listener for debugging or error handling.
         """
+        if inspect.iscoroutinefunction(listener):
 
-        def wrapper(*args: Any, **kwargs: Any) -> None:
-            self.off(event, wrapper)
-            listener(*args, **kwargs)
+            async def wrapper(*args: Any, **kwargs: Any) -> None:
+                self.off(event, wrapper)
+                await listener(*args, **kwargs)
+        else:
 
-        self.on(event, wrapper)
+            def wrapper(*args: Any, **kwargs: Any) -> None:
+                self.off(event, wrapper)
+                listener(*args, **kwargs)
 
-    def off(
-        self,
-        event: str | list[str] | None = None,
-        listener: Callable[..., Any] = None,
-    ) -> None:
+        self.on(event, wrapper, priority, metadata)
+
+    def off(self, event: str | list[str] | None = None, listener: Callable[..., Any] = None) -> None:
         """Unregister an event listener.
 
         If event is None, removes the listener from all events.
@@ -76,11 +170,13 @@ class EventEmitter:
             if event is None:
                 # Remove from all specific events
                 for evt_list in self._listeners.values():
-                    if listener in evt_list:
-                        evt_list.remove(listener)
+                    for listener_tuple in list(evt_list):
+                        if listener_tuple[0] == listener:
+                            evt_list.remove(listener_tuple)
                 # Remove from wildcard listeners
-                if listener in self._wildcard_listeners:
-                    self._wildcard_listeners.remove(listener)
+                for listener_tuple in list(self._wildcard_listeners):
+                    if listener_tuple[0] == listener:
+                        self._wildcard_listeners.remove(listener_tuple)
             else:
                 if isinstance(event, str):
                     events = [event]
@@ -90,36 +186,67 @@ class EventEmitter:
                     raise TypeError("Event must be a string, a list of strings, or None.")
 
                 for evt in events:
+                    if not evt or (evt != "*" and not isinstance(evt, str)):
+                        raise ValueError("Event names must be non-empty strings or '*'")
                     if evt == "*":
-                        if listener in self._wildcard_listeners:
-                            self._wildcard_listeners.remove(listener)
+                        for listener_tuple in list(self._wildcard_listeners):
+                            if listener_tuple[0] == listener:
+                                self._wildcard_listeners.remove(listener_tuple)
                     elif evt in self._listeners:
-                        try:
-                            self._listeners[evt].remove(listener)
-                        except ValueError:
-                            pass  # Listener was not found for this event
+                        for listener_tuple in list(self._listeners[evt]):
+                            if listener_tuple[0] == listener:
+                                self._listeners[evt].remove(listener_tuple)
 
-    def emit(self, event: str, *args: Any, **kwargs: Any) -> None:
-        """Emit an event to all registered listeners.
+    def emit(
+        self, event: str, *args: Any, error_handler: Optional[Callable[[Exception], None]] = None, **kwargs: Any
+    ) -> None:
+        """Emit an event to all registered listeners with optional error handling.
 
-        First, invokes wildcard listeners, then listeners registered to the specific event.
+        First, invokes wildcard listeners, then listeners registered to the specific event, sorted by priority.
+        Synchronous listeners are executed immediately, while async listeners are scheduled in the background loop.
 
         Parameters:
         - event (str): The name of the event to emit.
         - args: Positional arguments to pass to the listeners.
+        - error_handler (Callable, optional): Function to handle exceptions from listeners.
         - kwargs: Keyword arguments to pass to the listeners.
         """
+        if not event or not isinstance(event, str):
+            raise ValueError("Event name must be a non-empty string")
+
         with self._lock:
+            # Copy listeners to avoid modification issues during emission
             listeners = list(self._wildcard_listeners)
             if event in self._listeners:
                 listeners.extend(self._listeners[event])
-
-        for listener in listeners:
-            try:
-                listener(event, *args, **kwargs)
-            except Exception as e:
-                # Log the exception or handle it as needed
-                print(f"Error in listener {listener}: {e}")
+            # Sort by priority (lower number = higher priority)
+            listeners.sort(key=lambda x: x[1])
+
+        # Execute listeners outside the lock to prevent deadlocks
+        for listener_tuple in listeners:
+            listener, _, metadata = listener_tuple
+            if inspect.iscoroutinefunction(listener):
+                self._loop.call_soon_threadsafe(
+                    self._schedule_async_listener,
+                    listener,
+                    event,
+                    args,  # Pass args as a tuple
+                    error_handler,
+                    metadata,
+                    kwargs,
+                )
+            else:
+                try:
+                    listener(event, *args, **kwargs)
+                except Exception as e:
+                    if error_handler:
+                        error_handler(e)
+                    else:
+                        # Default error logging with loguru, including metadata if available
+                        error_msg = f"Error in listener {listener.__name__}: {e}"
+                        if metadata:
+                            error_msg += f" (Metadata: {metadata})"
+                        logger.error(error_msg)
 
     def clear(self, event: str) -> None:
         """Clear all listeners for a specific event.
@@ -127,6 +254,9 @@ class EventEmitter:
         Parameters:
         - event (str): The name of the event to clear listeners from.
         """
+        if not event or not isinstance(event, str):
+            raise ValueError("Event name must be a non-empty string")
+
         with self._lock:
             if event in self._listeners:
                 del self._listeners[event]
@@ -144,13 +274,16 @@ class EventEmitter:
         - event (str): The name of the event.
 
         Returns:
-        - List of callables registered for the event.
+        - List of callables registered for the event (without priority or metadata).
         """
+        if not event or not isinstance(event, str):
+            raise ValueError("Event name must be a non-empty string")
+
         with self._lock:
-            listeners = list(self._wildcard_listeners)
+            result = [listener_tuple[0] for listener_tuple in self._wildcard_listeners]
             if event in self._listeners:
-                listeners.extend(self._listeners[event])
-            return listeners
+                result.extend(listener_tuple[0] for listener_tuple in self._listeners[event])
+            return result
 
     def has_listener(self, event: str | None, listener: Callable[..., Any]) -> bool:
         """Check if a specific listener is registered for an event.
@@ -163,61 +296,103 @@ class EventEmitter:
         - True if the listener is registered for the event, False otherwise.
         """
         with self._lock:
-            if event is None:
-                return listener in self._wildcard_listeners
-            elif event == "*":
-                return listener in self._wildcard_listeners
+            if event is None or event == "*":
+                return any(listener_tuple[0] == listener for listener_tuple in self._wildcard_listeners)
             else:
-                return listener in self._listeners.get(event, [])
+                if not event or not isinstance(event, str):
+                    raise ValueError("Event name must be a non-empty string")
+                return any(listener_tuple[0] == listener for listener_tuple in self._listeners.get(event, []))
+
+    def listener_count(self, event: str) -> int:
+        """Return the number of listeners for a specific event, including wildcard listeners.
+
+        Parameters:
+        - event (str): The name of the event.
+
+        Returns:
+        - Total count of listeners for the event.
+        """
+        if not event or not isinstance(event, str):
+            raise ValueError("Event name must be a non-empty string")
+
+        with self._lock:
+            count = len(self._wildcard_listeners)
+            if event in self._listeners:
+                count += len(self._listeners[event])
+            return count
+
+    def debug_info(self) -> Dict[str, Any]:
+        """Return a dictionary with the current state of the emitter for debugging purposes.
+
+        Returns:
+        - Dict containing wildcard listeners and event-specific listeners.
+        """
+        with self._lock:
+            return {
+                "wildcard_listeners": [(l.__name__, p, m) for l, p, m in self._wildcard_listeners],
+                "event_listeners": {
+                    evt: [(l.__name__, p, m) for l, p, m in listeners] for evt, listeners in self._listeners.items()
+                },
+            }
 
 
 if __name__ == "__main__":
+    import asyncio
+
+    # Synchronous listener
+    def on_data_received(event: str, data: Any):
+        print(f"[Sync] Data received: {data}")
+
+    # Asynchronous listener
+    async def on_data_async(event: str, data: Any):
+        print(f"[Async] Starting async processing for data: {data}")
+        await asyncio.sleep(1)
+        print(f"[Async] Finished async processing for data: {data}")
 
-    def on_data_received(data):
-        print(f"Data received: {data}")
+    def on_any_event(event: str, data: Any):
+        print(f"[Sync] Event '{event}' emitted with data: {data}")
 
-    def on_any_event(event, data):
-        print(f"Event '{event}' emitted with data: {data}")
+    def custom_error_handler(exc: Exception):
+        print(f"Custom error handler caught: {exc}")
 
     emitter = EventEmitter()
 
-    # Register specific event listener
-    emitter.on("data", on_data_received)
+    # Register specific event listeners
+    emitter.on("data", on_data_received, priority=1)
+    emitter.on("data", on_data_async, priority=2, metadata={"id": "async_listener"})
 
     # Register wildcard listener
-    emitter.on("*", on_any_event)
+    emitter.on("*", on_any_event, priority=0)
 
     # Emit 'data' event
+    print("Emitting 'data' event...")
     emitter.emit("data", "Sample Data")
+    print("Emit completed. Note: Async listeners may still be running.")
 
-    # Output:
-    # Event 'data' emitted with data: Sample Data
-    # Data received: Sample Data
+    # Wait briefly to see async output
+    import time
 
-    # Emit 'update' event
-    emitter.emit("update", "Update Data")
+    time.sleep(2)
 
-    # Output:
-    # Event 'update' emitted with data: Update Data
+    # Register a one-time async listener
+    async def once_async_listener(event: str, data: Any):
+        print(f"[Async Once] Received: {data}")
+        await asyncio.sleep(1)
+        print(f"[Async Once] Processed: {data}")
 
-    # Register a one-time listener
-    def once_listener(data):
-        print(f"Once listener received: {data}")
-
-    emitter.once("data", once_listener)
-
-    # Emit 'data' event
-    emitter.emit("data", "First Call")
+    emitter.once("data", once_async_listener, priority=2, metadata={"id": "once_async"})
+    print("Emitting 'data' for once listener...")
+    emitter.emit("data", "Once Async Data")
+    time.sleep(2)
 
-    # Output:
-    # Event 'data' emitted with data: First Call
-    # Data received: First Call
-    # Once listener received: First Call
+    # Test error handling with async listener
+    async def error_async_listener(event: str, data: Any):
+        raise ValueError("Test async error")
 
-    # Emit 'data' event again
-    emitter.emit("data", "Second Call")
+    emitter.on("data", error_async_listener, metadata={"id": "error_async"})
+    print("Emitting 'data' with error...")
+    emitter.emit("data", "Error Data", error_handler=custom_error_handler)
+    time.sleep(1)
 
-    # Output:
-    # Event 'data' emitted with data: Second Call
-    # Data received: Second Call
-    # (Once listener is not called again)
+    # Clean up (optional)
+    emitter.close()

quantalogic/flow/__init__.py

@@ -0,0 +1,23 @@
+"""
+Flow Package Initialization
+
+This module initializes the flow package and provides package-level imports.
+Now supports nested workflows for hierarchical flow definitions.
+"""
+
+from loguru import logger
+
+# Expose key components for easy importing
+from .flow import Nodes, Workflow, WorkflowEngine
+from .flow_manager import WorkflowManager
+
+# Define which symbols are exported when using `from flow import *`
+__all__ = [
+    "WorkflowManager",
+    "Nodes",
+    "Workflow",
+    "WorkflowEngine",
+]
+
+# Package-level logger configuration
+logger.info("Initializing Quantalogic Flow Package")