fastapi-rtk 2.12.2__tar.gz → 2.12.3__tar.gz

{fastapi_rtk-2.12.2 → fastapi_rtk-2.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-rtk
-Version: 2.12.2
+Version: 2.12.3
 Summary: A package that provides a set of tools to build a FastAPI application with a Class-Based CRUD API.
 Project-URL: Homepage, https://codeberg.org/datatactics/fastapi-rtk
 Project-URL: Issues, https://codeberg.org/datatactics/fastapi-rtk/issues

{fastapi_rtk-2.12.2 → fastapi_rtk-2.12.3}/fastapi_rtk/__init__.py

@@ -17,6 +17,7 @@ from .fastapi_react_toolkit import *
 from .file_managers import *
 from .globals import *
 from .lang import *
+from .loop_managers import *
 from .manager import *
 from .mixins import *
 from .routers import *
@@ -158,6 +159,7 @@ __all__ = [
     "AbstractBaseOprFilter",
     "PydanticGenerationSchema",
     "AbstractInterface",
+    "AbstractLoopManager",
     "MissingGreenletError",
     "BasicModel",
     "AbstractSession",
@@ -209,6 +211,8 @@ __all__ = [
     "lazy_text",
     "translate",
     "_",
+    # .loop_managers
+    "LoopManager",
     # .manager
     "UserManager",
     # .mixins

fastapi_rtk-2.12.3/fastapi_rtk/_version.py

@@ -0,0 +1 @@
+__version__ = "2.12.3"

{fastapi_rtk-2.12.2 → fastapi_rtk-2.12.3}/fastapi_rtk/bases/__init__.py

@@ -3,6 +3,7 @@ from .db import *
 from .file_manager import *
 from .filter import *
 from .interface import *
+from .loop_manager import *
 from .model import *
 from .session import *
 from .user_cache import *
@@ -21,6 +22,7 @@ __all__ = [
     "AbstractBaseOprFilter",
     "PydanticGenerationSchema",
     "AbstractInterface",
+    "AbstractLoopManager",
     "MissingGreenletError",
     "BasicModel",
     "AbstractSession",

fastapi_rtk-2.12.3/fastapi_rtk/bases/loop_manager.py

@@ -0,0 +1,47 @@
+import abc
+import asyncio
+
+__all__ = ["AbstractLoopManager"]
+
+
+class AbstractLoopManager(abc.ABC):
+    """
+    Supplies the event loop that synchronous callers submit coroutines to.
+
+    Implement this to control which loop `smart_run_sync` / `safe_call_sync` reach for when no loop is passed, e.g. to hand them a loop the host application already runs. The loop must be running in another thread, because the calling thread blocks on the result.
+    """
+
+    @property
+    @abc.abstractmethod
+    def loop(self) -> asyncio.AbstractEventLoop:
+        """
+        The loop to submit coroutines to, started if it was not running yet.
+
+        Returns:
+            asyncio.AbstractEventLoop: A running event loop owned by another thread.
+        """
+
+    @abc.abstractmethod
+    def shutdown(self) -> None:
+        """
+        Stop the loops this manager owns, if it started any.
+
+        Returns:
+            None: The next `loop` access builds a fresh loop.
+        """
+
+    def loop_for(
+        self, current: asyncio.AbstractEventLoop | None
+    ) -> asyncio.AbstractEventLoop:
+        """
+        The loop to use for a caller already running on ``current``.
+
+        Blocking a thread for a task on the loop that thread runs would deadlock, since nothing is left to run the task. Override to hand such a caller a different loop; this default ignores ``current`` and is therefore only safe for callers that never run on the returned loop.
+
+        Args:
+            current (asyncio.AbstractEventLoop | None): The loop running in the calling thread, or None outside one.
+
+        Returns:
+            asyncio.AbstractEventLoop: The loop to submit to.
+        """
+        return self.loop

{fastapi_rtk-2.12.2 → fastapi_rtk-2.12.3}/fastapi_rtk/globals.py

@@ -56,6 +56,7 @@ from .utils import lazy, lazy_import
 if typing.TYPE_CHECKING:
     from .auth import AuthConfigurator
     from .bases.file_manager import AbstractFileManager, AbstractImageManager
+    from .bases.loop_manager import AbstractLoopManager
     from .caches import Cache
     from .fastapi_react_toolkit import FastAPIReactToolkit
     from .security.sqla.models import User
@@ -117,6 +118,10 @@ class Globals:
     """
     The cache object used by caching features such as `AUTH_USER_CACHE_TTL`. Defaults to `Cache` from `fastapi_rtk.caches.cache`, which keeps entries in an `InMemoryCacheStorage`.
     """
+    loop_manager: "AbstractLoopManager"
+    """
+    The object supplying the event loop `smart_run_sync` / `safe_call_sync` submit to when given no loop. Defaults to the `LOOP_MANAGER` config key, or `LoopManager` from `fastapi_rtk.loop_managers.loop_manager`, which runs one long-lived loop per nesting depth, each on its own daemon thread.
+    """
     user_cache: "UserCache"
     """
     The object that stores and rebuilds authenticated users in `g.cache`. Defaults to the `AUTH_USER_CACHE` config key, or `UserCache` from `fastapi_rtk.security.sqla.user_cache`.
@@ -341,6 +346,15 @@ g.set_default(
         )
     ),
 )
+g.set_default(
+    "loop_manager",
+    lazy(
+        lambda: (
+            lazy_import("fastapi_rtk.setting", lambda mod: mod.Setting.LOOP_MANAGER)()
+            or lazy_import("fastapi_rtk.loop_managers", lambda mod: mod.LoopManager())()
+        )
+    ),
+)
 g.config.add_callback(basic_callback)
 
 # Local Proxies

fastapi_rtk-2.12.3/fastapi_rtk/loop_managers/__init__.py

@@ -0,0 +1,3 @@
+from .loop_manager import *
+
+__all__ = ["LoopManager"]

fastapi_rtk-2.12.3/fastapi_rtk/loop_managers/loop_manager.py

@@ -0,0 +1,232 @@
+import asyncio
+import os
+import threading
+import typing
+import weakref
+
+from ..bases.loop_manager import AbstractLoopManager
+from ..const import logger as _root_logger
+
+__all__ = ["LoopManager"]
+
+logger = _root_logger.getChild("loop_manager")
+
+
+class LoopManager(AbstractLoopManager):
+    """
+    Runs long-lived event loops on daemon threads, one per nesting depth.
+
+    Reusing loops keeps loop-bound resources (asyncpg pools, redis asyncio clients, `asyncio.Lock`) valid across calls and stops every synchronous call from leaving a closed loop behind. Depth 0 serves ordinary callers; a caller already running on the depth-N loop gets depth N+1, so a synchronous event handler whose session commits inside a coroutine on one loop can still submit work without blocking that loop against itself. Loops are created on first need, restarted when one stops on its own, and forgotten in a forked child (Celery's prefork pool), whose inherited loops have no thread to drain them.
+
+    Attributes:
+        thread_name (str): Prefix of the thread names, suffixed with the depth.
+    """
+
+    thread_name = "fastapi-rtk-loop"
+
+    _managers: typing.ClassVar["weakref.WeakSet[LoopManager]"] = weakref.WeakSet()
+    """
+    Every live manager, so the fork handler can reset each one in the child. Weakly held, so a manager nobody uses is collected instead of being reset on every later fork.
+    """
+
+    def __init__(self):
+        self._loops: list[_Loop] = []
+        self._lock = threading.Lock()
+        self._managers.add(self)
+
+    @property
+    def loop(self) -> asyncio.AbstractEventLoop:
+        """
+        The loop ordinary callers submit to.
+
+        Returns:
+            asyncio.AbstractEventLoop: The depth-0 loop, started if it was not running yet.
+        """
+        return self._loop_at(0)
+
+    def loop_for(
+        self, current: asyncio.AbstractEventLoop | None
+    ) -> asyncio.AbstractEventLoop:
+        """
+        The loop to use for a caller running on ``current``.
+
+        Args:
+            current (asyncio.AbstractEventLoop | None): The loop running in the calling thread, or None outside one.
+
+        Returns:
+            asyncio.AbstractEventLoop: The next depth down when ``current`` is one of this manager's loops, else the depth-0 loop.
+        """
+        for depth, entry in enumerate(self._loops):
+            if entry.loop is current:
+                return self._loop_at(depth + 1)
+        return self._loop_at(0)
+
+    def shutdown(self) -> None:
+        """
+        Stop every loop this manager started and let their threads finish.
+
+        Coroutines still running are cancelled first, so a caller blocked on one raises `concurrent.futures.CancelledError` instead of waiting forever on a loop that stopped under it.
+
+        Returns:
+            None: The next `loop` access builds a fresh loop.
+        """
+        with self._lock:
+            entries, self._loops = self._loops, []
+        for entry in entries:
+            entry.stopped.set()
+            _cancel_and_stop(entry.loop)
+
+    def _loop_at(self, depth: int) -> asyncio.AbstractEventLoop:
+        """
+        Return the loop for one nesting depth, creating loops up to it.
+
+        Args:
+            depth (int): The nesting depth to serve.
+
+        Returns:
+            asyncio.AbstractEventLoop: The running loop held at that depth.
+        """
+        entries = self._loops
+        if depth < len(entries) and entries[depth].serving:
+            return entries[depth].loop
+        with self._lock:
+            while len(self._loops) <= depth:
+                self._loops.append(self._start_loop(len(self._loops)))
+            if not self._loops[depth].serving:
+                self._loops[depth] = self._start_loop(depth)
+            return self._loops[depth].loop
+
+    def _start_loop(self, depth: int) -> "_Loop":
+        """
+        Start a loop on its own daemon thread.
+
+        Args:
+            depth (int): The nesting depth the loop serves, used in the thread name.
+
+        Returns:
+            _Loop: The loop now running on that thread, with the thread and its stop flag.
+        """
+        loop = asyncio.new_event_loop()
+        stopped = threading.Event()
+        thread = threading.Thread(
+            target=_serve,
+            args=(loop, stopped),
+            name=f"{self.thread_name}-{depth}",
+            daemon=True,
+        )
+        thread.start()
+        return _Loop(loop, thread, stopped)
+
+    @classmethod
+    def _reset_all_after_fork(cls) -> None:
+        """
+        Reset every live manager in a freshly forked child.
+
+        Runs in the child's only thread before anything else can reach a manager, so nothing waits on a lock the fork inherited locked, and no child ever submits to a parent loop whose thread it did not inherit.
+
+        Returns:
+            None: Each manager starts fresh loops on its next use.
+        """
+        for manager in cls._managers:
+            manager._reset_after_fork()
+
+    def _reset_after_fork(self) -> None:
+        """
+        Forget the parent's loops, whose threads do not exist in this child.
+
+        The lock is replaced rather than taken: only the forking thread survives a fork, so a lock another thread held at that moment is inherited locked with nobody left to release it.
+
+        Returns:
+            None: The next `loop` access starts fresh loops.
+        """
+        self._loops = []
+        self._lock = threading.Lock()
+
+
+class _Loop(typing.NamedTuple):
+    """
+    One loop a `LoopManager` holds, with the thread serving it.
+
+    Attributes:
+        loop (asyncio.AbstractEventLoop): The loop coroutines are submitted to.
+        thread (threading.Thread): The daemon thread running it.
+        stopped (threading.Event): Set by `LoopManager.shutdown` to let that thread finish.
+    """
+
+    loop: asyncio.AbstractEventLoop
+    thread: threading.Thread
+    stopped: threading.Event
+
+    @property
+    def serving(self) -> bool:
+        """
+        Whether this loop can still accept coroutines.
+
+        Returns:
+            bool: True while its thread is alive and the loop is open.
+        """
+        return self.thread.is_alive() and not self.loop.is_closed()
+
+
+def _serve(loop: asyncio.AbstractEventLoop, stopped: threading.Event) -> None:
+    """
+    Run one loop until its manager stops it, restarting it if it stops on its own.
+
+    A `KeyboardInterrupt` or `SystemExit` raised inside a submitted coroutine propagates out of `run_forever`, and outside code can call `loop.stop()`. Either would otherwise end this thread while the loop still looks usable, and every later submission to it would block forever. A loop closed from outside cannot be restarted, so the thread gives it up and the manager builds a new one on next use.
+
+    Args:
+        loop (asyncio.AbstractEventLoop): The loop to run.
+        stopped (threading.Event): Set when the loop should be given up rather than restarted.
+
+    Returns:
+        None: The loop is closed once this returns.
+    """
+    asyncio.set_event_loop(loop)
+    try:
+        while not stopped.is_set() and not loop.is_closed():
+            try:
+                loop.run_forever()
+            except BaseException:
+                logger.exception("Event loop %s crashed, restarting it", loop)
+    finally:
+        loop.close()
+
+
+def _cancel_and_stop(loop: asyncio.AbstractEventLoop) -> None:
+    """
+    Cancel everything running on a loop, then stop it.
+
+    Args:
+        loop (asyncio.AbstractEventLoop): The loop to drain, running in another thread.
+
+    Returns:
+        None: The loop stops once the cancelled coroutines have finished.
+    """
+    if loop.is_closed():
+        return
+    try:
+        asyncio.run_coroutine_threadsafe(_cancel_all(), loop)
+    except RuntimeError:
+        logger.debug("Event loop %s was already gone when stopping it", loop)
+
+
+async def _cancel_all() -> None:
+    """
+    Cancel every other task on this loop, wait for them, then stop the loop.
+
+    Returns:
+        None: The loop is stopped when this returns.
+    """
+    loop = asyncio.get_running_loop()
+    tasks = [
+        task for task in asyncio.all_tasks(loop) if task is not asyncio.current_task()
+    ]
+    for task in tasks:
+        task.cancel()
+    if tasks:
+        await asyncio.gather(*tasks, return_exceptions=True)
+    loop.stop()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=LoopManager._reset_all_after_fork)

{fastapi_rtk-2.12.2 → fastapi_rtk-2.12.3}/fastapi_rtk/setting.py

@@ -21,6 +21,7 @@ from .globals import g
 
 if typing.TYPE_CHECKING:
     from .bases.file_manager import AbstractFileManager, AbstractImageManager
+    from .bases.loop_manager import AbstractLoopManager
     from .bases.user_cache import AbstractUserSerializer
     from .caches import Cache
     from .security.sqla.user_cache import UserCache
@@ -151,6 +152,13 @@ class _Setting:
         """
         return g.config.get("CACHE")
 
+    @property
+    def LOOP_MANAGER(self) -> "AbstractLoopManager | None":
+        """
+        The manager supplying the event loop `smart_run_sync` / `safe_call_sync` submit to when given no loop.
+        """
+        return g.config.get("LOOP_MANAGER")
+
     @property
     def FILE_ALLOWED_EXTENSIONS(self) -> list[str] | None:
         return g.config.get("FILE_ALLOWED_EXTENSIONS")

{fastapi_rtk-2.12.2 → fastapi_rtk-2.12.3}/fastapi_rtk/utils/run_utils.py

@@ -59,7 +59,7 @@ def smart_run_sync(
     Args:
         func (collections.abc.Callable[..., T | collections.abc.Awaitable[T]]): The function to be executed.
         *args: Positional arguments to be passed to the function.
-        loop (asyncio.AbstractEventLoop | None, optional): A running event loop to submit an async ``func`` to. Defaults to None, which runs it on a fresh loop in a thread pool.
+        loop (asyncio.AbstractEventLoop | None, optional): A running event loop to submit an async ``func`` to. Defaults to None, which uses the loop `g.loop_manager` supplies.
         **kwargs: Keyword arguments to be passed to the function.
 
     Returns:
@@ -98,9 +98,9 @@ def safe_call_sync(
 
     Args:
         result_or_coro (T | collections.abc.Coroutine[typing.Any, typing.Any, T]): The result or coroutine to be executed.
-        max_workers (int, optional): The maximum number of workers in the thread pool. Defaults to 1.
-        loop (asyncio.AbstractEventLoop | None, optional): A running event loop to submit the coroutine to. Defaults to None, which runs the coroutine on a fresh loop in a thread pool.
-        **kwargs: Additional keyword arguments to pass to the `ThreadPoolExecutor`.
+        max_workers (int, optional): Unused, kept so existing callers still type-check. Defaults to 1.
+        loop (asyncio.AbstractEventLoop | None, optional): A running event loop to submit the coroutine to. Defaults to None, which uses the loop `g.loop_manager` supplies.
+        **kwargs: Additional keyword arguments forwarded to `run_coroutine_in_threadpool`, which ignores them.
 
     Returns:
         T: The result of the function call or coroutine.
@@ -119,31 +119,28 @@ def run_coroutine_in_threadpool(
     **kwargs,
 ):
     """
-    Run a coroutine in a thread pool executor.
+    Run a coroutine on a long-lived event loop from a synchronous caller.
+
+    ``loop`` is submitted to when given; otherwise ``g.loop_manager`` picks a
+    long-lived loop, avoiding the one the calling thread already runs. Reusing
+    loops keeps loop-bound resources (asyncpg pools, redis asyncio clients,
+    ``asyncio.Lock``) valid across calls and stops every call from leaving a
+    closed loop behind. The caller's context is copied so contextvars set
+    before the call are visible inside the coroutine.
 
-    When ``loop`` is given, the coroutine is submitted to that already-running
-    loop via ``asyncio.run_coroutine_threadsafe`` instead of a throwaway loop.
-    This keeps loop-bound resources (asyncpg pools, redis asyncio clients,
-    ``asyncio.Lock``) valid across calls; ``max_workers`` and ``**kwargs`` are
-    then unused. The caller owns the loop and must run it in another thread.
+    Passing a ``loop`` the calling thread itself runs deadlocks, since blocking
+    that thread leaves nothing to run the task.
 
     Args:
         coro (collections.abc.Coroutine[typing.Any, typing.Any, T]): The coroutine to run.
-        max_workers (int, optional): The maximum number of workers in the thread pool. Defaults to 1.
-        loop (asyncio.AbstractEventLoop | None, optional): A running event loop to submit the coroutine to. Defaults to None, which runs the coroutine on a fresh loop in a thread pool.
-        **kwargs: Additional keyword arguments to pass to the `ThreadPoolExecutor`.
+        max_workers (int, optional): Unused, kept so existing callers still type-check. Defaults to 1.
+        loop (asyncio.AbstractEventLoop | None, optional): A running event loop to submit the coroutine to. Defaults to None, which uses the loop `g.loop_manager` supplies.
+        **kwargs: Unused, kept so existing callers still type-check.
 
     Returns:
         T: The result of the coroutine.
     """
-    if loop is not None:
-        return asyncio.run_coroutine_threadsafe(coro, loop).result()
-    with concurrent.futures.ThreadPoolExecutor(
-        max_workers=max_workers, **kwargs
-    ) as executor:
-        ctx = contextvars.copy_context()
-        future = executor.submit(ctx.run, asyncio.run, coro)
-        return future.result()
+    return _submit_to_loop(coro, loop if loop is not None else _managed_loop())
 
 
 def run_function_in_threadpool(
@@ -228,3 +225,77 @@ def parse_from_values_or_func(
     if callable(value_or_func):
         return value_or_func(*args, **kwargs)
     return value_or_func
+
+
+def _managed_loop() -> asyncio.AbstractEventLoop:
+    """
+    Return the loop the configured loop manager picks for this caller.
+
+    The loop already running in this thread is passed along, so the manager can
+    hand back a different one: blocking a thread for a task on its own loop
+    would deadlock, since nothing is left to run the task. ``g`` is imported
+    here rather than at module scope, because ``globals`` imports this package
+    while loading.
+
+    Returns:
+        asyncio.AbstractEventLoop: The loop `g.loop_manager` supplies for this caller.
+    """
+    from ..globals import g
+
+    return g.loop_manager.loop_for(_running_loop())
+
+
+def _submit_to_loop(
+    coro: collections.abc.Coroutine[typing.Any, typing.Any, T],
+    loop: asyncio.AbstractEventLoop,
+) -> T:
+    """
+    Run a coroutine on another thread's loop and block for its result.
+
+    The coroutine runs as a task on that loop, so it starts with the loop
+    thread's contextvars rather than the caller's. The caller's values are
+    copied in first, inside the task's own context, so nothing leaks between
+    concurrent callers.
+
+    Args:
+        coro (collections.abc.Coroutine[typing.Any, typing.Any, T]): The coroutine to run.
+        loop (asyncio.AbstractEventLoop): The loop to run it on, running in another thread.
+
+    Returns:
+        T: The result of the coroutine.
+    """
+    return asyncio.run_coroutine_threadsafe(
+        _with_context(contextvars.copy_context(), coro), loop
+    ).result()
+
+
+def _running_loop() -> asyncio.AbstractEventLoop | None:
+    """
+    Return the loop running in this thread, if any.
+
+    Returns:
+        asyncio.AbstractEventLoop | None: The running loop, or None outside one.
+    """
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        return None
+
+
+async def _with_context(
+    context: contextvars.Context,
+    coro: collections.abc.Coroutine[typing.Any, typing.Any, T],
+) -> T:
+    """
+    Await a coroutine with another context's variables applied.
+
+    Args:
+        context (contextvars.Context): The context whose variables to apply.
+        coro (collections.abc.Coroutine[typing.Any, typing.Any, T]): The coroutine to await.
+
+    Returns:
+        T: The result of the coroutine.
+    """
+    for variable, value in context.items():
+        variable.set(value)
+    return await coro