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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-rtk
-Version: 2.12.2
+Version: 2.12.4
 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.4}/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.4/fastapi_rtk/_version.py

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

{fastapi_rtk-2.12.2 → fastapi_rtk-2.12.4}/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,7 +22,7 @@ __all__ = [
     "AbstractBaseOprFilter",
     "PydanticGenerationSchema",
     "AbstractInterface",
-    "MissingGreenletError",
+    "AbstractLoopManager",
     "BasicModel",
     "AbstractSession",
     "AbstractUserSerializer",

{fastapi_rtk-2.12.2 → fastapi_rtk-2.12.4}/fastapi_rtk/bases/interface.py

@@ -11,7 +11,7 @@ import pydantic
 import sqlalchemy.exc
 
 from ..const import logger
-from ..exceptions import FastAPIReactToolkitException, raise_exception
+from ..exceptions import MissingGreenletError, raise_exception
 from ..globals import g
 from ..schemas import PRIMARY_KEY, ColumnEnumInfo, ColumnInfo, ColumnRelationInfo
 from ..utils import AsyncTaskRunner, C, T, deep_merge, lazy_self, smart_run
@@ -32,7 +32,6 @@ if typing.TYPE_CHECKING:
 __all__ = [
     "PydanticGenerationSchema",
     "AbstractInterface",
-    "MissingGreenletError",
 ]
 
 
@@ -56,70 +55,6 @@ class PydanticGenerationSchema(typing.TypedDict):
     name_: tuple[type[str], pydantic.Field] | None
 
 
-class MissingGreenletError(FastAPIReactToolkitException):
-    """Raised when an ORM attribute access during pydantic schema validation
-    triggers a SQLAlchemy lazy-load outside the asyncio greenlet.
-
-    Covers both async-property columns (awaited explicitly by
-    ``_populate_async_column``) and regular columns / relationships read by
-    pydantic's ``from_attributes`` machinery.
-
-    The most common causes are:
-
-    - The ORM instance is detached from its session (commit/close happened
-      before the schema was rendered).
-    - The async session was expired between the query and the
-      response-serialisation step.
-    - A relationship the schema reads has not been eager-loaded. Prefer
-      ``selectinload`` / ``joinedload`` on the query, call
-      ``await instance.load("<col>")`` before returning the instance, or
-      add the column to ``list_columns`` / ``show_columns`` (or the
-      narrower ``list_select_columns`` / ``show_select_columns``, or
-      ``extra_list_fetch_columns`` / ``extra_show_fetch_columns`` when
-      the column should be fetched but not surfaced in the response) on
-      the ``ModelRestApi`` subclass so the toolkit eager-loads it for
-      you.
-    """
-
-    def __init__(self, *, model, col: str | None, original: Exception):
-        self.model = model
-        self.col = col
-        self.original = original
-        model_label = type(model).__name__
-        if col is None:
-            super().__init__(
-                f"Failed to validate schema for '{model_label}': SQLAlchemy "
-                f"raised MissingGreenlet while pydantic accessed an attribute. "
-                f"Fix by eager-loading the missing relationship "
-                f"(`selectinload` / `joinedload`), by calling "
-                f'`await instance.load("<col>")` before the instance leaves '
-                f"the async context, or by adding the column to "
-                f"`list_columns` / `show_columns` (or the narrower "
-                f"`list_select_columns` / `show_select_columns`, or "
-                f"`extra_list_fetch_columns` / `extra_show_fetch_columns` "
-                f"when the column should be fetched but not surfaced in the "
-                f"response) on the ModelRestApi subclass. Original error: "
-                f"{original!r}."
-            )
-        else:
-            super().__init__(
-                f"Failed to populate column '{col}' on '{model_label}': "
-                f"SQLAlchemy raised MissingGreenlet. The ORM attempted I/O "
-                f"outside the async greenlet. Fix by eager-loading the "
-                f"underlying relationship "
-                f"(e.g. add `selectinload({model_label}.{col})` or "
-                f"`joinedload({model_label}.{col})` to the query), by "
-                f'calling `await instance.load("{col}")` before the instance '
-                f'leaves the async context, or by adding `"{col}"` to '
-                f"`list_columns` / `show_columns` (or the narrower "
-                f"`list_select_columns` / `show_select_columns`, or "
-                f"`extra_list_fetch_columns` / `extra_show_fetch_columns` "
-                f"when the column should be fetched but not surfaced in the "
-                f"response) on the ModelRestApi subclass. Original error: "
-                f"{original!r}."
-            )
-
-
 class lazy(lazy_self["AbstractInterface", T]): ...
 
 
@@ -1081,7 +1016,7 @@ class AbstractInterface(abc.ABC, typing.Generic[T, C, CT]):
         try:
             value = await getattr(model, col)
         except sqlalchemy.exc.MissingGreenlet as e:
-            raise MissingGreenletError(
+            raise MissingGreenletError.from_attribute_read(
                 model=model,
                 col=col,
                 original=e,
@@ -1119,7 +1054,7 @@ class AbstractInterface(abc.ABC, typing.Generic[T, C, CT]):
                 try:
                     getattr(value, field_name)
                 except sqlalchemy.exc.MissingGreenlet as e:
-                    raise MissingGreenletError(
+                    raise MissingGreenletError.from_attribute_read(
                         model=value,
                         col=field_name,
                         original=e,

fastapi_rtk-2.12.4/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.4/fastapi_rtk/exceptions.py

@@ -0,0 +1,235 @@
+import types
+import typing
+
+import fastapi
+import pydantic
+import sqlalchemy.exc
+
+from .utils import T, prettify_dict
+
+__all__ = [
+    "raise_exception",
+    "FastAPIReactToolkitException",
+    "RolesMismatchException",
+    "HTTPWithValidationException",
+    "MissingGreenletError",
+]
+
+
+def raise_exception(message: str, return_type: type[T] | None = None) -> T:
+    """
+    Raise a FastAPIReactToolkitException with the given message.
+
+    Args:
+        message (str): The error message.
+        return_type (type[T] | None, optional): The expected return type. Defaults to None.
+
+    Raises:
+        FastAPIReactToolkitException: Always raised.
+
+    Returns:
+        T: The return value.
+    """
+    raise FastAPIReactToolkitException(message)
+
+
+class FastAPIReactToolkitException(Exception):
+    """Base exception for FastAPI React Toolkit errors."""
+
+
+class RolesMismatchException(FastAPIReactToolkitException):
+    """Exception raised when the roles do not match the expected roles."""
+
+
+class HTTPWithValidationException(fastapi.HTTPException):
+    """
+    Custom HTTP Exception for FastAPI with validation details.
+    """
+
+    URL = f"https://errors.pydantic.dev/{pydantic.version.version_short()}/v"
+    _no_input = object()
+
+    def __init__(
+        self,
+        status_code: int,
+        type: str,
+        location_type: typing.Literal["path", "query", "body"],
+        field: str,
+        msg: str,
+        input: typing.Any = _no_input,
+        headers: dict[str, str] | None = None,
+    ):
+        """
+        Initialize the HTTPWithValidationException.
+
+        Args:
+            status_code (int): HTTP status code for the exception.
+            type (str): Type of the error (e.g., "string_type", "validation_error").
+            location_type (typing.Literal["path", "query", "body"]): Location type of the error, either "path", "query", or "body".
+            field (str): Field name where the error occurred.
+            msg (str): Error message describing the validation issue.
+            input (typing.Any, optional): Optional input value that caused the error. Defaults to _no_input.
+            headers (dict[str, str] | None, optional): Optional headers to include in the response. Defaults to None.
+        """
+        obj = {"type": type, "loc": [location_type, field], "msg": msg}
+        if input is not self._no_input:
+            if isinstance(input, pydantic.BaseModel):
+                input = input.model_dump(mode="json")
+            else:
+                input = str(input)
+            obj["input"] = input
+        obj["url"] = f"{self.URL}/{type}"
+
+        super().__init__(status_code, [obj], headers)
+
+
+class MissingGreenletError(FastAPIReactToolkitException):
+    """Raised when an ORM attribute access triggers a SQLAlchemy lazy-load
+    outside the asyncio greenlet.
+
+    Covers async-property columns (awaited explicitly by
+    ``_populate_async_column``), regular columns / relationships read by
+    pydantic's ``from_attributes`` machinery, and any attribute read by
+    application code during a request (hooks, filters, custom endpoints),
+    which ``globals_middleware_dispatch`` converts through
+    ``from_lazy_load``.
+
+    The most common causes are:
+
+    - The ORM instance is detached from its session (commit/close happened
+      before the schema was rendered).
+    - The async session was expired between the query and the
+      response-serialisation step.
+    - A relationship the schema reads has not been eager-loaded. Prefer
+      ``selectinload`` / ``joinedload`` on the query, call
+      ``await instance.load("<col>")`` before returning the instance, or
+      add the column to ``list_columns`` / ``show_columns`` (or the
+      narrower ``list_select_columns`` / ``show_select_columns``, or
+      ``extra_list_fetch_columns`` / ``extra_show_fetch_columns`` when
+      the column should be fetched but not surfaced in the response) on
+      the ``ModelRestApi`` subclass so the toolkit eager-loads it for
+      you.
+    """
+
+    def __init__(
+        self,
+        *,
+        model,
+        col: str | None,
+        source: str | None = None,
+        original: Exception,
+    ):
+        self.model = model
+        self.col = col
+        self.original = original
+        self.source = source
+        model_label = type(model).__name__
+        col_label = col or "<col>"
+        detail = {}
+        if col is None:
+            detail["problem"] = (
+                f"Failed to validate schema for '{model_label}': SQLAlchemy raised "
+                f"MissingGreenlet while pydantic read an attribute."
+            )
+        else:
+            detail["problem"] = (
+                f"Failed to populate column '{col}' on '{model_label}': SQLAlchemy "
+                f"raised MissingGreenlet, the ORM attempted I/O outside the async "
+                f"greenlet."
+            )
+        if source:
+            detail["accessed at"] = source
+        detail["fix by any of"] = [
+            f"Eager-load the relationship: add `selectinload({model_label}.{col_label})` or `joinedload({model_label}.{col_label})` to the query.",
+            f'Load it before the instance leaves the async context: `await instance.load("{col_label}")`.',
+            f'Add `"{col_label}"` to `list_columns` / `show_columns` on the ModelRestApi subclass, or to the narrower `list_select_columns` / `show_select_columns`.',
+            f'Add `"{col_label}"` to `extra_list_fetch_columns` / `extra_show_fetch_columns` when the column should be fetched but not surfaced in the response.',
+        ]
+        detail["original error"] = repr(original)
+        super().__init__("\n" + prettify_dict(detail))
+
+    @classmethod
+    def from_lazy_load(cls, original: sqlalchemy.exc.MissingGreenlet):
+        """
+        Build an enriched error from a MissingGreenlet raised by an ORM attribute read.
+
+        Args:
+            original (sqlalchemy.exc.MissingGreenlet): The exception SQLAlchemy raised.
+
+        Returns:
+            MissingGreenletError | None: The enriched error, or None when the traceback carries no ORM attribute read to name.
+        """
+        model, col = _lazy_load_target(original.__traceback__)
+        if model is None or col is None:
+            return None
+        return cls.from_attribute_read(model=model, col=col, original=original)
+
+    @classmethod
+    def from_attribute_read(cls, *, model, col: str | None, original: Exception):
+        """
+        Build the error for a known model and column, taking the call site from the traceback.
+
+        Args:
+            model: The model whose attribute was read.
+            col (str | None): The column that was read, or None when pydantic validation failed on an unnamed attribute.
+            original (Exception): The exception SQLAlchemy raised.
+
+        Returns:
+            MissingGreenletError: The error, carrying the call site when the traceback holds one.
+        """
+        return cls(
+            model=model,
+            col=col,
+            source=_lazy_load_source(original.__traceback__),
+            original=original,
+        )
+
+
+def _lazy_load_target(tb: types.TracebackType | None):
+    """
+    Find the ORM instance and attribute name whose read triggered a lazy load.
+
+    Args:
+        tb (types.TracebackType | None): Traceback of the raised MissingGreenlet.
+
+    Returns:
+        tuple: The ORM instance and its column name, or (None, None) when the traceback holds no attribute read.
+    """
+    while tb is not None:
+        frame = tb.tb_frame
+        if (
+            frame.f_code.co_name == "__get__"
+            and frame.f_globals.get("__name__") == "sqlalchemy.orm.attributes"
+        ):
+            instance = frame.f_locals.get("instance")
+            col = getattr(frame.f_locals.get("self"), "key", None)
+            if instance is not None and col:
+                return instance, col
+        tb = tb.tb_next
+    return None, None
+
+
+def _lazy_load_source(tb: types.TracebackType | None):
+    """
+    Locate the call site that triggered the lazy load, the last non-toolkit frame before SQLAlchemy took over.
+
+    Toolkit frames are skipped because the schema-validation probe reads every field itself, so its own line names no code the reader can act on.
+
+    Args:
+        tb (types.TracebackType | None): Traceback of the raised MissingGreenlet.
+
+    Returns:
+        str | None: A "path:line in function" label, or None when only SQLAlchemy and toolkit frames read the attribute.
+    """
+    caller = None
+    while tb is not None:
+        module = tb.tb_frame.f_globals.get("__name__", "")
+        if module.startswith("sqlalchemy."):
+            break
+        if not module.startswith("fastapi_rtk."):
+            caller = tb
+        tb = tb.tb_next
+    if caller is None:
+        return None
+    code = caller.tb_frame.f_code
+    return f"{code.co_filename}:{caller.tb_lineno} in {code.co_name}"

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

@@ -40,6 +40,7 @@ import contextvars
 import typing
 
 import fastapi
+import sqlalchemy.exc
 import starlette.middleware.base
 import starlette.types
 import werkzeug.local
@@ -51,11 +52,13 @@ from .const import (
     COOKIE_CONFIG,
     COOKIE_STRATEGY_CONFIG,
 )
+from .exceptions import MissingGreenletError
 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 +120,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`.
@@ -235,14 +242,31 @@ async def globals_middleware_dispatch(
     request: fastapi.Request,
     call_next: collections.abc.Callable,
 ) -> fastapi.Response:
-    """Dispatch the request in a new context to allow globals to be used."""
+    """
+    Dispatch the request in a new context to allow globals to be used.
 
+    Args:
+        request (fastapi.Request): The incoming request.
+        call_next (collections.abc.Callable): The next handler in the middleware chain.
+
+    Raises:
+        MissingGreenletError: When a lazy-load of an ORM attribute happened outside the asyncio greenlet, naming the model, the column, and the call site.
+
+    Returns:
+        fastapi.Response: The response produced by the rest of the chain.
+    """
     ctx = contextvars.copy_context()
 
     def _call_next() -> collections.abc.Awaitable[fastapi.Response]:
         return call_next(request)
 
-    return await ctx.run(_call_next)
+    try:
+        return await ctx.run(_call_next)
+    except sqlalchemy.exc.MissingGreenlet as e:
+        enriched = MissingGreenletError.from_lazy_load(e)
+        if not enriched:
+            raise
+        raise enriched from e
 
 
 class GlobalsMiddleware(starlette.middleware.base.BaseHTTPMiddleware):  # noqa
@@ -341,6 +365,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.4/fastapi_rtk/loop_managers/__init__.py

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