dynamicforms-fastapi-viewsets 0.1.0__py3-none-any.whl

fastapi_viewsets/decorators/celery_viewset/client.py

@@ -0,0 +1,88 @@
+import asyncio
+import logging
+import uuid
+
+from functools import wraps
+from typing import TYPE_CHECKING, TypeVar
+
+from fastapi.routing import APIRoute
+from pydantic import BaseModel
+
+from ..build_schema import build_schema
+from . import result_reader
+from .result_reader import get_result_queue_key
+
+if TYPE_CHECKING:
+    import redis
+
+    from celery import Celery
+
+T = TypeVar("T")
+logger = logging.getLogger(__name__)
+
+
+def celery_viewset_client(
+    celery_app: "Celery",
+    task_prefix: str,
+    redis_client: "redis.Redis",
+):
+    """
+    Decorator for FastAPI side. Replaces viewset methods with async wrappers that
+    send Celery tasks and await results via a Redis result queue.
+    """
+    queue_key = get_result_queue_key(task_prefix)
+
+    def decorator(cls: type[T]):
+        seen_tasks = set()
+
+        build_schema(cls)
+        for route in cls.__router.routes:
+            task_name = f"{task_prefix}.{route.name or route.endpoint.__name__}"
+
+            if task_name in seen_tasks:
+                continue
+            seen_tasks.add(task_name)
+
+            _patch_method(cls, route.endpoint, task_name, celery_app, redis_client, queue_key)
+
+        cls.__celery_viewset_metadata__ = {
+            "task_prefix": task_prefix,
+            "celery_app": celery_app,
+            "redis_client": redis_client,
+            "queue_key": queue_key,
+            "mode": "client",
+        }
+
+        return cls
+
+    return decorator
+
+
+def _patch_method(cls: type, original_endpoint, task_name: str, celery_app, redis_client, queue_key: str):
+    """Replace the method on cls with an async version that sends a Celery task and awaits the result."""
+    method_name = original_endpoint.__name__
+
+    @wraps(original_endpoint)
+    async def async_client_wrapper(_self, *args, **kwargs):
+        correlation_id = str(uuid.uuid4())
+        loop = asyncio.get_event_loop()
+        future: asyncio.Future = loop.create_future()
+        result_reader.register_future(correlation_id, future)
+
+        try:
+            serializable_kwargs = {
+                k: v.model_dump() if isinstance(v, BaseModel) else v
+                for k, v in kwargs.items()
+            }
+            logger.info("Celery task scheduling: %s (correlation_id=%s)", task_name, correlation_id)
+            celery_app.send_task(
+                    task_name,
+                    args=args,
+                    kwargs={**serializable_kwargs, "_correlation_id": correlation_id, "_result_queue_key": queue_key},
+            )
+            return await future
+        except Exception:
+            result_reader.unregister_future(correlation_id)
+            raise
+
+    setattr(cls, method_name, async_client_wrapper)

fastapi_viewsets/decorators/celery_viewset/result_reader.py

@@ -0,0 +1,99 @@
+import asyncio
+import json
+import logging
+
+from typing import TYPE_CHECKING
+
+from fastapi import HTTPException
+
+if TYPE_CHECKING:
+    import redis
+
+logger = logging.getLogger(__name__)
+
+# Global registry: correlation_id -> asyncio.Future
+_pending_futures: dict[str, asyncio.Future] = {}
+
+# Global reader task reference
+_reader_task: asyncio.Task | None = None
+
+
+def register_future(correlation_id: str, future: asyncio.Future) -> None:
+    _pending_futures[correlation_id] = future
+
+
+def unregister_future(correlation_id: str) -> None:
+    _pending_futures.pop(correlation_id, None)
+
+
+def get_result_queue_key(task_prefix: str) -> str:
+    return f"celery_viewset_results:{task_prefix}"
+
+
+async def result_reader_loop(redis_client: "redis.Redis", queue_key: str, poll_interval: float = 0.05) -> None:
+    """Background coroutine that reads results from Redis list and resolves pending Futures."""
+    while True:
+        try:
+            # Non-blocking pop from Redis list
+            item = await redis_client.lpop(queue_key)
+            if item is None:
+                await asyncio.sleep(poll_interval)
+                continue
+
+            data = json.loads(item)
+            correlation_id = data.get("correlation_id")
+            result = data.get("result")
+            error = data.get("error")
+
+            future = _pending_futures.pop(correlation_id, None)
+            if future is None:
+                logger.warning("No pending future for correlation_id=%s", correlation_id)
+                continue
+
+            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:
+                    future.set_result(result)
+
+        except asyncio.CancelledError:
+            break
+        except Exception as e:
+            logger.exception("Error in result_reader_loop: %s", e)
+            await asyncio.sleep(poll_interval)
+
+
+def push_result(redis_client: "redis.Redis", queue_key: str, correlation_id: str, result=None, error=None) -> None:
+    """Called from Celery worker to push result into Redis queue."""
+    data = {"correlation_id": correlation_id}
+    if error is not None:
+        data["error"] = str(error)
+    else:
+        data["result"] = result
+    redis_client.rpush(queue_key, json.dumps(data))
+
+
+async def start_result_reader(redis_client: "redis.Redis", queue_key: str, poll_interval: float = 0.05) -> asyncio.Task:
+    """Start the background result reader task. Should be called on FastAPI startup."""
+    global _reader_task
+    if _reader_task is not None and not _reader_task.done():
+        return _reader_task
+    _reader_task = asyncio.create_task(result_reader_loop(redis_client, queue_key, poll_interval))
+    return _reader_task
+
+
+async def stop_result_reader() -> None:
+    """Stop the background result reader task. Should be called on FastAPI shutdown."""
+    global _reader_task
+    if _reader_task is not None and not _reader_task.done():
+        _reader_task.cancel()
+        try:
+            await _reader_task
+        except asyncio.CancelledError:
+            pass
+    _reader_task = None

fastapi_viewsets/decorators/celery_viewset/server.py

@@ -0,0 +1,138 @@
+import asyncio
+import inspect
+import json
+import logging
+
+from functools import wraps
+from typing import get_type_hints, TYPE_CHECKING, TypeVar
+
+from fastapi import HTTPException
+from pydantic import BaseModel
+
+from ..build_schema import build_schema
+from ..lifecycle_runner import lifecycle_runner, LifecycleType
+from ..route_viewset import build_type_map, resolve_typevars
+
+if TYPE_CHECKING:
+    import redis
+
+    from celery import Celery
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+def _to_jsonable(value):
+    """Recursively convert Pydantic models and lists to JSON-serializable structures."""
+    if isinstance(value, BaseModel):
+        return value.model_dump()
+    if isinstance(value, list):
+        return [_to_jsonable(v) for v in value]
+    return value
+
+
+def _reconstruct_kwargs(original_endpoint, kwargs: dict, cls: type = None) -> dict:
+    """Reconstruct dict values back into Pydantic BaseModel instances based on endpoint type hints."""
+    try:
+        hints = get_type_hints(original_endpoint)
+    except Exception:
+        return kwargs
+
+    type_map = build_type_map(cls) if cls is not None else {}
+
+    result = {}
+    for key, value in kwargs.items():
+        hint = hints.get(key)
+        if hint is not None:
+            hint = resolve_typevars(type_map, hint)
+        if hint is not None and isinstance(value, dict) and inspect.isclass(hint) and issubclass(hint, BaseModel):
+            try:
+                result[key] = hint.model_validate(value)
+            except Exception:
+                result[key] = hint.model_construct(**value)
+        else:
+            result[key] = value
+    return result
+
+
+def celery_viewset_server(
+    celery_app: "Celery",
+    task_prefix: str,
+    lifecycle: LifecycleType = "singleton",
+    redis_client: "redis.Redis | None" = None,
+):
+    def decorator(cls: type[T]):
+        seen_tasks = set()
+        instance = cls() if lifecycle == "singleton" else None
+
+        def get_sync_wrapper(original_endpoint, task_name: str):
+            @wraps(original_endpoint)
+            def sync_wrapper(*args, **kwargs):
+                nonlocal instance
+
+                # Extract pottery/result-queue params injected by client
+                correlation_id = kwargs.pop("_correlation_id", None)
+                result_queue_key = kwargs.pop("_result_queue_key", None)
+
+                try:
+                    loop = asyncio.get_event_loop()
+                except RuntimeError:
+                    loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(loop)
+
+                if loop.is_running():
+                    import nest_asyncio
+
+                    nest_asyncio.apply()
+
+                logger.info("Celery task executing: %s (correlation_id=%s)", task_name, correlation_id)
+                try:
+                    kwargs = _reconstruct_kwargs(original_endpoint, kwargs, cls)
+                    result = loop.run_until_complete(
+                        lifecycle_runner(original_endpoint, instance, cls, lifecycle, *args, **kwargs)
+                    )
+                    logger.info("Celery task completed: %s (correlation_id=%s)", task_name, correlation_id)
+                    if correlation_id and result_queue_key and redis_client is not None:
+                        redis_client.rpush(result_queue_key, json.dumps({
+                            "correlation_id": correlation_id,
+                            "result": _to_jsonable(result),
+                        }))
+                    return result
+                except Exception as e:
+                    if isinstance(e, HTTPException):
+                        logger.info(
+                            "Celery task returned standard error: %s (correlation_id=%s): %d: %s",
+                            task_name,
+                            correlation_id,
+                            e.status_code,
+                            e.detail,
+                        )
+                    else:
+                        logger.exception("Celery task failed: %s (correlation_id=%s): %s", task_name, correlation_id, e)
+                    if correlation_id and result_queue_key and redis_client is not None:
+                        error_payload = {"correlation_id": correlation_id, "error": str(e)}
+                        if isinstance(e, HTTPException):
+                            error_payload["http_status_code"] = e.status_code
+                            error_payload["http_detail"] = e.detail
+                        redis_client.rpush(result_queue_key, json.dumps(error_payload))
+                    if not isinstance(e, HTTPException):
+                        raise
+
+            return sync_wrapper
+
+        build_schema(cls)
+        for route in cls.__router.routes:
+            task_name = f"{task_prefix}.{route.name or route.endpoint.__name__}"
+
+            if task_name in seen_tasks:
+                continue
+            seen_tasks.add(task_name)
+
+            celery_app.task(name=task_name)(get_sync_wrapper(route.endpoint, task_name))
+
+        cls.__celery_viewset_metadata__ = {"task_prefix": task_prefix, "lifecycle": lifecycle, "celery_app": celery_app}
+
+        return cls
+
+    return decorator

fastapi_viewsets/decorators/lifecycle_runner.py

@@ -0,0 +1,64 @@
+from collections.abc import Callable
+from typing import Any, Literal, TypeVar
+
+T = TypeVar("T")
+
+LifecycleType = Literal["singleton", "per-request", "instance-key"]
+
+
+async def lifecycle_runner(
+    original_endpoint: Callable,
+    singleton_instance: T,
+    cls: type[T],
+    lifecycle: LifecycleType = "singleton",
+    *args,
+    response: Any = None,
+    **kwargs
+):
+    """
+    `response` is reserved for `route_viewset`'s optional `finalize_response` hook (see below) -
+    callers that have no live Response object (e.g. `celery_viewset_server`, running in a worker
+    process) simply omit it, and `finalize_response` is never invoked.
+    """
+
+    async def run_with_state(req_instance: Any):
+        if hasattr(req_instance, "load_state"):
+            await req_instance.load_state()
+
+        try:
+            bound_method = getattr(req_instance, original_endpoint.__name__, None)
+            if bound_method is not None:
+                return await bound_method(*args, **kwargs)
+            return await original_endpoint(req_instance, *args, **kwargs)
+        finally:
+            if hasattr(req_instance, "save_state"):
+                await req_instance.save_state()
+
+    async def finalize(req_instance: Any, result: Any) -> Any:
+        # Opt-in hook, mirroring load_state/save_state: only called when the viewset defines it
+        # AND a live Response was actually supplied (route_viewset HTTP wiring, not celery_viewset
+        # worker execution - a Celery worker has no Response object to hand it). Lets the viewset
+        # translate part of its (JSON-serializable) return value into response-level side effects
+        # (e.g. Set-Cookie) that can't survive a Celery/Redis round trip themselves - see
+        # docs/guide/routers.md "Response-level side effects: finalize_response".
+        if response is not None and hasattr(req_instance, "finalize_response"):
+            return await req_instance.finalize_response(response, result)
+        return result
+
+    if lifecycle == "singleton":
+        result = await run_with_state(singleton_instance)
+        return await finalize(singleton_instance, result)
+    elif lifecycle == "per-request":
+        req_instance = cls()
+        bound_method = getattr(req_instance, original_endpoint.__name__, None)
+        if bound_method is not None:
+            result = await bound_method(*args, **kwargs)
+        else:
+            result = await original_endpoint(req_instance, *args, **kwargs)
+        return await finalize(req_instance, result)
+    elif lifecycle == "instance-key":
+        req_instance = cls()
+        result = await run_with_state(req_instance)
+        return await finalize(req_instance, result)
+
+    return await original_endpoint(*args, **kwargs)

fastapi_viewsets/decorators/primary_key_model_helper.py

@@ -0,0 +1,33 @@
+from typing import Any, get_origin, TypeVar
+
+from pydantic import BaseModel, create_model
+
+T = TypeVar("T", bound=BaseModel)
+
+def create_model_without_pk(model: type[T], pk_field_name: str) -> type[BaseModel]:
+    """
+    Creates a new Pydantic model based on the given model but without the specified primary key field.
+    """
+    fields = {
+        name: (field.annotation, field.default if field.default is not ... else ...)
+        for name, field in model.model_fields.items()
+        if name != pk_field_name
+    }
+    return create_model(f"{model.__name__}NoPK", **fields)
+
+def typecast_to_original_model(value: Any, original_annotation: type[T]) -> T:
+    """
+    Typecasts a value (usually a Pydantic model without PK) back to the original Pydantic model.
+    If validation fails (e.g., due to missing PK that will be auto-incremented), it uses model_construct.
+    """
+    origin = get_origin(original_annotation) or original_annotation
+    if not isinstance(value, BaseModel) or isinstance(value, origin):
+        return value
+
+    # noinspection PyBroadException
+    try:
+        return original_annotation.model_validate(value.model_dump())
+    except Exception:
+        # Fallback: create instance with model_construct if validation fails
+        # (e.g. required field missing but it will be filled by autoinc)
+        return original_annotation.model_construct(**value.model_dump())

fastapi_viewsets/decorators/route_viewset.py

@@ -0,0 +1,216 @@
+import inspect
+
+from functools import wraps
+from typing import Annotated, get_args, get_origin, TypeVar
+
+from fastapi import APIRouter, Depends, Query, Response
+from fastapi.params import FieldInfo
+from pydantic import BaseModel
+
+try:
+    from typing_extensions import NoDefault as _TypeVarNoDefault
+except ImportError:
+    _TypeVarNoDefault = object()  # fallback sentinel — never equal to any real TypeVar default
+
+from fastapi_viewsets.mixins import FilterParam, make_all_optional
+
+from .build_schema import build_schema, route_to_add_api_route_kwargs
+from .lifecycle_runner import lifecycle_runner, LifecycleType
+from .primary_key_model_helper import create_model_without_pk, typecast_to_original_model
+
+T = TypeVar("T")
+
+
+def build_type_map(cls: type[T], current_map: dict = None) -> dict:
+    if current_map is None:
+        current_map = {}
+
+    type_map = dict(current_map)
+
+    if not hasattr(cls, "__orig_bases__"):
+        return type_map
+
+    for base in cls.__orig_bases__:
+        origin = getattr(base, "__origin__", None)
+        if not origin:
+            continue
+
+        args = get_args(base)
+        params = getattr(origin, "__parameters__", ())
+
+        new_map = {}
+        for param, arg in zip(params, args, strict=False):
+            # Try to resolve arg (which can be a TypeVar or e.g. List[T]) from current mapping
+            new_map[param] = resolve_typevars(type_map, arg)
+
+        # Update local mapping for this origin
+        type_map.update(new_map)
+        # Recursively search parents of this origin and add results to our mapping
+        type_map.update(build_type_map(origin, new_map))
+
+    return type_map
+
+
+def resolve_typevars(type_map, annotation):
+    if isinstance(annotation, TypeVar):
+        resolved = type_map.get(annotation, annotation)
+        if not isinstance(resolved, TypeVar):
+            return resolved
+        # Fall back to PEP 696 TypeVar default when the TypeVar is not bound in the type_map
+        tv_default = getattr(resolved, "__default__", _TypeVarNoDefault)
+        if tv_default is not _TypeVarNoDefault and not isinstance(tv_default, TypeVar):
+            return tv_default
+    elif get_origin(annotation) is not None:
+        origin = get_origin(annotation)
+        args = get_args(annotation)
+        new_args = tuple(resolve_typevars(type_map, arg) for arg in args)
+        if new_args != args:
+            # To deluje za List, Dict, Union, itd.
+            try:
+                return origin[new_args]
+            except:
+                return annotation
+    return annotation
+
+
+def route_viewset(
+        router: APIRouter,
+        base_path: str,
+        lifecycle: LifecycleType = "singleton",
+        pk_field_name: str = None,
+):
+    def decorator(cls: type[T]):
+        seen_routes = set()
+        instance = cls() if lifecycle == "singleton" else None
+
+        # Opt-in: only viewsets that define `finalize_response` pay for the extra `Response`
+        # param - see docs/guide/routers.md "Response-level side effects: finalize_response".
+        has_finalize_response = hasattr(cls, "finalize_response")
+
+        type_map = build_type_map(cls)
+
+        # Derive tag from class name: strip "ViewSet" suffix if present
+        cls_name = cls.__name__
+        if cls_name.endswith("ViewSet"):
+            cls_name = cls_name[:-len("ViewSet")]
+        default_tags = [cls_name] if cls_name else None
+
+        def _is_filter_param(annotation) -> bool:
+            """Return True when annotation is Annotated[T, FilterParam()]."""
+            return (
+                hasattr(annotation, "__metadata__")
+                and any(isinstance(m, FilterParam) for m in annotation.__metadata__)
+            )
+
+        def _is_model_query_param(annotation) -> bool:
+            """Return True for Annotated[PydanticModel, <FieldInfo>] (e.g. Query() or Depends()).
+            These should use Depends() in the wrapper so FastAPI expands model fields as
+            individual query params even when other parameters are present on the same endpoint."""
+            args = getattr(annotation, "__args__", None)
+            metadata = getattr(annotation, "__metadata__", None)
+            if not (args and metadata):
+                return False
+            inner = args[0]
+            if not (inspect.isclass(inner) and issubclass(inner, BaseModel)):
+                return False
+            return any(isinstance(m, FieldInfo) for m in metadata)
+
+        def get_wrapper(original_endpoint, route_path, route_methods):
+            sig = inspect.signature(original_endpoint)
+            new_params = []
+
+            for name, p in sig.parameters.items():
+                if name == "self":
+                    continue
+
+                annotation = resolve_typevars(type_map, p.annotation)
+                new_p = p.replace(annotation=annotation)
+
+                # Transform Annotated[T, FilterParam()] → Annotated[TFilter, Query()]
+                if _is_filter_param(annotation):
+                    inner_type = annotation.__args__[0]
+                    if inspect.isclass(inner_type) and issubclass(inner_type, BaseModel):
+                        # optional_model = make_all_optional(inner_type)
+                        new_p = new_p.replace(annotation=Annotated[inner_type, Query()])
+                    new_params.append(new_p)
+                    continue
+
+                # Convert Annotated[PydanticModel, FieldInfo] → Annotated[PydanticModel, Depends()]
+                # so that FastAPI expands model fields as individual query params even when
+                # other parameters (e.g. sort) are present on the same endpoint.
+                if _is_model_query_param(annotation):
+                    inner_type = annotation.__args__[0]
+                    new_p = new_p.replace(annotation=Annotated[inner_type, Depends()])
+                    new_params.append(new_p)
+                    continue
+
+                # If we have a PK field and this parameter is a model from which we want to exclude PK
+                if (pk_field_name and
+                    inspect.isclass(annotation) and
+                    issubclass(annotation, BaseModel)
+                ):
+                    # Check if {pk} is in the path and if the method is one that normally accepts a model in the body
+                    # (POST without {pk} or PUT/PATCH with {pk})
+                    is_create = "POST" in route_methods and "{pk}" not in route_path
+                    is_update = False  # ("PUT" in route_methods or "PATCH" in route_methods) and "{pk}" in route_path
+
+                    if (is_create or is_update) and pk_field_name in annotation.model_fields:
+                        new_model = create_model_without_pk(annotation, pk_field_name)
+                        new_p = new_p.replace(annotation=new_model)
+
+                new_params.append(new_p)
+
+            if has_finalize_response:
+                # Reserved param name, only added for viewsets that opt in by defining
+                # finalize_response - FastAPI injects the REAL Response for this connection here
+                # (never forwarded to the underlying method itself, see wrapper below). Keyword-only
+                # so it can be appended regardless of what defaults precede it.
+                new_params.append(
+                    inspect.Parameter("response", inspect.Parameter.KEYWORD_ONLY, annotation=Response)
+                )
+
+            new_return_annotation = resolve_typevars(type_map, sig.return_annotation)
+            new_sig = sig.replace(parameters=new_params, return_annotation=new_return_annotation)
+
+            @wraps(original_endpoint)
+            async def wrapper(*args, **kwargs):
+                nonlocal instance
+
+                response_obj = kwargs.pop("response", None) if has_finalize_response else None
+
+                # Check if any argument needs to be "typecasted" back to the original model
+                # This happens if we replaced the model type with a NoPK version in get_wrapper
+                new_kwargs = {}
+                for param_name, value in kwargs.items():
+                    if param_name in sig.parameters:
+                        orig_param = sig.parameters[param_name]
+                        orig_annotation = resolve_typevars(type_map, orig_param.annotation)
+                        # Filter params must not be typecast — they arrive as the all-optional model
+                        if _is_filter_param(orig_annotation):
+                            new_kwargs[param_name] = value
+                        else:
+                            new_kwargs[param_name] = typecast_to_original_model(value, orig_annotation)
+                    else:
+                        new_kwargs[param_name] = value
+
+                return await lifecycle_runner(
+                    original_endpoint, instance, cls, lifecycle, *args, response=response_obj, **new_kwargs
+                )
+
+            wrapper.__signature__ = new_sig
+            return wrapper, new_return_annotation
+
+        build_schema(cls, base_path, default_tags, get_wrapper, disable_response_model=has_finalize_response)
+
+        for route in cls.__router.routes:
+            router.add_api_route(**route_to_add_api_route_kwargs(route))
+
+        cls.__viewset_metadata__ = {
+            "base_path": base_path,
+            "lifecycle": lifecycle,
+            "router": router
+        }
+
+        return cls
+
+    return decorator