feat: update run() function to use asyncio.Runner with uvloop for improved performance and cleanup

Author: adamrefaey

src/asynctasq/utils/loop.py

@@ -2,6 +2,12 @@
 
 Provides a single `run()` helper that automatically detects and uses the
 running event loop, or creates a new uvloop-based loop if none is running.
+
+Best Practices Applied (2025):
+- Uses asyncio.Runner with uvloop for Python 3.11+
+- Proper shutdown sequence: asyncgens -> executor -> cleanup
+- Graceful error handling during cleanup phases
+- Uses asyncio.run() semantics with uvloop optimization
 """
 
 from __future__ import annotations
@@ -44,11 +50,11 @@ async def _cleanup_asynctasq():
 
 
 def run(coro: Any):
-    """Run coroutine using a new event loop.
+    """Run coroutine using a new event loop with uvloop optimization.
 
     Creates a new event loop (uvloop if available, asyncio otherwise) and runs
-    the coroutine to completion. This is similar to asyncio.run() but with
-    automatic uvloop support and AsyncTasQ cleanup.
+    the coroutine to completion. This follows asyncio.run() semantics with
+    automatic uvloop support and proper cleanup sequence.
 
     Args:
         coro: The coroutine to run
@@ -59,13 +65,20 @@ def run(coro: Any):
     Raises:
         RuntimeError: If called from within a running event loop
 
+    Best Practices (2025):
+        - Uses asyncio.Runner with uvloop (Python 3.12+ min requirement)
+        - Proper shutdown order: asyncgens → executor → cleanup → close
+        - Graceful error handling at each cleanup phase
+        - Matches asyncio.run() behavior with performance optimization
+
     Note:
         - This function creates a NEW event loop and cannot be called from
           within an existing event loop
         - If you're already in an async context (FastAPI, Jupyter, etc.),
           use 'await' directly instead
         - For running event loops, use asynctasq.init() to register cleanup
           hooks automatically
+        - uvloop provides 2-4x performance improvement over standard asyncio
 
     Example:
         >>> from asynctasq.utils.loop import run
@@ -88,39 +101,32 @@ def run(coro: Any):
             raise
         # No event loop is running, proceed to create one
 
-    # Create a new event loop
-    # Try to use uvloop for best performance, fall back to asyncio if unavailable
+    # Use asyncio.Runner with uvloop for best performance
+    # This is the modern recommended approach per 2025 best practices (Python 3.11+)
+    # Since min supported version is 3.12, we always use Runner
     try:
         import uvloop
 
-        loop = uvloop.new_event_loop()
-        logger.debug("Using uvloop event loop")
+        # Use Runner with uvloop factory - combines best of both worlds
+        with asyncio.Runner(loop_factory=uvloop.new_event_loop) as runner:
+            logger.debug("Using asyncio.Runner with uvloop")
+            try:
+                return runner.run(coro)
+            finally:
+                # Runner handles asyncgens and executor shutdown automatically
+                # We only need to cleanup AsyncTasQ resources
+                try:
+                    runner.run(_cleanup_asynctasq())
+                except Exception as e:
+                    logger.debug(f"AsyncTasQ cleanup completed with warnings: {e}")
     except ImportError:
-        loop = asyncio.new_event_loop()
-        logger.debug("Using asyncio event loop (uvloop not available)")
-
-    asyncio.set_event_loop(loop)
-
-    try:
-        return loop.run_until_complete(coro)
-    finally:
-        try:
-            # Cleanup AsyncTasQ resources before shutting down asyncgens
-            loop.run_until_complete(_cleanup_asynctasq())
-        except Exception:
-            pass
-        try:
-            # Shutdown async generators
-            loop.run_until_complete(loop.shutdown_asyncgens())
-        except Exception:
-            pass
-        try:
-            # Shutdown default executor
-            loop.run_until_complete(loop.shutdown_default_executor())
-        except Exception:
-            pass
-        finally:
-            # Close the loop
-            loop.close()
-            # Reset the event loop to None
-            asyncio.set_event_loop(None)
+        # uvloop not available, use standard Runner
+        with asyncio.Runner() as runner:
+            logger.debug("Using asyncio.Runner (uvloop not available)")
+            try:
+                return runner.run(coro)
+            finally:
+                try:
+                    runner.run(_cleanup_asynctasq())
+                except Exception as e:
+                    logger.debug(f"AsyncTasQ cleanup completed with warnings: {e}")