dynamicforms-fastapi-viewsets 0.1.0__tar.gz → 0.1.1__tar.gz

{dynamicforms_fastapi_viewsets-0.1.0 → dynamicforms_fastapi_viewsets-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamicforms-fastapi-viewsets
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -29,13 +29,21 @@ Provides-Extra: celery
 Requires-Dist: celery>=5.3; extra == 'celery'
 Requires-Dist: redis>=5.0; extra == 'celery'
 Provides-Extra: dev
+Requires-Dist: asgiref; extra == 'dev'
 Requires-Dist: celery; extra == 'dev'
 Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: django; extra == 'dev'
 Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pyjwt; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-asyncio; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: redis; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: asgiref>=3.6; extra == 'django'
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: jwt
+Requires-Dist: pyjwt>=2.8; extra == 'jwt'
 Description-Content-Type: text/markdown
 
 # DynamicForms FastAPI Viewsets
@@ -48,8 +56,9 @@ Celery-backed async execution and a matching Vue/TypeScript client counterpart.
   Handles type resolution, lifecycle management and OpenAPI schema automatically.
 - **`CollectionViewSet`** — zero-boilerplate in-memory viewset backed by any Python list, set or dict.
   Great for prototyping and testing.
-- **`CeleryViewSet`** — delegate all CRUD operations to Celery tasks, for long-running or background
-  processing scenarios (requires the `celery` extra).
+- **`celery_viewset` decorator** — move a viewset's execution to a Celery worker with no code changes
+  to the viewset itself, for long-running or background processing scenarios (requires the `celery`
+  extra).
 - **Bulk operations** — first-class support for bulk create, update, partial update and destroy.
 - **Vue / TypeScript counterpart** — mirror mixin classes and a `route_rest` factory give you a fully
   typed HTTP client that matches your backend viewset exactly (published separately as
@@ -98,7 +107,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`, `CeleryViewSet`, and the Vue client.
+the mixin system, `route_viewset`, `CollectionViewSet`, `celery_viewset`, and the Vue client.
 
 ## License
 

{dynamicforms_fastapi_viewsets-0.1.0 → dynamicforms_fastapi_viewsets-0.1.1}/README.md

@@ -8,8 +8,9 @@ Celery-backed async execution and a matching Vue/TypeScript client counterpart.
   Handles type resolution, lifecycle management and OpenAPI schema automatically.
 - **`CollectionViewSet`** — zero-boilerplate in-memory viewset backed by any Python list, set or dict.
   Great for prototyping and testing.
-- **`CeleryViewSet`** — delegate all CRUD operations to Celery tasks, for long-running or background
-  processing scenarios (requires the `celery` extra).
+- **`celery_viewset` decorator** — move a viewset's execution to a Celery worker with no code changes
+  to the viewset itself, for long-running or background processing scenarios (requires the `celery`
+  extra).
 - **Bulk operations** — first-class support for bulk create, update, partial update and destroy.
 - **Vue / TypeScript counterpart** — mirror mixin classes and a `route_rest` factory give you a fully
   typed HTTP client that matches your backend viewset exactly (published separately as
@@ -58,7 +59,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`, `CeleryViewSet`, and the Vue client.
+the mixin system, `route_viewset`, `CollectionViewSet`, `celery_viewset`, and the Vue client.
 
 ## License
 

dynamicforms_fastapi_viewsets-0.1.1/fastapi_viewsets/__init__.py

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

dynamicforms_fastapi_viewsets-0.1.1/fastapi_viewsets/action_configuration.py

@@ -0,0 +1,111 @@
+from typing import Any
+
+from .conf import settings
+from .middleware import Middleware
+
+_PERFORM_METHOD_BY_ACTION = {
+    "create": "perform_create",
+    "bulk_create": "perform_bulk_create",
+    "list_items": "perform_list",
+    "retrieve": "perform_retrieve",
+    "update": "perform_update",
+    "partial_update": "perform_update",
+    "bulk_update": "perform_bulk_update",
+    "bulk_partial_update": "perform_bulk_update",
+    "destroy": "perform_destroy",
+    "bulk_destroy": "perform_bulk_destroy",
+    "lookup": "perform_lookup",
+}
+"""Mirrors the action-method -> perform_* wiring already in mixins.py, so @action_configuration on
+a perform_* method (where CRUD logic actually lives) is found when resolving its action's config,
+not just on the framework's own @final action methods (update, list_items, ...)."""
+
+
+def action_configuration(config: dict[Any, Any]):
+    """
+    Attaches per-viewset/per-action configuration for context processors and command middleware to
+    consult - works identically whether applied to a viewset class or to an individual method
+    (typically a perform_* method). Keys are identifiers (a context processor callable, a
+    Middleware subclass already registered in settings.viewsets_command_middleware, or a fresh
+    Middleware instance to inject just for this call - see extra_middlewares_for); values are
+    opaque, interpreted only by whichever processor/middleware reads them (see
+    fastapi_viewsets/context/__init__.py's Context.configuration_for and build_context). See
+    docs/guide/action-configuration.md.
+
+        @action_configuration({Session: False})
+        class LoginViewSet(...): ...
+
+        class ItemViewSet(...):
+            @action_configuration({Session: False})
+            async def perform_list(self, context): ...
+    """
+
+    def decorator(target):
+        target.__action_configuration__ = config
+        return target
+
+    return decorator
+
+
+def _candidate_method_names(action_name: str) -> list[str]:
+    names = [action_name]
+    perform_name = _PERFORM_METHOD_BY_ACTION.get(action_name)
+    if perform_name:
+        names.append(perform_name)
+    return names
+
+
+def resolve_action_configuration(cls: type, action_name: str) -> dict[Any, Any]:
+    """
+    Merges settings.default_action_configuration (lowest priority) -> class-level
+    @action_configuration -> method-level @action_configuration (highest priority), per identifier
+    (a method-level entry for an identifier fully replaces whatever a lower layer had for that same
+    identifier; identifiers a method doesn't mention still fall through from the class/default).
+
+    Returns the raw merged dict - ByAction values are left unresolved (see
+    fastapi_viewsets/context/__init__.py's Context.configuration_for, which resolves them at read
+    time against the current action, so a Context reused across actions - e.g. via
+    clone_for_command - never resolves stale).
+
+    Takes the viewset *class* (not an instance) - method-level lookup via `getattr(cls, candidate)`
+    returns the same underlying function (and thus the same `__action_configuration__` attribute)
+    as `getattr(instance, candidate)` would, so no instance is ever needed; this also lets it be
+    called before a viewset instance exists yet (e.g. from an early Middleware.depends() call - see
+    route_viewset.py - for per-request/instance-key lifecycles).
+
+    Method-level lookup checks both the actual action method name (for hand-written __router
+    endpoints, which have no separate perform_* counterpart) and its mapped perform_* method (where
+    CRUD logic actually lives - see _PERFORM_METHOD_BY_ACTION), in that order, so a perform_*-level
+    override wins if both happen to be decorated.
+    """
+    merged: dict[Any, Any] = dict(settings.default_action_configuration)
+    merged.update(getattr(cls, "__action_configuration__", {}))
+    for candidate in _candidate_method_names(action_name):
+        method_config = getattr(getattr(cls, candidate, None), "__action_configuration__", None)
+        if method_config:
+            merged.update(method_config)
+    return merged
+
+
+def extra_middlewares_for(action_configuration: dict[Any, Any], global_middlewares: list) -> list:
+    """
+    Keys in `action_configuration` that are a Middleware *instance* are appended to the chain,
+    just for this call, in dict-iteration order - this is how @action_configuration injects a
+    brand-new middleware for one viewset/method without registering it globally. Keys that are a
+    Middleware *class* configure an already-globally-registered instance of that type (read via
+    Middleware.config_from/Context.configuration_for) - a class with no matching instance in
+    `global_middlewares` raises ValueError, fail-fast, since it's almost certainly a typo or a
+    forgotten global registration rather than an intentional injection (use an instance for that).
+    """
+    global_types = {type(mw) for mw in global_middlewares}
+    extras = []
+    for identifier in action_configuration:
+        if isinstance(identifier, Middleware):
+            extras.append(identifier)
+        elif isinstance(identifier, type) and issubclass(identifier, Middleware) and identifier not in global_types:
+            raise ValueError(
+                f"{identifier.__name__} is configured via @action_configuration but has no instance "
+                f"in settings.viewsets_command_middleware - register one globally, or pass a "
+                f"Middleware instance (not the class) to inject a new one just for this call."
+            )
+    return extras

{dynamicforms_fastapi_viewsets-0.1.0 → dynamicforms_fastapi_viewsets-0.1.1}/fastapi_viewsets/collection_viewset.py

@@ -4,6 +4,7 @@ from typing import Any, Generic, TypeVar
 
 from pydantic import BaseModel
 
+from .context import Context
 from .mixins import ImplMixin
 from .response_classes import NotFoundError
 
@@ -39,35 +40,37 @@ class AsyncCollectionViewSet(
     async def container_delete(self, pk: K) -> None:
         raise NotImplementedError
 
-    async def perform_list(self) -> list[T]:
+    async def perform_list(self, _context: Context) -> list[T]:
         return await self.container_list()
 
-    async def perform_retrieve(self, pk: K) -> T:
+    async def perform_retrieve(self, _context: Context, pk: K) -> T:
         return await self.container_retrieve(pk)
 
-    async def perform_create(self, data: T) -> T:
+    async def perform_create(self, _context: Context, data: T) -> T:
         return await self.container_add(data)
 
-    async def perform_bulk_create(self, data: list[T]) -> list[T]:
+    async def perform_bulk_create(self, _context: Context, data: list[T]) -> list[T]:
         results = []
         for item in data:
             results.append(await self.container_add(item))
         return results
 
-    async def perform_update(self, pk: K, data: T, partial: bool = True) -> T:
+    async def perform_update(self, _context: Context, pk: K, data: T, partial: bool = True) -> T:
         return await self.container_update(pk, data, partial)
 
-    async def perform_bulk_update(self, records: dict[K, T], partial: bool = True) -> list[T]:
+    async def perform_bulk_update(
+        self, _context: Context, records: dict[K, T], partial: bool = True
+    ) -> list[T]:
         results = []
         for pk, data in records.items():
             results.append(await self.container_update(pk, data, partial))
         return results
 
-    async def perform_destroy(self, pk: K) -> dict[K, Any]:
+    async def perform_destroy(self, _context: Context, pk: K) -> dict[K, Any]:
         await self.container_delete(pk)
         return {pk: None}
 
-    async def perform_bulk_destroy(self, pk: list[K]) -> list[dict[K, Any]]:
+    async def perform_bulk_destroy(self, _context: Context, pk: list[K]) -> list[dict[K, Any]]:
         results = []
         for p in pk:
             await self.container_delete(p)

dynamicforms_fastapi_viewsets-0.1.1/fastapi_viewsets/conf.py

@@ -0,0 +1,45 @@
+import json
+
+from collections.abc import Awaitable, Callable
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi import Request
+    from fastapi.security.base import SecurityBase
+
+    from .context.auth import AuthBackend
+    from .middleware import CommandMiddleware
+
+ContextProcessor = Callable[["Request", Any], Awaitable[dict[str, Any]]]
+
+
+class Settings:
+    """
+    Global, mutable settings for fastapi_viewsets - configured once by the application, e.g.:
+
+        from fastapi_viewsets.conf import settings
+
+        async def auth_processor(request, viewset) -> dict:
+            return {"user": await authenticate(request)}
+
+        settings.viewsets_context_processors = [auth_processor]
+    """
+
+    def __init__(self):
+        self.viewsets_context_processors: list[ContextProcessor] = []
+        self.viewsets_context_json_encoder: type[json.JSONEncoder] | None = None
+        self.viewsets_context_json_decoder: type[json.JSONDecoder] | None = None
+        self.viewsets_command_middleware: list[CommandMiddleware] = []
+        self.viewsets_auth_processors: list[AuthBackend] = []
+        self.default_action_configuration: dict[Any, Any] = {}
+        self.viewsets_security_scheme: SecurityBase | None = None
+        """
+        Purely for OpenAPI/Swagger discoverability (a lock icon + testable Authorize flow) - attached
+        as an extra sub-dependency alongside the per-route Middleware.depends() bridge (see
+        route_viewset.py), not otherwise consumed by this library. Must be set before any viewset
+        class is decorated with route_viewset (same existing constraint as
+        disable_response_model=bool(settings.viewsets_command_middleware) already has).
+        """
+
+
+settings = Settings()