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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-rtk
-Version: 2.12.3
+Version: 2.13.0
 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.13.0/fastapi_rtk/_version.py

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

{fastapi_rtk-2.12.3 → fastapi_rtk-2.13.0}/fastapi_rtk/backends/generic/column.py

@@ -1,4 +1,5 @@
 import collections.abc
+import copy
 import inspect
 import typing
 
@@ -6,7 +7,11 @@ import pydantic
 
 from ...mixins import LoggerMixin
 from ...utils import T
-from .exceptions import ColumnInvalidTypeException, GenericColumnException
+from .exceptions import (
+    ColumnInvalidTypeException,
+    ColumnNotSetException,
+    GenericColumnException,
+)
 
 if typing.TYPE_CHECKING:
     from .model import GenericModel
@@ -45,7 +50,7 @@ class GenericColumn(typing.Generic[T], LoggerMixin):
         auto_increment (bool, optional): Whether the column is auto incremented. Only works if the column is a primary key. Defaults to False.
         unique (bool, optional): Whether the column is unique. Defaults to False.
         nullable (bool, optional): Whether the column is nullable. Defaults to True.
-        default (T | collections.abc.Callable[[], T] | collections.abc.Callable[[GenericModel], T] | NoDefault, optional): The default value of the column. Will be used if the column is not set by the user. Defaults to NoDefault (no default value).
+        default (T | collections.abc.Callable[[], T] | collections.abc.Callable[[GenericModel], T] | NoDefault, optional): The default value of the column. Will be used if the column is not set by the user. It is resolved once, when the model is initialized: a callable taking no argument is called, and a mutable value is copied. Defaults to NoDefault (no default value).
     """
 
     col_type: type[T]
@@ -78,7 +83,7 @@ class GenericColumn(typing.Generic[T], LoggerMixin):
             auto_increment (bool, optional): Whether the column is auto incremented. Only works if the column is a primary key. Defaults to False.
             unique (bool, optional): Whether the column is unique. Defaults to False.
             nullable (bool, optional): Whether the column is nullable. Defaults to True.
-            default (T | collections.abc.Callable[[], T] | collections.abc.Callable[["GenericModel"], T] | _NoDefaultValue, optional): The default value of the column. Will be used if the column is not set by the user. Defaults to UNSET (no default value).
+            default (T | collections.abc.Callable[[], T] | collections.abc.Callable[["GenericModel"], T] | _NoDefaultValue, optional): The default value of the column. Will be used if the column is not set by the user. It is resolved once, when the model is initialized: a callable taking no argument is called, and a mutable value is copied. Defaults to UNSET (no default value).
 
         Raises:
             GenericColumnException: If auto increment is set on a non-primary key column or if the column type is not int when auto increment is set.
@@ -95,10 +100,8 @@ class GenericColumn(typing.Generic[T], LoggerMixin):
             self.unique = True
             self.nullable = False
 
-        if inspect.isfunction(self.default):
-            # If the function takes no parameters, convert it to a function that needs the instance
-            if inspect.signature(self.default).parameters == {}:
-                self.default = lambda instance, func=self.default: func()
+        if self.default is not UNSET:
+            self.default = self._normalize_default(self.default)
 
         if not self.primary_key and self.auto_increment:
             raise GenericColumnException(
@@ -125,22 +128,30 @@ class GenericColumn(typing.Generic[T], LoggerMixin):
         instance: "GenericModel | None",
         owner: type["GenericModel"],
     ):
+        """
+        Read the column value of the instance, or the descriptor itself when read on the class.
+
+        Args:
+            instance (GenericModel | None): The instance to read from, or None when read on the class.
+            owner (type[GenericModel]): The model class owning the column.
+
+        Raises:
+            ColumnNotSetException: If a column that is neither nullable nor an auto incrementing primary key was never set.
+
+        Returns:
+            GenericColumn | T | None: The descriptor on class access, else the value, None for an unset nullable column, or PK_AUTO_INCREMENT for an unset auto incrementing primary key.
+        """
         if not instance:
             return self
 
-        default_value = self.default
-        if callable(default_value):
-            default_value = default_value(instance)
-
-        value: T | GenericUnset = instance.__dict__.get(
-            f"_{self._col_name}", default_value
-        )
+        value: T | GenericUnset = instance.__dict__.get(f"_{self._col_name}", UNSET)
 
-        if value is default_value:
-            if self.nullable and value is UNSET:
+        if value is UNSET:
+            if self.nullable:
                 return None
-            elif self.primary_key and self.auto_increment:
+            if self.primary_key and self.auto_increment:
                 return PK_AUTO_INCREMENT
+            raise ColumnNotSetException(instance, f"Column {self._col_name} is not set")
 
         return value
 
@@ -161,7 +172,8 @@ class GenericColumn(typing.Generic[T], LoggerMixin):
         if self.nullable:
             validation_type = validation_type | None
         if self.default is not UNSET:
-            validation_type = validation_type | type(self.default)
+            if not callable(self.default):
+                validation_type = validation_type | type(self.default)
             validation_field = pydantic.Field(default=self.default)
         else:
             validation_field = pydantic.Field
@@ -194,3 +206,60 @@ class GenericColumn(typing.Generic[T], LoggerMixin):
             f"_{self._col_name}" in instance.__dict__
             and getattr(instance, f"_{self._col_name}") is not UNSET
         )
+
+    def apply_default(self, instance: "GenericModel") -> None:
+        """
+        Write the column default into the instance, leaving an already set column untouched.
+
+        A default resolving to a sentinel is skipped, so a default reading a not yet assigned primary key leaves the column unset.
+
+        Args:
+            instance (GenericModel): The instance to write the default into.
+        """
+        if self.default is UNSET or self.is_column_set(instance):
+            return
+
+        value = self.default(instance) if callable(self.default) else self.default
+        if isinstance(value, (GenericUnset, GenericPKAutoIncrement)):
+            return
+
+        instance.__dict__[f"_{self._col_name}"] = value
+
+    def _normalize_default(
+        self,
+        default: T | collections.abc.Callable[..., T],
+    ) -> T | collections.abc.Callable[["GenericModel"], T]:
+        """
+        Normalize a column default into either a plain value or a callable taking the model instance.
+
+        A mutable value becomes a copying callable, so one instance cannot mutate the default of every other instance.
+
+        Args:
+            default (T | collections.abc.Callable[..., T]): The default given to the column.
+
+        Returns:
+            T | collections.abc.Callable[[GenericModel], T]: The value itself, or a callable taking the instance.
+        """
+        if not callable(default):
+            if isinstance(default, collections.abc.Hashable):
+                return default
+            return lambda instance, value=default: copy.deepcopy(value)
+
+        try:
+            parameters = inspect.signature(default).parameters.values()
+        except (TypeError, ValueError):
+            # A builtin without an introspectable signature (dict, str, ...) can only be a zero argument factory.
+            return lambda instance, func=default: func()
+
+        if any(
+            parameter.default is inspect.Parameter.empty
+            and parameter.kind
+            in (
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            )
+            for parameter in parameters
+        ):
+            return default
+
+        return lambda instance, func=default: func()

{fastapi_rtk-2.12.3 → fastapi_rtk-2.13.0}/fastapi_rtk/backends/generic/model.py

@@ -117,15 +117,20 @@ class GenericModel(BasicModel):
         """
         Initialize the model with the given keyword arguments.
 
+        A column without a given value takes its default, like a dataclass mapped SQLAlchemy model does.
+
         Args:
             __check_on_init__ (bool, optional): Whether to check the model's validity on initialization. Defaults to True.
         """
-        if not kwargs:
-            return
         for key, value in kwargs.items():
             if key not in self.__mapper__.properties.keys():
                 continue
             setattr(self, key, value)
+
+        # After the given values, so a default reading another column sees it.
+        for column in self.__mapper__.properties.values():
+            column.apply_default(self)
+
         if __check_on_init__:
             self.is_model_valid()
 
@@ -166,8 +171,10 @@ class GenericModel(BasicModel):
         """
         errors: list[Exception] = []
         for key in self.__mapper__.properties.keys():
-            if getattr(self, key) is UNSET:
-                errors.append(ColumnNotSetException(self, f"Column {key} is not set"))
+            try:
+                getattr(self, key)
+            except ColumnNotSetException as e:
+                errors.append(e)
 
         if errors:
             # Rollback to last valid state
@@ -186,4 +193,10 @@ class GenericModel(BasicModel):
         return [cls.__mapper__.pk]
 
     def __repr__(self):
-        return f"{self.__class__.__name__}({';'.join([f'{col}={getattr(self, col)}' for col in self.__mapper__.properties.keys()])})"
+        values = []
+        for col in self.__mapper__.properties.keys():
+            try:
+                values.append(f"{col}={getattr(self, col)}")
+            except ColumnNotSetException:
+                values.append(f"{col}={UNSET}")
+        return f"{self.__class__.__name__}({';'.join(values)})"

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

@@ -23,7 +23,6 @@ __all__ = [
     "PydanticGenerationSchema",
     "AbstractInterface",
     "AbstractLoopManager",
-    "MissingGreenletError",
     "BasicModel",
     "AbstractSession",
     "AbstractUserSerializer",

{fastapi_rtk-2.12.3 → fastapi_rtk-2.13.0}/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.13.0/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.3 → fastapi_rtk-2.13.0}/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,6 +52,7 @@ from .const import (
     COOKIE_CONFIG,
     COOKIE_STRATEGY_CONFIG,
 )
+from .exceptions import MissingGreenletError
 from .utils import lazy, lazy_import
 
 if typing.TYPE_CHECKING:
@@ -240,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