dv-pipecat-ai 0.0.74.dev770__py3-none-any.whl → 0.0.82.dev776__py3-none-any.whl

pipecat/utils/asyncio/task_manager.py

@@ -4,8 +4,14 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Asyncio task management.
+
+This module provides task management functionality. Includes both abstract base
+classes and concrete implementations for managing asyncio tasks with
+comprehensive monitoring and cleanup capabilities.
+"""
+
 import asyncio
-import time
 import traceback
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
@@ -13,154 +19,141 @@ from typing import Coroutine, Dict, Optional, Sequence
 
 from loguru import logger
 
-WATCHDOG_TIMEOUT = 5.0
-
 
 @dataclass
 class TaskManagerParams:
+    """Configuration parameters for task manager initialization.
+
+    Parameters:
+        loop: The asyncio event loop to use for task management.
+    """
+
     loop: asyncio.AbstractEventLoop
-    enable_watchdog_timers: bool = False
-    enable_watchdog_logging: bool = False
-    watchdog_timeout: float = WATCHDOG_TIMEOUT
 
 
 class BaseTaskManager(ABC):
+    """Abstract base class for asyncio task management.
+
+    Provides the interface for creating, monitoring, and managing asyncio tasks.
+    """
+
     @abstractmethod
     def setup(self, params: TaskManagerParams):
-        pass
+        """Initialize the task manager with configuration parameters.
 
-    @abstractmethod
-    def get_event_loop(self) -> asyncio.AbstractEventLoop:
+        Args:
+            params: Configuration parameters for task management.
+        """
         pass
 
     @abstractmethod
-    def create_task(
-        self,
-        coroutine: Coroutine,
-        name: str,
-        *,
-        enable_watchdog_logging: Optional[bool] = None,
-        enable_watchdog_timers: Optional[bool] = None,
-        watchdog_timeout: Optional[float] = None,
-    ) -> asyncio.Task:
-        """
-        Creates and schedules a new asyncio Task that runs the given coroutine.
-
-        The task is added to a global set of created tasks.
-
-        Args:
-            loop (asyncio.AbstractEventLoop): The event loop to use for creating the task.
-            coroutine (Coroutine): The coroutine to be executed within the task.
-            name (str): The name to assign to the task for identification.
-            enable_watchdog_logging(bool): whether this task should log watchdog processing times.
-            enable_watchdog_timers(bool): whether this task should have a watchdog timer.
-            watchdog_timeout(float): watchdog timer timeout for this task.
+    def get_event_loop(self) -> asyncio.AbstractEventLoop:
+        """Get the event loop used by this task manager.
 
         Returns:
-            asyncio.Task: The created task object.
+            The asyncio event loop instance.
         """
         pass
 
     @abstractmethod
-    async def wait_for_task(self, task: asyncio.Task, timeout: Optional[float] = None):
-        """Wait for an asyncio.Task to complete with optional timeout handling.
+    def create_task(self, coroutine: Coroutine, name: str) -> asyncio.Task:
+        """Creates and schedules a new asyncio Task that runs the given coroutine.
 
-        This function awaits the specified asyncio.Task and handles scenarios for
-        timeouts, cancellations, and other exceptions. It also ensures that the task
-        is removed from the set of registered tasks upon completion or failure.
+        The task is added to a global set of created tasks.
 
         Args:
-            task (asyncio.Task): The asyncio Task to wait for.
-            timeout (Optional[float], optional): The maximum number of seconds
-                to wait for the task to complete. If None, waits indefinitely.
-                Defaults to None.
+            coroutine: The coroutine to be executed within the task.
+            name: The name to assign to the task for identification.
+
+        Returns:
+            The created task object.
         """
         pass
 
     @abstractmethod
     async def cancel_task(self, task: asyncio.Task, timeout: Optional[float] = None):
-        """Cancels the given asyncio Task and awaits its completion with an
-        optional timeout.
+        """Cancels the given asyncio Task and awaits its completion with an optional timeout.
 
         This function removes the task from the set of registered tasks upon
         completion or failure.
 
         Args:
-            task (asyncio.Task): The task to be cancelled.
-            timeout (Optional[float]): The optional timeout in seconds to wait for the task to cancel.
-
+            task: The task to be cancelled.
+            timeout: The optional timeout in seconds to wait for the task to cancel.
         """
         pass
 
     @abstractmethod
     def current_tasks(self) -> Sequence[asyncio.Task]:
-        """Returns the list of currently created/registered tasks."""
-        pass
-
-    @abstractmethod
-    def task_reset_watchdog(self):
-        """Resets the running task watchdog timer. If not reset, a warning will
-        be logged indicating the task is stalling.
+        """Returns the list of currently created/registered tasks.
 
+        Returns:
+            Sequence of currently managed asyncio tasks.
         """
         pass
 
-    @property
-    @abstractmethod
-    def task_watchdog_enabled(self) -> bool:
-        """Whether the current running task has a watchdog timer enabled."""
-        pass
-
 
 @dataclass
 class TaskData:
+    """Internal data structure for tracking task metadata.
+
+    Parameters:
+        task: The asyncio Task being managed.
+    """
+
     task: asyncio.Task
-    watchdog_timer: asyncio.Event
-    enable_watchdog_logging: bool
-    enable_watchdog_timers: bool
-    watchdog_timeout: float
-    watchdog_task: Optional[asyncio.Task]
 
 
 class TaskManager(BaseTaskManager):
+    """Concrete implementation of BaseTaskManager.
+
+    Manages asyncio tasks. Provides comprehensive task lifecycle management
+    including creation, monitoring, cancellation, and cleanup.
+
+    """
+
     def __init__(self, conversation_id: Optional[str] = None) -> None:
+        """Initialize the task manager with empty task registry."""
         self._tasks: Dict[str, TaskData] = {}
         self._params: Optional[TaskManagerParams] = None
         self._conversation_id = conversation_id
 
     def setup(self, params: TaskManagerParams):
+        """Initialize the task manager with configuration parameters.
+
+        Args:
+            params: Configuration parameters for task management.
+        """
         if not self._params:
             self._params = params
 
     def get_event_loop(self) -> asyncio.AbstractEventLoop:
+        """Get the event loop used by this task manager.
+
+        Returns:
+            The asyncio event loop instance.
+
+        Raises:
+            Exception: If the task manager is not properly set up.
+        """
         if not self._params:
             raise Exception("TaskManager is not setup: unable to get event loop")
         return self._params.loop
 
-    def create_task(
-        self,
-        coroutine: Coroutine,
-        name: str,
-        *,
-        enable_watchdog_logging: Optional[bool] = None,
-        enable_watchdog_timers: Optional[bool] = None,
-        watchdog_timeout: Optional[float] = None,
-    ) -> asyncio.Task:
-        """
-        Creates and schedules a new asyncio Task that runs the given coroutine.
+    def create_task(self, coroutine: Coroutine, name: str) -> asyncio.Task:
+        """Creates and schedules a new asyncio Task that runs the given coroutine.
 
         The task is added to a global set of created tasks.
 
         Args:
-            loop (asyncio.AbstractEventLoop): The event loop to use for creating the task.
-            coroutine (Coroutine): The coroutine to be executed within the task.
-            name (str): The name to assign to the task for identification.
-            enable_watchdog_logging(bool): whether this task should log watchdog processing time.
-            enable_watchdog_timers(bool): whether this task should have a watchdog timer.
-            watchdog_timeout(float): watchdog timer timeout for this task.
+            coroutine: The coroutine to be executed within the task.
+            name: The name to assign to the task for identification.
 
         Returns:
-            asyncio.Task: The created task object.
+            The created task object.
+
+        Raises:
+            Exception: If the task manager is not properly set up.
         """
 
         async def run_coroutine():
@@ -186,73 +179,23 @@ class TaskManager(BaseTaskManager):
         task = self._params.loop.create_task(run_coroutine())
         task.set_name(name)
         task.add_done_callback(self._task_done_handler)
-        self._add_task(
-            TaskData(
-                task=task,
-                watchdog_timer=asyncio.Event(),
-                enable_watchdog_logging=(
-                    enable_watchdog_logging
-                    if enable_watchdog_logging
-                    else self._params.enable_watchdog_logging
-                ),
-                enable_watchdog_timers=(
-                    enable_watchdog_timers
-                    if enable_watchdog_timers
-                    else self._params.enable_watchdog_timers
-                ),
-                watchdog_timeout=(
-                    watchdog_timeout if watchdog_timeout else self._params.watchdog_timeout
-                ),
-                watchdog_task=None,
-            ),
-        )
+        self._add_task(TaskData(task=task))
         logger.trace(f"{name}: task created")
         return task
 
-    async def wait_for_task(self, task: asyncio.Task, timeout: Optional[float] = None):
-        """Wait for an asyncio.Task to complete with optional timeout handling.
-
-        This function awaits the specified asyncio.Task and handles scenarios for
-        timeouts, cancellations, and other exceptions. It also ensures that the task
-        is removed from the set of registered tasks upon completion or failure.
-
-        Args:
-            task (asyncio.Task): The asyncio Task to wait for.
-            timeout (Optional[float], optional): The maximum number of seconds
-                to wait for the task to complete. If None, waits indefinitely.
-                Defaults to None.
-        """
-        name = task.get_name()
-        try:
-            if timeout:
-                await asyncio.wait_for(task, timeout=timeout)
-            else:
-                await task
-        except asyncio.TimeoutError:
-            logger.warning(f"{name}: timed out waiting for task to finish")
-        except asyncio.CancelledError:
-            logger.trace(f"{name}: unexpected task cancellation (maybe Ctrl-C?)")
-            raise
-        except Exception as e:
-            logger.exception(f"{name}: unexpected exception while stopping task: {e}")
-
     async def cancel_task(self, task: asyncio.Task, timeout: Optional[float] = None):
-        """Cancels the given asyncio Task and awaits its completion with an
-        optional timeout.
+        """Cancels the given asyncio Task and awaits its completion with an optional timeout.
 
         This function removes the task from the set of registered tasks upon
         completion or failure.
 
         Args:
-            task (asyncio.Task): The task to be cancelled.
-            timeout (Optional[float]): The optional timeout in seconds to wait for the task to cancel.
-
+            task: The task to be cancelled.
+            timeout: The optional timeout in seconds to wait for the task to cancel.
         """
         name = task.get_name()
         task.cancel()
         try:
-            # Make sure to reset watchdog if a task is cancelled.
-            self.reset_watchdog(task)
             if timeout:
                 await asyncio.wait_for(task, timeout=timeout)
             else:
@@ -268,68 +211,31 @@ class TaskManager(BaseTaskManager):
             logger.critical(f"{name}: fatal base exception while cancelling task: {e}")
             raise
 
-    def reset_watchdog(self, task: asyncio.Task):
-        name = task.get_name()
-        if name in self._tasks and self._tasks[name].enable_watchdog_timers:
-            self._tasks[name].watchdog_timer.set()
-
     def current_tasks(self) -> Sequence[asyncio.Task]:
-        """Returns the list of currently created/registered tasks."""
-        return [data.task for data in self._tasks.values()]
-
-    def task_reset_watchdog(self):
-        """Resets the running task watchdog timer. If not reset on time, a warning
-        will be logged indicating the task is stalling.
+        """Returns the list of currently created/registered tasks.
 
+        Returns:
+            Sequence of currently managed asyncio tasks.
         """
-        task = asyncio.current_task()
-        if task:
-            self.reset_watchdog(task)
-
-    @property
-    def task_watchdog_enabled(self) -> bool:
-        task = asyncio.current_task()
-        if not task:
-            return False
-        name = task.get_name()
-        return name in self._tasks and self._tasks[name].enable_watchdog_timers
+        return [data.task for data in self._tasks.values()]
 
     def _add_task(self, task_data: TaskData):
-        name = task_data.task.get_name()
-        self._tasks[name] = task_data
-        if self._params and task_data.enable_watchdog_timers:
-            watchdog_task = self.get_event_loop().create_task(
-                self._watchdog_task_handler(task_data)
-            )
-            task_data.watchdog_task = watchdog_task
+        """Add a task to the internal registry.
 
-    async def _watchdog_task_handler(self, task_data: TaskData):
+        Args:
+            task_data: The task metadata.
+        """
         name = task_data.task.get_name()
-        timer = task_data.watchdog_timer
-        enable_watchdog_logging = task_data.enable_watchdog_logging
-        watchdog_timeout = task_data.watchdog_timeout
-
-        while True:
-            try:
-                start_time = time.time()
-                await asyncio.wait_for(timer.wait(), timeout=watchdog_timeout)
-                total_time = time.time() - start_time
-                if enable_watchdog_logging:
-                    logger.debug(f"{name} time between watchdog timer resets: {total_time:.20f}")
-            except asyncio.TimeoutError:
-                logger.warning(
-                    f"{name}: task is taking too long {WATCHDOG_TIMEOUT} second(s) (forgot to reset watchdog?)"
-                )
-            finally:
-                timer.clear()
+        self._tasks[name] = task_data
 
     def _task_done_handler(self, task: asyncio.Task):
+        """Handle task completion by removing the task from the registry.
+
+        Args:
+            task: The completed asyncio task.
+        """
         name = task.get_name()
         try:
-            task_data = self._tasks[name]
-            if task_data.watchdog_task:
-                task_data.watchdog_task.cancel()
-                task_data.watchdog_task = None
             del self._tasks[name]
         except KeyError as e:
             logger.trace(f"{name}: unable to remove task data (already removed?): {e}")

pipecat/utils/base_object.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Base object class providing event handling and lifecycle management.
+
+This module provides the foundational BaseObject class that offers common
+functionality including unique identification, naming, event handling,
+and async cleanup for all Pipecat components.
+"""
+
 import asyncio
 import inspect
 from abc import ABC
@@ -15,7 +22,21 @@ from pipecat.utils.utils import obj_count, obj_id
 
 
 class BaseObject(ABC):
-    def __init__(self, *, name: Optional[str] = None):
+    """Abstract base class providing common functionality for Pipecat objects.
+
+    Provides unique identification, naming, event handling capabilities,
+    and async lifecycle management for all Pipecat components. All major
+    classes in the framework should inherit from this base class.
+    """
+
+    def __init__(self, *, name: Optional[str] = None, **kwargs):
+        """Initialize the base object.
+
+        Args:
+            name: Optional custom name for the object. If not provided,
+                generates a name using the class name and instance count.
+            **kwargs: Additional arguments passed to parent class.
+        """
         self._id: int = obj_id()
         self._name = name or f"{self.__class__.__name__}#{obj_count(self)}"
 
@@ -29,19 +50,44 @@ class BaseObject(ABC):
 
     @property
     def id(self) -> int:
+        """Get the unique identifier for this object.
+
+        Returns:
+            The unique integer ID assigned to this object instance.
+        """
         return self._id
 
     @property
     def name(self) -> str:
+        """Get the name of this object.
+
+        Returns:
+            The object's name, either custom-provided or auto-generated.
+        """
         return self._name
 
     async def cleanup(self):
+        """Clean up resources and wait for running event handlers to complete.
+
+        This method should be called when the object is no longer needed.
+        It waits for all currently executing event handler tasks to finish
+        before returning.
+        """
         if self._event_tasks:
             event_names, tasks = zip(*self._event_tasks)
             logger.debug(f"{self} waiting on event handlers to finish {list(event_names)}...")
             await asyncio.wait(tasks)
 
     def event_handler(self, event_name: str):
+        """Decorator for registering event handlers.
+
+        Args:
+            event_name: The name of the event to handle.
+
+        Returns:
+            The decorator function that registers the handler.
+        """
+
         def decorator(handler):
             self.add_event_handler(event_name, handler)
             return handler
@@ -49,18 +95,37 @@ class BaseObject(ABC):
         return decorator
 
     def add_event_handler(self, event_name: str, handler):
+        """Add an event handler for the specified event.
+
+        Args:
+            event_name: The name of the event to handle.
+            handler: The function to call when the event occurs.
+                Can be sync or async.
+        """
         if event_name in self._event_handlers:
             self._event_handlers[event_name].append(handler)
         else:
             logger.warning(f"Event handler {event_name} not registered")
 
     def _register_event_handler(self, event_name: str):
+        """Register an event handler type.
+
+        Args:
+            event_name: The name of the event type to register.
+        """
         if event_name not in self._event_handlers:
             self._event_handlers[event_name] = []
         else:
             logger.warning(f"Event handler {event_name} not registered")
 
     async def _call_event_handler(self, event_name: str, *args, **kwargs):
+        """Call all registered handlers for the specified event.
+
+        Args:
+            event_name: The name of the event to trigger.
+            *args: Positional arguments to pass to event handlers.
+            **kwargs: Keyword arguments to pass to event handlers.
+        """
         # If we haven't registered an event handler, we don't need to do
         # anything.
         if not self._event_handlers.get(event_name):
@@ -76,6 +141,13 @@ class BaseObject(ABC):
         task.add_done_callback(self._event_task_finished)
 
     async def _run_task(self, event_name: str, *args, **kwargs):
+        """Execute all handlers for an event.
+
+        Args:
+            event_name: The name of the event being handled.
+            *args: Positional arguments to pass to handlers.
+            **kwargs: Keyword arguments to pass to handlers.
+        """
         try:
             for handler in self._event_handlers[event_name]:
                 if inspect.iscoroutinefunction(handler):
@@ -86,9 +158,19 @@ class BaseObject(ABC):
             logger.exception(f"Exception in event handler {event_name}: {e}")
 
     def _event_task_finished(self, task: asyncio.Task):
+        """Clean up completed event handler tasks.
+
+        Args:
+            task: The completed asyncio Task to remove from tracking.
+        """
         tuple_to_remove = next((t for t in self._event_tasks if t[1] == task), None)
         if tuple_to_remove:
             self._event_tasks.discard(tuple_to_remove)
 
     def __str__(self):
+        """Return the string representation of this object.
+
+        Returns:
+            The object's name as its string representation.
+        """
         return self.name

pipecat/utils/network.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Base class for network utilities, providing exponential backoff time calculation."""
+
 
 def exponential_backoff_time(
     attempt: int, min_wait: float = 4, max_wait: float = 10, multiplier: float = 1