dynamicforms-fastapi-viewsets 0.10.0__tar.gz → 0.11.0__tar.gz

{dynamicforms_fastapi_viewsets-0.10.0 → dynamicforms_fastapi_viewsets-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dynamicforms-fastapi-viewsets
-Version: 0.10.0
+Version: 0.11.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
@@ -33,6 +33,7 @@ Requires-Dist: asgiref; extra == 'dev'
 Requires-Dist: celery; extra == 'dev'
 Requires-Dist: coverage; extra == 'dev'
 Requires-Dist: django; extra == 'dev'
+Requires-Dist: gevent; extra == 'dev'
 Requires-Dist: httpx2; extra == 'dev'
 Requires-Dist: muxws[starlette,websockets]>=0.4.1; extra == 'dev'
 Requires-Dist: pyjwt; extra == 'dev'

dynamicforms_fastapi_viewsets-0.11.0/fastapi_viewsets/__init__.py

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

{dynamicforms_fastapi_viewsets-0.10.0 → dynamicforms_fastapi_viewsets-0.11.0}/fastapi_viewsets/action_configuration.py

@@ -1,3 +1,4 @@
+from dataclasses import dataclass
 from typing import Any
 
 from .conf import settings
@@ -47,6 +48,31 @@ def action_configuration(config: dict[Any, Any]):
     return decorator
 
 
+@dataclass(frozen=True)
+class TimeLimits:
+    """
+    The time limits, in seconds, of an execution of a deferred action, configured under the
+    `TimeLimits` key:
+
+        @action_configuration({TimeLimits: TimeLimits(soft=30, hard=60)})
+        class ReportViewSet(...): ...
+
+    `soft` interrupts the execution from inside: `Middleware.execute()` sees `ActionInterruptedError`
+    from `call_next()`, `finally` blocks and `save_state()` run, and the caller receives the error.
+    `hard` ends the execution's process: the execution unwinds as `SystemExit` only as far as it
+    gets before the process is killed, the caller receives `ActionInterruptedError` with reason
+    `time_limit`, and `Middleware.on_transition()` receives `interrupted`. None leaves a limit to
+    the executor's own configuration.
+
+    The executor enforces them (`celery_viewset` sends them with each call); an in-process action
+    has no time limit. A value in `settings.default_action_configuration` applies to every action,
+    and `ByAction` varies it per action.
+    """
+
+    soft: float | None = None
+    hard: float | None = None
+
+
 def _candidate_method_names(action_name: str) -> list[str]:
     names = [action_name]
     perform_name = _PERFORM_METHOD_BY_ACTION.get(action_name)

{dynamicforms_fastapi_viewsets-0.10.0 → dynamicforms_fastapi_viewsets-0.11.0}/fastapi_viewsets/decorators/celery_viewset/__init__.py

@@ -49,14 +49,14 @@ def celery_viewset(
     - In a Celery worker (detected via sys.argv or set_is_celery_worker): uses celery_viewset_server
     - In a FastAPI app: uses celery_viewset_client
 
-    For explicit control, use celery_viewset_client or celery_viewset_server directly.
+    For explicit control, use celery_viewset_client or celery_viewset_server directly. Both modes
+    require redis_client.
     """
+    if redis_client is None:
+        raise ValueError("redis_client is required for celery_viewset")
     if _detect_is_celery_worker():
         return celery_viewset_server(celery_app, task_prefix, lifecycle=lifecycle, redis_client=redis_client)
-    else:
-        if redis_client is None:
-            raise ValueError("redis_client is required for celery_viewset in client (FastAPI) mode")
-        return celery_viewset_client(celery_app, task_prefix, redis_client=redis_client, result_timeout=result_timeout)
+    return celery_viewset_client(celery_app, task_prefix, redis_client=redis_client, result_timeout=result_timeout)
 
 
 def check_result_readers() -> frozenset[str]:

{dynamicforms_fastapi_viewsets-0.10.0 → dynamicforms_fastapi_viewsets-0.11.0}/fastapi_viewsets/decorators/celery_viewset/client.py

@@ -8,10 +8,12 @@ from typing import TYPE_CHECKING, TypeVar
 
 from pydantic import BaseModel
 
+from ...action_configuration import resolve_action_configuration, TimeLimits
 from ...context import Context, SerializableObject, serialize_context, to_jsonable
 from ...exceptions import ActionDispatchError, ResultTimeoutError
+from ...middleware import ActionTransition, run_transition_listeners
 from ..build_schema import build_schema
-from ..lifecycle_runner import current_call, DEFERRED_ACTIONS_ATTRIBUTE
+from ..lifecycle_runner import current_call, DEFERRED_ACTIONS_ATTRIBUTE, effective_middlewares
 from ..primary_key_model_helper import PARTIAL_UPDATE_ACTIONS
 from . import result_reader
 from .payload import CONTEXT_KWARG, PARENT_KWARG, REQUEST_KWARG, request_to_jsonable
@@ -96,14 +98,30 @@ async def _serialize_value(value, partial: bool = False):
     return to_jsonable(value)
 
 
+def _time_limit_options(context: Context) -> dict:
+    """The `send_task` time limit options of the call's `TimeLimits` configuration."""
+    limits = context.configuration_for(TimeLimits)
+    if limits is None:
+        return {}
+    options = {}
+    if limits.soft is not None:
+        options["soft_time_limit"] = limits.soft
+    if limits.hard is not None:
+        options["time_limit"] = limits.hard
+    return options
+
+
 def _patch_method(
     cls: type, original_endpoint, task_name: str, celery_app, queue_key: str, result_timeout: float | None
 ):
     """Replace the method on cls with an async version that sends a Celery task and awaits the result.
 
     The task carries the call's context, request and parent execution (see `payload`) from
-    `current_call()`; a `context` the caller passes replaces the call's. A send that fails raises
-    `ActionDispatchError`. The action's name joins the class's `DEFERRED_ACTIONS_ATTRIBUTE`."""
+    `current_call()`; a `context` the caller passes replaces the call's. The action's `TimeLimits`
+    configuration is sent as the task's time limits. Arguments that cannot be serialized raise
+    `ActionDispatchError` (reason `serialization`), a send that fails raises it with reason `send`.
+    Once the task is sent, `Middleware.on_transition()` of the action's effective middlewares
+    receives `dispatched`. The action's name joins the class's `DEFERRED_ACTIONS_ATTRIBUTE`."""
     method_name = original_endpoint.__name__
     declares_request = "request" in inspect.signature(original_endpoint).parameters
 
@@ -122,10 +140,26 @@ def _patch_method(
             if declares_request:
                 kwargs.pop("request", None)
             parent = call.parent_of_dispatch() if call is not None else None
-            serializable_args = [await _serialize_value(v) for v in args]
-            serializable_kwargs = {
-                k: await _serialize_value(v, method_name in PARTIAL_UPDATE_ACTIONS) for k, v in kwargs.items()
-            }
+            action_configuration = resolve_action_configuration(cls, method_name)
+            bound_context = Context(context.raw(), action_configuration=action_configuration, action_name=method_name)
+            try:
+                serializable_args = [await _serialize_value(v) for v in args]
+                serializable_kwargs = {
+                    k: await _serialize_value(v, method_name in PARTIAL_UPDATE_ACTIONS) for k, v in kwargs.items()
+                }
+                task_kwargs = {
+                    **serializable_kwargs,
+                    CONTEXT_KWARG: await serialize_context(context.raw()),
+                    REQUEST_KWARG: request_to_jsonable(call.request if call is not None else None),
+                    PARENT_KWARG: parent.to_jsonable() if parent is not None else None,
+                    "_correlation_id": correlation_id,
+                    "_result_queue_key": get_process_queue_key(queue_key),
+                }
+            except Exception as error:
+                logger.error(
+                    "Celery task arguments not serializable: %s (correlation_id=%s)", task_name, correlation_id
+                )
+                raise ActionDispatchError(task_name, "serialization") from error
             logger.info("Celery task scheduling: %s (correlation_id=%s)", task_name, correlation_id)
             try:
                 # send_task() blocks while it connects and publishes to the broker.
@@ -133,23 +167,21 @@ def _patch_method(
                     celery_app.send_task,
                     task_name,
                     args=serializable_args,
-                    kwargs={
-                        **serializable_kwargs,
-                        CONTEXT_KWARG: await serialize_context(context.raw()),
-                        REQUEST_KWARG: request_to_jsonable(call.request if call is not None else None),
-                        PARENT_KWARG: parent.to_jsonable() if parent is not None else None,
-                        "_correlation_id": correlation_id,
-                        "_result_queue_key": get_process_queue_key(queue_key),
-                    },
+                    kwargs=task_kwargs,
                     # send_task() defaults ignore_result to False regardless of what the task was
                     # registered with (celery_viewset_server sets ignore_result=True) - Celery's
                     # per-request value overrides the task's own, so it must be repeated here or the
                     # worker still tries to JSON-encode the raw return value into its result backend.
                     ignore_result=True,
+                    **_time_limit_options(bound_context),
                 )
             except Exception as error:
                 logger.error("Celery task not sent: %s (correlation_id=%s)", task_name, correlation_id)
-                raise ActionDispatchError(task_name) from error
+                raise ActionDispatchError(task_name, "send") from error
+            await run_transition_listeners(
+                effective_middlewares(action_configuration),
+                ActionTransition("dispatched", cls, method_name, bound_context, parent, None),
+            )
             try:
                 return await asyncio.wait_for(future, result_timeout)
             except asyncio.TimeoutError:

{dynamicforms_fastapi_viewsets-0.10.0 → dynamicforms_fastapi_viewsets-0.11.0}/fastapi_viewsets/decorators/celery_viewset/result_reader.py

@@ -7,9 +7,10 @@ import socket
 from typing import TYPE_CHECKING
 
 from fastapi import HTTPException
+from fastapi.exceptions import RequestValidationError
 
 from ...context import from_jsonable
-from ...exceptions import ResultReaderStoppedError
+from ...exceptions import _error_from_jsonable, _error_to_jsonable, ActionFailedError, ResultReaderStoppedError
 
 if TYPE_CHECKING:
     import redis
@@ -88,27 +89,12 @@ async def _read_results(redis_client: "redis.Redis", queue_key: str, poll_interv
 
             data = json.loads(item)
             correlation_id = data.get("correlation_id")
-            result = data.get("result")
-            error = data.get("error")
 
             pending = _pending_futures.pop(correlation_id, None)
             if pending is None:
                 logger.warning("No pending future for correlation_id=%s", correlation_id)
                 continue
-            future = pending[0]
-
-            if not future.done():
-                if error is not None:
-                    http_status_code = data.get("http_status_code")
-                    http_detail = data.get("http_detail")
-                    if http_status_code is not None:
-                        future.set_exception(HTTPException(status_code=http_status_code, detail=http_detail))
-                    else:
-                        future.set_exception(Exception(error))
-                else:
-                    # Undoes _to_jsonable's SerializableObject tagging (see server.py) at any depth -
-                    # an untagged value passes through unchanged.
-                    future.set_result(from_jsonable(result))
+            _resolve(pending[0], data)
 
         except asyncio.CancelledError:
             break
@@ -117,22 +103,78 @@ async def _read_results(redis_client: "redis.Redis", queue_key: str, poll_interv
             await asyncio.sleep(poll_interval)
 
 
+def _resolve(future: asyncio.Future, data: dict) -> None:
+    """Resolves `future` with the result or the error of one payload."""
+    if future.done():
+        return
+    task = data.get("task")
+    try:
+        if data.get("error") is not None:
+            future.set_exception(_payload_error(data))
+        else:
+            # Undoes _to_jsonable's SerializableObject tagging (see server.py) at any depth - an
+            # untagged value passes through unchanged.
+            future.set_result(from_jsonable(data.get("result")))
+    except Exception as error:
+        logger.exception("Result of %s (correlation_id=%s) cannot be read", task, data.get("correlation_id"))
+        failure = ActionFailedError(task, "result")
+        failure.__cause__ = error
+        future.set_exception(failure)
+
+
+def _payload_error(data: dict) -> Exception:
+    """The exception a payload's `error` carries. An `error` that is not encoded fields is an
+    `HTTPException` when the payload has `http_status_code`, else an `ActionFailedError`."""
+    error = data["error"]
+    if isinstance(error, dict):
+        return _error_from_jsonable(error)
+    if data.get("http_status_code") is not None:
+        return HTTPException(status_code=data["http_status_code"], detail=data.get("http_detail"))
+    return ActionFailedError(data.get("task"))
+
+
+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`.
+    """
+    if not isinstance(error, (HTTPException, RequestValidationError)):
+        error = ActionFailedError(task)
+    encoded = _error_to_jsonable(error)
+    return {
+        "correlation_id": correlation_id,
+        "task": task,
+        "error": encoded,
+        "http_status_code": encoded["status_code"],
+        "http_detail": encoded["detail"],
+    }
+
+
 def push_payload(redis_client: "redis.Redis", queue_key: str, data: dict) -> None:
     """Push one result payload to queue_key and renew the list's expiry to RESULT_QUEUE_TTL."""
     redis_client.rpush(queue_key, json.dumps(data))
     redis_client.expire(queue_key, RESULT_QUEUE_TTL)
 
 
-def push_result(redis_client: "redis.Redis", queue_key: str, correlation_id: str, result=None, error=None) -> None:
+def push_result(
+    redis_client: "redis.Redis",
+    queue_key: str,
+    correlation_id: str,
+    result=None,
+    error: BaseException | None = None,
+    task: str | None = None,
+) -> None:
     """
     Push a result or an error for one call. queue_key is the `_result_queue_key` the client sent with
-    the task.
+    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.
     """
-    data = {"correlation_id": correlation_id}
     if error is not None:
-        data["error"] = str(error)
+        data = error_payload(correlation_id, task, error)
     else:
-        data["result"] = result
+        data = {"correlation_id": correlation_id, "task": task, "result": result}
     push_payload(redis_client, queue_key, data)