dynamicforms-fastapi-viewsets 0.5.6__tar.gz → 0.6.0__tar.gz

{dynamicforms_fastapi_viewsets-0.5.6 → dynamicforms_fastapi_viewsets-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dynamicforms-fastapi-viewsets
-Version: 0.5.6
+Version: 0.6.0
 Summary: Django REST Framework-style viewsets for FastAPI, with optional Celery-backed async execution and a Vue/TypeScript client counterpart.
 Project-URL: Homepage, https://github.com/dynamicforms/fastapi-viewsets
 Project-URL: Repository, https://github.com/dynamicforms/fastapi-viewsets

dynamicforms_fastapi_viewsets-0.6.0/fastapi_viewsets/__init__.py

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

{dynamicforms_fastapi_viewsets-0.5.6 → dynamicforms_fastapi_viewsets-0.6.0}/fastapi_viewsets/backends/django_orm.py

@@ -27,12 +27,12 @@ from typing import Any, ClassVar, Generic, TYPE_CHECKING
 
 from asgiref.sync import sync_to_async
 from django.db.models import BooleanField, F, Func, Q, Value
-from fastapi import HTTPException
 from pydantic import BaseModel
 from typing_extensions import TypeVar
 
 from ..context import Context
 from ..cursor import CursorPredicate, wants_greater
+from ..exceptions import NotFoundError
 from ..filters import (
     can_compile_all,
     compile_all,
@@ -299,7 +299,7 @@ class DjangoORMViewSet(ImplMixin[K, T], Generic[K, T]):
         try:
             return await self.get_queryset(context).aget(**{self.pk_field: pk})
         except ObjectDoesNotExist:
-            raise HTTPException(status_code=404, detail=f"Item with pk {pk} not found") from None
+            raise NotFoundError(pk) from None
 
     def _writable_fields(self, data: T, exclude_unset: bool = False) -> dict[str, Any]:
         """

{dynamicforms_fastapi_viewsets-0.5.6 → dynamicforms_fastapi_viewsets-0.6.0}/fastapi_viewsets/collection_viewset.py

@@ -5,8 +5,8 @@ from typing import Any, Generic, TypeVar
 from pydantic import BaseModel
 
 from .context import Context
+from .exceptions import NotFoundError
 from .mixins import ImplMixin
-from .response_classes import NotFoundError
 
 T = TypeVar("T")
 K = TypeVar("K")

{dynamicforms_fastapi_viewsets-0.5.6 → dynamicforms_fastapi_viewsets-0.6.0}/fastapi_viewsets/cursor.py

@@ -45,6 +45,11 @@ TItem = TypeVar("TItem")
 class CursorError(ValueError):
     """The cursor is unreadable, or does not belong to the query it was sent with."""
 
+    def __init__(self, message: str, code: str, params: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.code = code
+        self.params = params or {}
+
 
 CursorKeys = tuple[tuple[str, bool], ...]
 """Ordering keys as (field name, descending), primary key last. The shape a position is read against."""
@@ -129,18 +134,27 @@ def decode_cursor(raw: str, keys: CursorKeys, expected_query: str, annotations:
         padded = raw + "=" * (-len(raw) % 4)
         payload = json.loads(base64.urlsafe_b64decode(padded))
     except (ValueError, binascii.Error) as error:
-        raise CursorError(f"cursor is not readable: {error}") from None
+        raise CursorError(
+            f"cursor is not readable: {error}", code="cursor_unreadable", params={"error": str(error)}
+        ) from None
 
     if not isinstance(payload, dict) or not isinstance(payload.get("p"), dict):
-        raise CursorError("cursor is not readable: no position in it")
+        raise CursorError("cursor is not readable: no position in it", code="cursor_missing_position")
 
     if payload.get("q") != expected_query:
-        raise CursorError("this cursor was issued for a different ordering or filter - start from the first page")
+        raise CursorError(
+            "this cursor was issued for a different ordering or filter - start from the first page",
+            code="cursor_stale",
+        )
 
     position = payload["p"]
     missing = [name for name, _ in keys if name not in position]
     if missing:
-        raise CursorError(f"cursor has no value for ordering key(s): {', '.join(missing)}")
+        raise CursorError(
+            f"cursor has no value for ordering key(s): {', '.join(missing)}",
+            code="cursor_missing_keys",
+            params={"missing": missing},
+        )
 
     coerced: dict[str, Any] = {}
     for name, _ in keys:
@@ -152,7 +166,11 @@ def decode_cursor(raw: str, keys: CursorKeys, expected_query: str, annotations:
         try:
             coerced[name] = TypeAdapter(annotation).validate_python(value)
         except Exception as error:
-            raise CursorError(f"cursor value for {name!r} does not fit the field: {error}") from None
+            raise CursorError(
+                f"cursor value for {name!r} does not fit the field: {error}",
+                code="cursor_value_mismatch",
+                params={"name": name, "error": str(error)},
+            ) from None
 
     return CursorState(
         position=coerced,

dynamicforms_fastapi_viewsets-0.6.0/fastapi_viewsets/exceptions.py

@@ -0,0 +1,81 @@
+"""
+The HTTP exceptions this package raises on its own behalf.
+
+`detail` is the English default, fully interpolated - a plain string, exactly as it always was, so
+an application that does nothing further sees exactly what it always has. `code` names what went
+wrong independently of `detail`'s wording, and `params` are the raw values `detail` was
+interpolated with; both reach the response body only once the application registers
+`df_viewset_exception_handler` for `DfViewSetError` (see that function). A view's own
+`raise HTTPException(status_code, detail="...")` is unaffected either way.
+"""
+
+from typing import Any
+
+from fastapi import HTTPException, Request
+from fastapi.responses import JSONResponse
+
+from .cursor import CursorError
+
+
+class DfViewSetError(HTTPException):
+    """Base for every `HTTPException` this package raises on its own behalf."""
+
+    def __init__(self, status_code: int, message: str, code: str, params: dict[str, Any] | None = None):
+        super().__init__(status_code=status_code, detail=message)
+        self.code = code
+        self.params = params or {}
+
+
+class NotFoundError(DfViewSetError):
+    def __init__(self, pk: Any):
+        super().__init__(404, f"Item with pk {pk} not found", "not_found", {"pk": pk})
+
+
+class SessionExpiredError(DfViewSetError):
+    def __init__(self):
+        super().__init__(401, "Session expired or invalid", "session_expired")
+
+
+class NotAuthorizedError(DfViewSetError):
+    def __init__(self):
+        super().__init__(403, "Not authorized to perform this action", "not_authorized")
+
+
+class RateLimitedError(DfViewSetError):
+    def __init__(self):
+        super().__init__(429, "Rate limit exceeded", "rate_limited")
+
+
+class UnsupportedListShapeError(DfViewSetError):
+    def __init__(self, shape: str, allowed: list[str]):
+        message = f"unsupported list shape {shape!r}; this endpoint offers {', '.join(allowed)}"
+        super().__init__(422, message, "unsupported_list_shape", {"shape": shape, "allowed": allowed})
+
+
+class CursorRequestError(DfViewSetError):
+    """Raised in place of a caught `CursorError`, carrying the same `code`/`params` as a 400 response."""
+
+    def __init__(self, error: CursorError):
+        super().__init__(400, str(error), error.code, error.params)
+
+
+async def df_viewset_exception_handler(_request: Request, exc: DfViewSetError) -> JSONResponse:
+    """
+    Adds `detail_code` and `detail_params` alongside `detail` in the response body.
+
+    Opt in once, for `DfViewSetError` - every exception this package raises on its own descends
+    from it:
+
+        from fastapi_viewsets.exceptions import DfViewSetError, df_viewset_exception_handler
+
+        app.add_exception_handler(DfViewSetError, df_viewset_exception_handler)
+
+    An application that never registers this sees exactly what it always has -
+    `{"detail": "..."}`, from FastAPI's own default `HTTPException` handling; `code` and `params`
+    reach nothing without it.
+    """
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"detail": exc.detail, "detail_code": exc.code, "detail_params": exc.params},
+        headers=exc.headers,
+    )

{dynamicforms_fastapi_viewsets-0.5.6 → dynamicforms_fastapi_viewsets-0.6.0}/fastapi_viewsets/middleware/auth/__init__.py

@@ -1,8 +1,7 @@
 from collections.abc import Awaitable, Callable
 from typing import Any, TYPE_CHECKING
 
-from fastapi import HTTPException
-
+from ...exceptions import SessionExpiredError
 from .. import Middleware, ViewSetResult
 
 if TYPE_CHECKING:
@@ -41,7 +40,7 @@ class Session(Middleware):
             return
         user = await context.user
         if user is None:
-            raise HTTPException(status_code=401, detail="Session expired or invalid")
+            raise SessionExpiredError()
 
     async def __call__(
         self,

{dynamicforms_fastapi_viewsets-0.5.6 → dynamicforms_fastapi_viewsets-0.6.0}/fastapi_viewsets/middleware/auth/authorization.py

@@ -3,8 +3,7 @@ import inspect
 from collections.abc import Awaitable, Callable
 from typing import Any, TYPE_CHECKING
 
-from fastapi import HTTPException
-
+from ...exceptions import NotAuthorizedError
 from .. import Middleware, ViewSetResult
 
 if TYPE_CHECKING:
@@ -23,14 +22,18 @@ class Authorization(Middleware):
     - If it's callable, it's evaluated as `check(request, cls, context)` (sync or async) in
       `depends()` - bridged onto FastAPI's own `Depends()` by route_viewset - a falsy result
       rejects the request with 403 before `perform_*` (or even FastAPI's own body parsing) ever
-      runs. Use this for checks that don't need a specific record (e.g. a role check).
-    - Either way (callable or not, or even unconfigured), the resolved value is made available as
-      `context.authorization` (set in `__call__`, unconditionally, in the onion chain - there's no
-      reject decision here, so there's no benefit to doing this any earlier) - `perform_*` can
-      inspect it once it has whatever record-specific info a check needs (e.g. the object a `pk`
-      resolved to) and reject itself (`raise HTTPException(403, ...)`) if it decides to. This is
-      the "no hook in the middleware layer needed" case - just raise, same as anywhere else in the
-      pipeline (see docs/guide/action-configuration.md's "Rejecting a request: just raise").
+      runs. Use this for checks that don't need a specific record (e.g. a role check). A callable
+      config is consumed entirely by `depends()` and never reaches `context.authorization` - there
+      is nothing left for `perform_*` to do with the check function itself, and a bare function
+      isn't something a `celery_viewset` worker could receive anyway.
+    - Otherwise (non-callable, or unconfigured/`None`), nothing is enforced by the middleware
+      itself; the value is made available as `context.authorization` (set in `__call__`, in the
+      onion chain - there's no reject decision here, so there's no benefit to doing this any
+      earlier) - `perform_*` can inspect it once it has whatever record-specific info a check
+      needs (e.g. the object a `pk` resolved to) and reject itself (`raise HTTPException(403,
+      ...)`) if it decides to. This is the "no hook in the middleware layer needed" case - just
+      raise, same as anywhere else in the pipeline (see docs/guide/action-configuration.md's
+      "Rejecting a request: just raise").
 
     Unconfigured (no `@action_configuration` entry for `Authorization` at all): nothing is
     enforced, `context.authorization` resolves to `None`.
@@ -54,7 +57,7 @@ class Authorization(Middleware):
             if inspect.isawaitable(allowed):
                 allowed = await allowed
             if not allowed:
-                raise HTTPException(status_code=403, detail="Not authorized to perform this action")
+                raise NotAuthorizedError()
 
     async def __call__(
         self,
@@ -63,5 +66,7 @@ class Authorization(Middleware):
         context: "Context",
         call_next: Callable[[], Awaitable[ViewSetResult]],
     ) -> ViewSetResult:
-        context.set("authorization", self.config_from(context))
+        config = self.config_from(context)
+        if not callable(config):
+            context.set("authorization", config)
         return await call_next()

{dynamicforms_fastapi_viewsets-0.5.6 → dynamicforms_fastapi_viewsets-0.6.0}/fastapi_viewsets/middleware/rate_limiter.py

@@ -4,8 +4,7 @@ import time
 from collections.abc import Awaitable, Callable
 from typing import Any, TYPE_CHECKING
 
-from fastapi import HTTPException
-
+from ..exceptions import RateLimitedError
 from . import Middleware, ViewSetResult
 
 if TYPE_CHECKING:
@@ -72,7 +71,7 @@ class RateLimiter(Middleware):
             key = await key
         allowed = await self._increment(key, limit)
         if not allowed:
-            raise HTTPException(status_code=429, detail="Rate limit exceeded")
+            raise RateLimitedError()
 
     async def __call__(
         self,

{dynamicforms_fastapi_viewsets-0.5.6 → dynamicforms_fastapi_viewsets-0.6.0}/fastapi_viewsets/mixins.py

@@ -2,7 +2,7 @@ from abc import ABC, abstractmethod
 from enum import Enum
 from typing import Annotated, Any, final, Generic, get_args, get_origin, Union
 
-from fastapi import APIRouter, Header, HTTPException, Query
+from fastapi import APIRouter, Header, Query
 from pydantic import BaseModel, ConfigDict, create_model
 from pydantic.alias_generators import to_camel
 from typing_extensions import TypeVar
@@ -21,6 +21,7 @@ from fastapi_viewsets.cursor import (
     make_predicate,
     position_of,
 )
+from fastapi_viewsets.exceptions import CursorRequestError, UnsupportedListShapeError
 from fastapi_viewsets.filters import filters_from, FilterSet
 from fastapi_viewsets.list_query import (
     build_list_query,
@@ -315,10 +316,7 @@ class ListMixin(Generic[T, TFilter], ABC):
         default, allowed = self.resolve_shapes()
         shape = x_list_shape or default
         if shape not in allowed:
-            raise HTTPException(
-                status_code=422,
-                detail=f"unsupported list shape {shape!r}; this endpoint offers {', '.join(allowed)}",
-            )
+            raise UnsupportedListShapeError(shape, list(allowed))
 
         query = build_list_query(
             fltr,
@@ -446,7 +444,7 @@ class ListMixin(Generic[T, TFilter], ABC):
             except CursorError as error:
                 # The client sent something wrong, not the server - a stale cursor after a sort
                 # change is the ordinary case, and it deserves a message rather than a traceback.
-                raise HTTPException(status_code=400, detail=str(error)) from None
+                raise CursorRequestError(error) from None
             query.extra_filters.append(make_predicate(state, keys, self.nulls_first))
 
         backwards = bool(state and state.backwards)

{dynamicforms_fastapi_viewsets-0.5.6 → dynamicforms_fastapi_viewsets-0.6.0}/fastapi_viewsets/mux_ws/protocol.py

@@ -37,8 +37,6 @@ consume the whole body before learning whether it was an error at all.
 from typing import Any
 from urllib.parse import urlencode
 
-from muxws.frames import ABSENT
-
 METHOD_KEY = ":method"
 PATH_KEY = ":path"
 QUERY_KEY = ":query"
@@ -120,4 +118,6 @@ def build_response_meta(status: int, headers: dict[str, str]) -> dict[str, Any]:
 
 def body_to_payload(body: Any) -> Any:
     """`ABSENT` is muxws' "no payload at all", which is a different frame from a null payload."""
+    from muxws.frames import ABSENT
+
     return ABSENT if body is None else body

dynamicforms_fastapi_viewsets-0.6.0/fastapi_viewsets/response_classes.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+
+class NotFoundResponse(BaseModel):
+    detail: str = "Item with pk {pk} not found"
+
+
+NOT_FOUND_RESPONSE = {"404": {"model": NotFoundResponse}}

dynamicforms_fastapi_viewsets-0.5.6/fastapi_viewsets/__init__.py

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

dynamicforms_fastapi_viewsets-0.5.6/fastapi_viewsets/response_classes.py

@@ -1,17 +0,0 @@
-from typing import Any
-
-from fastapi import HTTPException
-from pydantic import BaseModel
-
-
-class NotFoundResponse(BaseModel):
-    detail: str = "Item with pk {pk} not found"
-
-
-NOT_FOUND_RESPONSE = {"404": {"model": NotFoundResponse, "message": NotFoundResponse().detail}}
-
-
-class NotFoundError(HTTPException):
-    def __init__(self, pk: Any):
-        # NotFoundResponse has only "detail", so it deconstructs into exactly the same parameter for HTTPException
-        super().__init__(status_code=404, **NotFoundResponse(detail=f"Item with pk {pk} not found").model_dump())