dynamicforms-fastapi-viewsets 0.11.3__tar.gz → 0.12.0__tar.gz

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dynamicforms-fastapi-viewsets
-Version: 0.11.3
+Version: 0.12.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
@@ -72,8 +72,7 @@ Celery-backed async execution and a matching Vue/TypeScript client counterpart.
 - **Bulk operations** — first-class support for bulk create, update, partial update and destroy.
 - **muxws transport** — reach the same viewsets over a single WebSocket instead of one HTTP request
   per call. A command goes through your application as an HTTP request does - its middleware,
-  exception handlers, router dependencies and state - so both transports behave identically. In the
-  demo, a burst of 100 requests takes 156 ms over REST and 37 ms over muxws.
+  exception handlers, router dependencies and state - so both transports behave identically.
 - **Events** — publish an event to a topic and every frontend following it learns of it, as a muxws
   push or on its next poll. `ChangeEvents` publishes every create, update and destroy of a viewset to
   its routed base path; custom events are declared with `source()`. Every event is recorded before it
@@ -139,7 +138,7 @@ app.include_router(router)
 
 See the [full documentation](https://docs.velis.si/dynamicforms/fastapi-viewsets/) for guides on
 the mixin system, `route_viewset`, `CollectionViewSet`, `DjangoORMViewSet`, `celery_viewset`, the
-list pipeline and pagination, the muxws transport, and the Vue client.
+list pipeline and pagination, the muxws transport, events, and the Vue client.
 
 ## Demo
 

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/README.md

@@ -18,8 +18,7 @@ Celery-backed async execution and a matching Vue/TypeScript client counterpart.
 - **Bulk operations** — first-class support for bulk create, update, partial update and destroy.
 - **muxws transport** — reach the same viewsets over a single WebSocket instead of one HTTP request
   per call. A command goes through your application as an HTTP request does - its middleware,
-  exception handlers, router dependencies and state - so both transports behave identically. In the
-  demo, a burst of 100 requests takes 156 ms over REST and 37 ms over muxws.
+  exception handlers, router dependencies and state - so both transports behave identically.
 - **Events** — publish an event to a topic and every frontend following it learns of it, as a muxws
   push or on its next poll. `ChangeEvents` publishes every create, update and destroy of a viewset to
   its routed base path; custom events are declared with `source()`. Every event is recorded before it
@@ -85,7 +84,7 @@ app.include_router(router)
 
 See the [full documentation](https://docs.velis.si/dynamicforms/fastapi-viewsets/) for guides on
 the mixin system, `route_viewset`, `CollectionViewSet`, `DjangoORMViewSet`, `celery_viewset`, the
-list pipeline and pagination, the muxws transport, and the Vue client.
+list pipeline and pagination, the muxws transport, events, and the Vue client.
 
 ## Demo
 

dynamicforms_fastapi_viewsets-0.12.0/fastapi_viewsets/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.12.0"
+
+from .error_namespace import ERROR_NAMESPACE, ERROR_NAMESPACE_PYDANTIC
+
+__all__ = ["ERROR_NAMESPACE", "ERROR_NAMESPACE_PYDANTIC", "__version__"]

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/collection_viewset.py

@@ -211,8 +211,7 @@ class CollectionViewSet(AsyncCollectionViewSet[K, T]):
 
         for field_name, field_info in data.__class__.model_fields.items():
             if field_info.json_schema_extra and field_info.json_schema_extra.get("autoinc_int"):
-                # If the field is already set and is not 0 or None, we leave it (unless this is the desired behavior)
-                # However, we usually want autoinc only if the value is not yet set
+                # a truthy value is kept; 0 or None gets the next value after the container's maximum
                 current_val = getattr(data, field_name, None)
                 if current_val:
                     continue

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/conf.py

@@ -9,7 +9,7 @@ if TYPE_CHECKING:
 
     from .context.auth import AuthBackend
     from .events.authorizers import EventAuthorizer
-    from .events.delivery import DeliveryFilter
+    from .events.delivery import DeliveryFilter, EventListener
     from .events.store import EventStore
     from .middleware import CommandMiddleware
 
@@ -40,8 +40,9 @@ class Settings:
         """
         self.viewsets_idempotency_lock_ttl: float = 600
         """
-        Seconds a running record of `Idempotency` is kept after it was written, unless the action
-        finishes first. Once it expires, a repeat runs the action again.
+        Seconds a running record of `Idempotency` is kept after it was last extended; the process
+        running the call extends it every third of this time. Once it expires, a repeat runs the
+        action again.
         """
         self.viewsets_auth_processors: list[AuthBackend] = []
         self.default_action_configuration: dict[Any, Any] = {}
@@ -82,8 +83,15 @@ class Settings:
         """
         self.viewsets_event_delivery_filters: list[DeliveryFilter] = []
         """
-        The functions that decide, per subscription and per event, whether a push is sent. A filter
-        that answers False skips that socket; a filter that raises counts as True.
+        The functions that decide, per subscription and per event, whether a push is sent, and per
+        poll and per event whether the poll answers the event. A filter that answers False skips that
+        socket or leaves the event out of the poll answer; a filter that raises counts as True.
+        """
+        self.viewsets_event_listeners: list[EventListener] = []
+        """
+        The functions called with every event in every process whose store is started, before its
+        pushes, whether or not the process holds a subscription of its topic. A listener that raises is
+        logged and the next one runs.
         """
         self.viewsets_event_log_size: int = 32
         """

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/cursor.py

@@ -34,6 +34,7 @@ from typing import Any, ClassVar, Generic, TYPE_CHECKING
 from pydantic import BaseModel, TypeAdapter
 from typing_extensions import TypeVar
 
+from .error_namespace import _namespaced
 from .filters import Filter
 
 if TYPE_CHECKING:
@@ -43,7 +44,10 @@ TItem = TypeVar("TItem")
 
 
 class CursorError(ValueError):
-    """The cursor is unreadable, or does not belong to the query it was sent with."""
+    """
+    The cursor is unreadable, or does not belong to the query it was sent with. `code` is one of the
+    cursor codes, `fastapi-viewsets.cursor_<reason>`.
+    """
 
     def __init__(self, message: str, code: str, params: dict[str, Any] | None = None):
         super().__init__(message)
@@ -135,16 +139,16 @@ def decode_cursor(raw: str, keys: CursorKeys, expected_query: str, annotations:
         payload = json.loads(base64.urlsafe_b64decode(padded))
     except (ValueError, binascii.Error) as error:
         raise CursorError(
-            f"cursor is not readable: {error}", code="cursor_unreadable", params={"error": str(error)}
+            f"cursor is not readable: {error}", code=_namespaced("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", code="cursor_missing_position")
+        raise CursorError("cursor is not readable: no position in it", code=_namespaced("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",
-            code="cursor_stale",
+            code=_namespaced("cursor_stale"),
         )
 
     position = payload["p"]
@@ -152,7 +156,7 @@ def decode_cursor(raw: str, keys: CursorKeys, expected_query: str, annotations:
     if missing:
         raise CursorError(
             f"cursor has no value for ordering key(s): {', '.join(missing)}",
-            code="cursor_missing_keys",
+            code=_namespaced("cursor_missing_keys"),
             params={"missing": missing},
         )
 
@@ -168,7 +172,7 @@ def decode_cursor(raw: str, keys: CursorKeys, expected_query: str, annotations:
         except Exception as error:
             raise CursorError(
                 f"cursor value for {name!r} does not fit the field: {error}",
-                code="cursor_value_mismatch",
+                code=_namespaced("cursor_value_mismatch"),
                 params={"name": name, "error": str(error)},
             ) from None
 

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/decorators/celery_viewset/client.py

@@ -27,6 +27,7 @@ if TYPE_CHECKING:
 T = TypeVar("T")
 logger = logging.getLogger(__name__)
 
+# Seconds a `celery_viewset_client` call waits for its result when `result_timeout` is not given.
 DEFAULT_RESULT_TIMEOUT = 3600.0
 
 # queue_keys registered by celery_viewset_client so far - populated at decoration (import) time,

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/decorators/celery_viewset/result_reader.py

@@ -136,8 +136,9 @@ def _payload_error(data: dict) -> Exception:
 def error_payload(correlation_id: str, task: str | None, error: BaseException) -> dict:
     """
     The payload that fails one call with `error`: an `HTTPException` (a `DfViewSetError` with its
-    class), any other error as `ActionFailedError`. `http_status_code` and `http_detail` repeat the
-    status and detail for a reader that does not decode `error`.
+    class), a `RequestValidationError` as a 422 with its errors as `detail` and `class`
+    `"RequestValidationError"`, any other error as `ActionFailedError`. `http_status_code` and
+    `http_detail` repeat the status and detail for a reader that does not decode `error`.
     """
     if not isinstance(error, (HTTPException, RequestValidationError)):
         error = ActionFailedError(task)
@@ -168,8 +169,10 @@ def push_result(
     """
     Push a result or an error for one call. queue_key is the `_result_queue_key` the client sent with
     the task. An `error` that is an `HTTPException` reaches the caller as it is (a `DfViewSetError`
-    of a class `fastapi_viewsets.exceptions` defines keeps its class); any other error reaches it
-    as `ActionFailedError`. `task` names the call's task in that error.
+    of a class `fastapi_viewsets.exceptions` defines keeps its class), and so does a
+    `RequestValidationError`; any other error reaches it as `ActionFailedError`. `task` names the
+    call's task in that error. The FastAPI process answers each as `fastapi_viewsets.error_responses`
+    answers it.
     """
     if error is not None:
         data = error_payload(correlation_id, task, error)

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/decorators/celery_viewset/server.py

@@ -20,7 +20,6 @@ from functools import wraps
 from typing import Any, get_args, get_origin, get_type_hints, TYPE_CHECKING, TypeVar, Union
 
 from fastapi import HTTPException
-from fastapi.encoders import jsonable_encoder
 from fastapi.exceptions import RequestValidationError
 from pydantic import BaseModel, TypeAdapter, ValidationError
 
@@ -63,11 +62,9 @@ def _unwrap_optional(hint):
     return hint
 
 
-# Alias, not a re-implementation: the actual conversion (Pydantic models, dicts, lists/tuples,
-# SerializableObject values - e.g. a ViewSetResult a worker-side action returned directly, see
-# fastapi_viewsets.middleware) lives in fastapi_viewsets.context.to_jsonable, shared with
-# ViewSetResult's own (de)serialization. Kept under this name since call sites/tests here already
-# import it as `_to_jsonable`.
+# `fastapi_viewsets.context.to_jsonable`: converts Pydantic models, dicts, lists/tuples and
+# SerializableObject values (e.g. a ViewSetResult a worker-side action returned directly); also used
+# by ViewSetResult's own (de)serialization.
 _to_jsonable = to_jsonable
 
 
@@ -668,14 +665,13 @@ def celery_viewset_server(
                 _report("interrupted", task_name, call, lambda t: ActionInterruptedError(t, "time_limit"))
                 raise pool_timeout
             error = run.translate(caught)
-            if isinstance(error, RequestValidationError):
-                # a request the worker found invalid (a filter value that will not convert) answers as
-                # FastAPI answers one: 422 with the errors as `detail`
-                error = HTTPException(status_code=422, detail=jsonable_encoder(error.errors()))
             process_exit = isinstance(error, (KeyboardInterrupt, SystemExit))
             if process_exit:
                 pushed = ActionInterruptedError(task_name, "terminated")
-            elif isinstance(error, HTTPException):
+            elif isinstance(error, (HTTPException, RequestValidationError)):
+                # a request the worker found invalid (a filter value that will not convert) is pushed as
+                # the `RequestValidationError` it is, and answered as a request the FastAPI process found
+                # invalid
                 pushed = error
             else:
                 pushed = ActionFailedError(task_name)
@@ -688,12 +684,15 @@ def celery_viewset_server(
                     exc_info=caught,
                 )
             else:
+                status, detail = (
+                    (pushed.status_code, pushed.detail) if isinstance(pushed, HTTPException) else (422, pushed.errors())
+                )
                 logger.info(
                     "Celery task returned standard error: %s (correlation_id=%s): %d: %s",
                     task_name,
                     correlation_id,
-                    pushed.status_code,
-                    pushed.detail,
+                    status,
+                    detail,
                 )
             if process_exit and not _supervised():
                 _report("interrupted", task_name, call, lambda _t: pushed)

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/decorators/route_viewset.py

@@ -24,6 +24,7 @@ from fastapi_viewsets.endpoint_docs import (
 from fastapi_viewsets.middleware import any_modifies_response_shape, Middleware, unwrap_viewset_result_type
 from fastapi_viewsets.mixins import FilterParam
 from fastapi_viewsets.mux_ws import register_viewset, resolve_register_muxws, resolve_register_rest
+from fastapi_viewsets.response_classes import with_error_responses
 from fastapi_viewsets.routing import MUXWS, openapi_endpoint, REST, transport_route_class
 
 from .build_schema import _pydantic_generic_args, build_schema, route_to_add_api_route_kwargs
@@ -418,7 +419,9 @@ def route_viewset(
             documented.add(action_name)
             paths.setdefault(action_name, route.path[len(base) :] if route.path.startswith(base) else route.path)
             dependencies = list(route.dependencies or []) + [Depends(_make_middleware_depends(cls, action_name))]
-            route_kwargs = route_to_add_api_route_kwargs(route, dependencies=dependencies)
+            route_kwargs = route_to_add_api_route_kwargs(
+                route, dependencies=dependencies, responses=with_error_responses(route.responses)
+            )
             # Per-viewset wording for an endpoint the mixin provided - the mixin's own docstring is
             # the same sentence on every viewset in the application. See endpoint_docs.py.
             route_kwargs.update(docs_for(cls, action_name))

dynamicforms_fastapi_viewsets-0.12.0/fastapi_viewsets/error_namespace.py

@@ -0,0 +1,57 @@
+"""
+The namespaces of the error codes this package's errors carry.
+
+An error code is `<namespace>.<code>`: `code` is snake_case without `.`, `namespace` one or more
+segments of `[a-z0-9]+(-[a-z0-9]+)*` joined by `.`, and a full code splits at its last `.`. The
+codes this package declares are in `ERROR_NAMESPACE`. `ERROR_NAMESPACE_PYDANTIC` is the namespace
+of pydantic's error types, which the field errors of a `fastapi-viewsets.validation_failed` body carry
+as `pydantic.<type>`, and of `pydantic.custom_error`, the field error of a type pydantic does not
+declare. A code the application gives an error is used as given.
+"""
+
+ERROR_NAMESPACE = "fastapi-viewsets"
+"""The namespace of every error code this package declares, e.g. `fastapi-viewsets.not_found`."""
+
+ERROR_NAMESPACE_PYDANTIC = "pydantic"
+"""The namespace of pydantic's error types, e.g. `pydantic.string_too_short`."""
+
+_PREFIX = f"{ERROR_NAMESPACE}."
+
+_DECLARED_CODES = frozenset(
+    {
+        "not_found",
+        "read_only",
+        "session_expired",
+        "not_authorized",
+        "rate_limited",
+        "result_timeout",
+        "result_reader_stopped",
+        "action_dispatch_failed",
+        "action_interrupted",
+        "action_failed",
+        "idempotency_key_invalid",
+        "idempotency_key_reused",
+        "unsupported_list_shape",
+        "event_topic_invalid",
+        "event_topic_refused",
+        "event_scope_missing",
+        "event_subscriptions_exceeded",
+        "event_cursors_exceeded",
+        "cursor_unreadable",
+        "cursor_missing_position",
+        "cursor_stale",
+        "cursor_missing_keys",
+        "cursor_value_mismatch",
+        "validation_failed",
+        "http_error",
+        "unhandled_error",
+        "command_invalid",
+        "pk_assigned_by_server",
+    }
+)
+"""Every code this package declares, without the namespace; each is built with `_namespaced()`."""
+
+
+def _namespaced(code: str) -> str:
+    """The full code of `code`, an error code this package declares."""
+    return f"{_PREFIX}{code}"

dynamicforms_fastapi_viewsets-0.12.0/fastapi_viewsets/error_responses.py

@@ -0,0 +1,261 @@
+"""
+The body of every error response: `ApiErrorBody`.
+
+    {
+        "detail": "Item with pk 42 not found",
+        "detail_code": "fastapi-viewsets.not_found",
+        "detail_params": {"pk": 42},
+        "field_errors": {}
+    }
+
+`error_body()` builds it from an exception:
+
+- a `DfViewSetError`: its `detail`, `code` and `params`;
+- a `RequestValidationError`: `fastapi-viewsets.validation_failed`, with its errors in
+  `field_errors`;
+- any other `HTTPException` (FastAPI's, Starlette's, one an application raises, Starlette's own
+  404 and 405 of the router): `fastapi-viewsets.http_error` with `params.status`;
+- any other exception: `fastapi-viewsets.unhandled_error` (`UnhandledError`), status 500, with no
+  part of the exception in the body.
+
+The routes of a viewset answer every error with this body without any registration (see
+`routing.TransportRoute`). `install_error_handlers(app)` answers the errors of the application's
+other routes, and of a request no route matches, with it too.
+"""
+
+from http import HTTPStatus
+from typing import Any, get_args
+
+from fastapi import FastAPI
+from fastapi.encoders import jsonable_encoder
+from fastapi.exception_handlers import http_exception_handler, request_validation_exception_handler
+from fastapi.exceptions import RequestValidationError
+from fastapi.utils import is_body_allowed_for_status_code
+from pydantic import BaseModel, Field
+from pydantic_core.core_schema import ErrorType
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from .error_namespace import _namespaced, ERROR_NAMESPACE_PYDANTIC
+from .exceptions import DfViewSetError, UnhandledError
+
+
+class ApiFieldError(BaseModel):
+    """One failure of one value of a request that failed validation."""
+
+    code: str = Field(
+        description=(
+            "pydantic's error type in the namespace `pydantic`, e.g. `pydantic.string_too_short`; "
+            "`pydantic.custom_error` for a type pydantic does not declare (a `PydanticCustomError` of the "
+            "application); `fastapi-viewsets.pk_assigned_by_server` for a primary key in a create's body."
+        ),
+        examples=["pydantic.string_too_short"],
+    )
+    params: dict[str, Any] = Field(
+        description=(
+            "The values pydantic built `detail` from (pydantic's `ctx`); `{}` without any. For "
+            "`pydantic.custom_error`: `{type, ctx}`, the custom error's type and its `ctx`."
+        ),
+        examples=[{"min_length": 3}, {"type": "app.slug_taken", "ctx": {"slug": "blue"}}],
+    )
+    detail: str = Field(
+        description="pydantic's English message (`msg`).",
+        examples=["String should have at least 3 characters"],
+    )
+
+
+class ApiErrorBody(BaseModel):
+    """The body of every error response."""
+
+    detail: str = Field(
+        description="English text of the error, interpolated from `detail_params`. Not translated.",
+        examples=["Item with pk 42 not found"],
+    )
+    detail_code: str = Field(
+        description=(
+            "The error's full code, `<namespace>.<code>`: `fastapi-viewsets.<code>` for the errors the "
+            "package raises, the application's own code as given for its own `DfViewSetError`."
+        ),
+        examples=["fastapi-viewsets.not_found"],
+    )
+    detail_params: dict[str, Any] = Field(
+        description="The values `detail` was interpolated with, by name; `{}` without any.",
+        examples=[{"pk": 42}],
+    )
+    field_errors: dict[str, list[ApiFieldError]] = Field(
+        description=(
+            "The failures of a request that failed validation (`fastapi-viewsets.validation_failed`), keyed "
+            "by field name: pydantic's `loc` without its first element (`body`, `query`, `path`, `header`, "
+            "`cookie`), joined with `.`; a failure of the body as a whole is keyed `''`. `{}` for every "
+            "other error."
+        ),
+        examples=[{}],
+    )
+
+
+VALIDATION_FAILED_DETAIL = "The request failed validation"
+"""The `detail` of `fastapi-viewsets.validation_failed`."""
+
+
+def _jsonable_ctx(ctx: dict[str, Any] | None) -> dict[str, Any]:
+    """pydantic's `ctx` as JSON values: an exception (the `error` of `value_error`) as its message."""
+    return jsonable_encoder(
+        {name: str(value) if isinstance(value, BaseException) else value for name, value in (ctx or {}).items()}
+    )
+
+
+PYDANTIC_ERROR_TYPES = frozenset(get_args(ErrorType))
+"""The error types pydantic declares: the values of `pydantic_core.core_schema.ErrorType`."""
+
+CUSTOM_ERROR_CODE = f"{ERROR_NAMESPACE_PYDANTIC}.custom_error"
+"""The code of a field error whose type pydantic does not declare."""
+
+_PACKAGE_FIELD_ERROR_CODES = {"pk_assigned_by_server": _namespaced("pk_assigned_by_server")}
+"""The codes of the `PydanticCustomError` types this package raises, by type."""
+
+
+def _field_error(error: Any) -> dict[str, Any]:
+    error_type = error.get("type")
+    ctx = _jsonable_ctx(error.get("ctx"))
+    if error_type in PYDANTIC_ERROR_TYPES:
+        code, params = f"{ERROR_NAMESPACE_PYDANTIC}.{error_type}", ctx
+    elif error_type in _PACKAGE_FIELD_ERROR_CODES:
+        code, params = _PACKAGE_FIELD_ERROR_CODES[error_type], ctx
+    else:
+        code, params = CUSTOM_ERROR_CODE, {"type": error_type, "ctx": ctx}
+    return {"code": code, "params": params, "detail": str(error.get("msg", ""))}
+
+
+def field_errors(errors: Any) -> dict[str, list[dict[str, Any]]]:
+    """
+    pydantic's errors (`RequestValidationError.errors()`) as `ApiErrorBody.field_errors`: keyed by
+    `loc` without its first element, joined with `.` (`("body", "address", "city")` is
+    `address.city`, `("body",)` is `''`), each `{code, params, detail}` with `msg` as `detail`.
+    `input` is left out.
+
+    - A `type` pydantic declares (`PYDANTIC_ERROR_TYPES`) is `code` in the namespace
+      `ERROR_NAMESPACE_PYDANTIC` (`pydantic.string_too_short`), with `ctx` as `params`.
+    - `pk_assigned_by_server`, the type this package raises, is `fastapi-viewsets.pk_assigned_by_server`,
+      with `ctx` as `params`.
+    - Any other `type` (a `PydanticCustomError` of the application) is `pydantic.custom_error`, with
+      `params` `{"type": <type>, "ctx": <ctx>}`: `ctx` is nested, so none of its keys collides with
+      `type`.
+    """
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for error in errors or ():
+        loc = error.get("loc") or ()
+        name = ".".join(str(part) for part in list(loc)[1:])
+        grouped.setdefault(name, []).append(_field_error(error))
+    return grouped
+
+
+def _body(detail: str, code: str, params: dict[str, Any], fields: dict | None = None) -> dict[str, Any]:
+    return {"detail": detail, "detail_code": code, "detail_params": params, "field_errors": fields or {}}
+
+
+def error_status(error: BaseException) -> int:
+    """The status `error` is answered with: an `HTTPException`'s own, 422 for a
+    `RequestValidationError`, 500 for any other exception."""
+    if isinstance(error, HTTPException):
+        return error.status_code
+    if isinstance(error, RequestValidationError):
+        return 422
+    return 500
+
+
+def error_body(error: BaseException) -> dict[str, Any]:
+    """
+    `error` as an `ApiErrorBody`, in JSON form.
+
+    - `DfViewSetError`: `detail`, `code` as `detail_code`, `params` as `detail_params`.
+    - `RequestValidationError`: `fastapi-viewsets.validation_failed`, `detail_params` `{}`, its errors
+      in `field_errors` (see `field_errors()`).
+    - another `HTTPException`: `fastapi-viewsets.http_error`, `detail_params` `{"status": <status>}`.
+      A string `detail` is the body's `detail`; any other `detail` is `detail_params.detail` and the
+      body's `detail` is the status phrase (`Bad Request`).
+    - any other exception: the body of `UnhandledError`.
+    """
+    if isinstance(error, RequestValidationError):
+        return _body(VALIDATION_FAILED_DETAIL, _namespaced("validation_failed"), {}, field_errors(error.errors()))
+    if not isinstance(error, HTTPException):
+        error = UnhandledError()
+    if isinstance(error, DfViewSetError):
+        return _body(jsonable_encoder(error.detail), error.code, jsonable_encoder(error.params))
+    params: dict[str, Any] = {"status": error.status_code}
+    detail = error.detail
+    if not isinstance(detail, str):
+        params["detail"] = jsonable_encoder(detail)
+        try:
+            detail = HTTPStatus(error.status_code).phrase
+        except ValueError:
+            detail = f"HTTP {error.status_code}"
+    return _body(detail, _namespaced("http_error"), params)
+
+
+def error_response(error: BaseException) -> Response:
+    """
+    The response that answers `error`: `error_status(error)`, `error_body(error)` as JSON, and an
+    `HTTPException`'s `headers`. A status that allows no body (204, 304) is answered without one.
+    """
+    status = error_status(error)
+    headers = getattr(error, "headers", None) if isinstance(error, HTTPException) else None
+    if not is_body_allowed_for_status_code(status):
+        return Response(status_code=status, headers=headers)
+    return JSONResponse(error_body(error), status_code=status, headers=headers)
+
+
+async def _handle_error(_request: Request, error: Exception) -> Response:
+    """The handler `install_error_handlers` registers, and the one a viewset route answers
+    `HTTPException` and `RequestValidationError` with. For `Exception` Starlette's
+    `ServerErrorMiddleware` re-raises the exception after the response, and the server logs it."""
+    return error_response(error)
+
+
+def install_error_handlers(app: FastAPI) -> None:
+    """
+    Registers the handlers that answer the errors of every route of `app` with an `ApiErrorBody`
+    (see `error_body()`), for `DfViewSetError`, `HTTPException` (Starlette's, which FastAPI's
+    subclasses), `RequestValidationError` and `Exception`. Starlette's own 404 of a path no route
+    matches and 405 of a method a route does not serve are `fastapi-viewsets.http_error` with
+    `params.status` 404 and 405. An exception without a handler of its own is answered with 500
+    `fastapi-viewsets.unhandled_error` and re-raised by Starlette, so the server logs it.
+
+    A handler the application registers for one of these classes afterwards replaces this one; a
+    handler for a more specific class, or for a status, takes precedence as Starlette's lookup
+    gives it.
+
+    The routes of a viewset answer with an `ApiErrorBody` whether or not this is called.
+    """
+    app.add_exception_handler(DfViewSetError, _handle_error)
+    app.add_exception_handler(HTTPException, _handle_error)
+    app.add_exception_handler(RequestValidationError, _handle_error)
+    app.add_exception_handler(Exception, _handle_error)
+
+
+_FASTAPI_HANDLERS = (http_exception_handler, request_validation_exception_handler)
+"""The handlers a FastAPI application registers by default."""
+
+
+EXCEPTION_HANDLERS_SCOPE_KEY = "starlette.exception_handlers"
+
+
+def uniform_exception_handlers(scope: dict[str, Any]) -> None:
+    """
+    Replaces, for the request of `scope`, FastAPI's default handlers of `HTTPException` and
+    `RequestValidationError` with one that answers an `ApiErrorBody`. Handlers the application
+    registered for a class or a status are kept.
+    """
+    exception_handlers, status_handlers = scope.get(EXCEPTION_HANDLERS_SCOPE_KEY) or ({}, {})
+    handlers = {
+        key: (_handle_error if handler in _FASTAPI_HANDLERS else handler) for key, handler in exception_handlers.items()
+    }
+    handlers.setdefault(HTTPException, _handle_error)
+    handlers.setdefault(RequestValidationError, _handle_error)
+    scope[EXCEPTION_HANDLERS_SCOPE_KEY] = (handlers, status_handlers)
+
+
+def answers_unhandled_itself(app: Any) -> bool:
+    """Whether `app` has a handler of its own, not `install_error_handlers`', for `Exception` or 500."""
+    handlers = getattr(app, "exception_handlers", None) or {}
+    return any(key in handlers and handlers[key] is not _handle_error for key in (Exception, 500))

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/events/__init__.py

@@ -32,6 +32,7 @@ from .delivery import (
     DeliveryFilter,
     drop_peer,
     drop_subscriptions,
+    EventListener,
     passes_filters,
     reset_subscriptions,
     subscribe,
@@ -80,6 +81,7 @@ __all__ = [
     "ChangeEvents",
     "DeclaredSources",
     "DeliveryFilter",
+    "EventListener",
     "Event",
     "EventAuthorizer",
     "EventScope",

{dynamicforms_fastapi_viewsets-0.11.3 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/events/conftest.py

@@ -9,6 +9,7 @@ from typing import Any
 import pytest
 
 from ..conf import settings
+from ..error_namespace import ERROR_NAMESPACE
 from . import store as store_module
 from .delivery import reset_subscriptions
 from .redis import _APPEND_SCRIPT
@@ -19,6 +20,7 @@ EVENT_SETTINGS = (
     "viewsets_event_store",
     "viewsets_event_authorizers",
     "viewsets_event_delivery_filters",
+    "viewsets_event_listeners",
     "viewsets_event_log_size",
     "viewsets_event_log_ttl",
     "viewsets_event_push_timeout",
@@ -33,6 +35,7 @@ def _reset_events():
     saved = {name: getattr(settings, name) for name in EVENT_SETTINGS}
     settings.viewsets_event_authorizers = []
     settings.viewsets_event_delivery_filters = []
+    settings.viewsets_event_listeners = []
     reset_subscriptions()
     reset_sources()
     reset_event_scopes()
@@ -255,3 +258,8 @@ class FakePubSub:
     async def aclose(self) -> None:
         await self.unsubscribe(*list(self.subscribed))
         self.closed = True
+
+
+def envelope(detail: str, code: str, **params: Any) -> dict[str, Any]:
+    """The `ApiErrorBody` of the package's error `code` (without the namespace)."""
+    return {"detail": detail, "detail_code": f"{ERROR_NAMESPACE}.{code}", "detail_params": params, "field_errors": {}}