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

dynamicforms_fastapi_viewsets-0.1.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: dynamicforms-fastapi-viewsets
+Version: 0.1.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
+Project-URL: Issues, https://github.com/dynamicforms/fastapi-viewsets/issues
+Project-URL: Documentation, https://docs.velis.si/dynamicforms/fastapi-viewsets/
+Author-email: Jure Erznožnik <jure.erznoznik@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: celery,django-rest-framework,dynamicforms,fastapi,rest,viewsets
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.100
+Requires-Dist: pydantic>=2.1
+Requires-Dist: typing-extensions>=4.10
+Provides-Extra: celery
+Requires-Dist: celery>=5.3; extra == 'celery'
+Requires-Dist: redis>=5.0; extra == 'celery'
+Provides-Extra: dev
+Requires-Dist: celery; extra == 'dev'
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: redis; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DynamicForms FastAPI Viewsets
+
+Django REST Framework-style viewsets for [FastAPI](https://fastapi.tiangolo.com/), with optional
+Celery-backed async execution and a matching Vue/TypeScript client counterpart.
+
+- **Python mixins for FastAPI** — compose CRUD and bulk endpoints from small, focused mixin classes.
+- **`route_viewset` decorator** — register a viewset on a FastAPI router with a single decorator call.
+  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).
+- **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
+  [`@dynamicforms/fastapi-viewsets`](https://www.npmjs.com/package/@dynamicforms/fastapi-viewsets) on npm).
+
+## Installation
+
+```bash
+pip install dynamicforms-fastapi-viewsets
+
+# with Celery-backed viewset support
+pip install "dynamicforms-fastapi-viewsets[celery]"
+```
+
+Requires Python 3.10+, FastAPI and Pydantic v2.
+
+## Quick example
+
+```python
+from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel
+
+from fastapi_viewsets.collection_viewset import CollectionViewSet
+from fastapi_viewsets.decorators.route_viewset import route_viewset
+from fastapi_viewsets.mixins import BulkViewSetMixin
+
+
+class Item(BaseModel):
+    id: int
+    name: str
+
+
+database: dict[int, Item] = {1: Item(id=1, name="First element")}
+
+app = FastAPI()
+router = APIRouter()
+
+
+@route_viewset(router, base_path="/items", pk_field_name="id")
+class ItemViewSet(CollectionViewSet[int, Item], BulkViewSetMixin[int, Item]):
+    def __init__(self):
+        super().__init__(container=database, pk_field="id")
+
+
+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.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

dynamicforms_fastapi_viewsets-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+fastapi_viewsets/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+fastapi_viewsets/celery_viewset.py,sha256=RuUSWg7yYFXN5XMYyo1fVhGFd1B5EnlpXdkkY8fUSCA,1805
+fastapi_viewsets/collection_viewset.py,sha256=zDZeYfKmFv0ITaZTkBcFzBrx2ogLZkhvuO_njqAym2k,7809
+fastapi_viewsets/mixins.py,sha256=1xymX80V36KrQo1HowexxBYQBn9d3DM0sjSgOSl3mYM,17175
+fastapi_viewsets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_viewsets/response_classes.py,sha256=a6ijtl4fv218K04hZ2EyNWUVkhRKpZsTevdpcPwTfPI,573
+fastapi_viewsets/decorators/__init__.py,sha256=7XVRyUuwFBIWtkTJeJfSUdM684oKlK8SSgUTSqZ7ga0,152
+fastapi_viewsets/decorators/build_schema.py,sha256=0gsXTe6nGMOgVNVfT7RD0jA8ghvaePEZo6-KSEaqiLE,6497
+fastapi_viewsets/decorators/lifecycle_runner.py,sha256=SK2l6C6tkEjUgTqbBQFLJ29xBkxIjcxd7A-EiAFaySU,2739
+fastapi_viewsets/decorators/primary_key_model_helper.py,sha256=GzcNUEa1_xEWR5nefNd0i_LEBdAJCeluMvTeeGv5m4Q,1400
+fastapi_viewsets/decorators/route_viewset.py,sha256=D8Y8yFISQUwBSL6AEyW0pF3BKcDVuFPL6K3yJz2GpvU,9409
+fastapi_viewsets/decorators/celery_viewset/__init__.py,sha256=Dg5bhnmRU22OhDWRl8vTEm2kNUObu9ioY5380np6c5g,1844
+fastapi_viewsets/decorators/celery_viewset/client.py,sha256=qHRM67ZmVK_e0JeZws3HditR4VqAvws12mvxg5yYZU0,2687
+fastapi_viewsets/decorators/celery_viewset/result_reader.py,sha256=-e7Ek83zAKtaqZc8zNLEQXMb91vUxaLD5xGbzx9uVo4,3440
+fastapi_viewsets/decorators/celery_viewset/server.py,sha256=MqLM4kfPZjV6xYO-6N2APZ3tuMYGH9hBKr0V7JKT7MA,5180
+fastapi_viewsets/save_state/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_viewsets/save_state/save_state.py,sha256=7MNSLlbzTHNNVwh8UCBh254rCAfgEbsb0pjWGs8CcPE,1041
+fastapi_viewsets/save_state/serialize_state.py,sha256=B4sVAs34NxXOngXIQl539wDc6hxv6DsUL64N85ckcv4,892
+dynamicforms_fastapi_viewsets-0.1.0.dist-info/METADATA,sha256=xqJIg-q7GvCwY40g7MrkrKLWCuq05PtW_ddCNL6kIIs,4119
+dynamicforms_fastapi_viewsets-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+dynamicforms_fastapi_viewsets-0.1.0.dist-info/licenses/LICENSE,sha256=FAkqLxu7p_qANzmRKPino1JsRH7jqPAIAU6wwF22Qko,1072
+dynamicforms_fastapi_viewsets-0.1.0.dist-info/RECORD,,

dynamicforms_fastapi_viewsets-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dynamicforms_fastapi_viewsets-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jure Erznožnik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_viewsets/__init__.py

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

fastapi_viewsets/celery_viewset.py

@@ -0,0 +1,50 @@
+from typing import Any, Generic, TYPE_CHECKING, TypeVar
+
+from .mixins import BulkViewSetMixin
+
+if TYPE_CHECKING:
+    from celery import Celery
+
+
+T = TypeVar("T")
+K = TypeVar("K")
+
+
+class CeleryViewSet(BulkViewSetMixin[K, T], Generic[K, T]):
+    def __init__(self, celery: "Celery", task_prefix: str):
+        self.celery = celery
+        self.task_prefix = task_prefix
+
+    async def perform_create(self, data):
+        result = self.celery.send_task(f"{self.task_prefix}.create", args=[data])
+        return result
+
+    async def perform_bulk_create(self, data: list):
+        result = self.celery.send_task(f"{self.task_prefix}.bulk_create", args=[data])
+        return result
+
+    async def perform_list(self):
+        result = self.celery.send_task(f"{self.task_prefix}.list")
+        return result
+
+    async def perform_retrieve(self, pk):
+        result = self.celery.send_task(f"{self.task_prefix}.retrieve", args=[pk])
+        return result
+
+    async def perform_update(self, pk, data, partial: bool = True):
+        task_name = "partial_update" if partial else "update"
+        result = self.celery.send_task(f"{self.task_prefix}.{task_name}", args=[pk, data])
+        return result
+
+    async def perform_bulk_update(self, records: dict, partial: bool = True):
+        task_name = "bulk_partial_update" if partial else "bulk_update"
+        result = self.celery.send_task(f"{self.task_prefix}.{task_name}", args=[records])
+        return result
+
+    async def perform_destroy(self, pk) -> dict[Any, Any]:
+        result = self.celery.send_task(f"{self.task_prefix}.destroy", args=[pk])
+        return result
+
+    async def perform_bulk_destroy(self, pk: list) -> list[dict[Any, Any]]:
+        result = self.celery.send_task(f"{self.task_prefix}.bulk_destroy", args=[pk])
+        return result

fastapi_viewsets/collection_viewset.py

@@ -0,0 +1,216 @@
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable, MutableMapping, MutableSequence, MutableSet
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+from .mixins import ImplMixin
+from .response_classes import NotFoundError
+
+T = TypeVar("T")
+K = TypeVar("K")
+
+ReadableCollection = Iterable[T]  # list/retrieve only
+MutableCollection = MutableSequence[T] | MutableSet[T] | MutableMapping[K, T]  # + create/update/delete
+
+
+class AsyncCollectionViewSet(
+    Generic[K, T],
+    ImplMixin[K, T],
+    ABC,
+):
+    @abstractmethod
+    async def container_list(self) -> list[T]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def container_retrieve(self, pk: K) -> T:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def container_add(self, data: T) -> T:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def container_update(self, pk: K, data: T, partial: bool) -> T:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def container_delete(self, pk: K) -> None:
+        raise NotImplementedError
+
+    async def perform_list(self) -> list[T]:
+        return await self.container_list()
+
+    async def perform_retrieve(self, pk: K) -> T:
+        return await self.container_retrieve(pk)
+
+    async def perform_create(self, data: T) -> T:
+        return await self.container_add(data)
+
+    async def perform_bulk_create(self, 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:
+        return await self.container_update(pk, data, partial)
+
+    async def perform_bulk_update(self, 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]:
+        await self.container_delete(pk)
+        return {pk: None}
+
+    async def perform_bulk_destroy(self, pk: list[K]) -> list[dict[K, Any]]:
+        results = []
+        for p in pk:
+            await self.container_delete(p)
+            results.append({p: None})
+        return results
+
+
+class CollectionViewSet(AsyncCollectionViewSet[K, T]):
+    def __init__(self, container: ReadableCollection[T] | MutableCollection[K, T], pk_field: str = "id"):
+        self.container = container
+        self.pk_field = pk_field
+        self.is_mutable = isinstance(container, (MutableSequence, MutableSet, MutableMapping))
+
+        self._add_func: Callable | None = None
+        self._update_func: Callable | None = None
+        self._delete_func: Callable | None = None
+
+        if self.is_mutable:
+            if isinstance(container, MutableSequence):
+                self._add_func = container.append
+                self._update_func = self._update_sequence
+                self._delete_func = self._delete_sequence
+            elif isinstance(container, MutableSet):
+                self._add_func = container.add
+                self._update_func = self._update_set
+                self._delete_func = container.remove
+            elif isinstance(container, MutableMapping):
+                self._add_func = self._add_mapping
+                self._update_func = self._update_mapping
+                self._delete_func = container.__delitem__
+
+    def _check_mutable(self):
+        if not self.is_mutable:
+            raise Exception("Provided container is not mutable")
+
+    def _get_pk(self, item: T) -> K:
+        if isinstance(item, dict):
+            return item[self.pk_field]
+        return getattr(item, self.pk_field)
+
+    # Sequence helpers
+    def _update_sequence(self, pk: K, data: T, partial: bool):
+        for i, item in enumerate(self.container):
+            if self._get_pk(item) == pk:
+                if partial:
+                    if isinstance(item, dict):
+                        item.update(data)
+                    else:
+                        for key, value in data.items():
+                            setattr(item, key, value)
+                else:
+                    self.container[i] = data
+                return self.container[i]
+        raise NotFoundError(pk)
+
+    def _delete_sequence(self, pk: K):
+        for i, item in enumerate(self.container):
+            if self._get_pk(item) == pk:
+                del self.container[i]
+                return
+        raise NotFoundError(pk)
+
+    # Set helpers
+    def _update_set(self, pk: K, data: T, partial: bool):
+        for item in self.container:
+            if self._get_pk(item) == pk:
+                self.container.remove(item)
+                self.container.add(data)  # Sets don't really support partial update easily without mutation
+                return data
+        raise NotFoundError(pk)
+
+    # Mapping helpers
+    def _add_mapping(self, data: T):
+        pk = self._get_pk(data)
+        self.container[pk] = data
+
+    def _update_mapping(self, pk: K, data: T, partial: bool):
+        if pk not in self.container:
+            raise NotFoundError(pk)
+        if partial:
+            item = self.container[pk]
+            if isinstance(item, dict):
+                item.update(data)
+            else:
+                for key, value in data.items():
+                    setattr(item, key, value)
+        else:
+            self.container[pk] = data
+        return self.container[pk]
+
+    async def container_list(self) -> list[T]:
+        if isinstance(self.container, MutableMapping):
+            return list(self.container.values())
+        return list(self.container)
+
+    async def container_retrieve(self, pk: K) -> T:
+        if isinstance(self.container, MutableMapping):
+            if pk in self.container:
+                return self.container[pk]
+        else:
+            for item in self.container:
+                if self._get_pk(item) == pk:
+                    return item
+        raise NotFoundError(pk)
+
+    async def container_add(self, data: T) -> T:
+        self._check_mutable()
+        self._handle_autoinc(data)
+        self._add_func(data)
+        return data
+
+    def _handle_autoinc(self, data: T):
+        if not isinstance(data, BaseModel):
+            return
+
+        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
+                current_val = getattr(data, field_name, None)
+                if current_val:
+                    continue
+
+                # We find the max value in the container
+                max_val = 0
+                items = self.container.values() if isinstance(self.container, MutableMapping) else self.container
+                for item in items:
+                    try:
+                        val = item[field_name] if isinstance(item, dict) else getattr(item, field_name, 0)
+                        if isinstance(val, int) and val > max_val:
+                            max_val = val
+                    except (KeyError, AttributeError):
+                        continue
+
+                setattr(data, field_name, max_val + 1)
+
+    async def container_update(self, pk: K, data: T, partial: bool) -> T:
+        self._check_mutable()
+        return self._update_func(pk, data, partial)
+
+    async def container_delete(self, pk: K) -> None:
+        self._check_mutable()
+        try:
+            self._delete_func(pk)
+        except KeyError as e:
+            raise NotFoundError(pk) from e

fastapi_viewsets/decorators/__init__.py

@@ -0,0 +1,2 @@
+from .celery_viewset import celery_viewset, celery_viewset_client, celery_viewset_server, set_is_celery_worker
+from .route_viewset import route_viewset

fastapi_viewsets/decorators/build_schema.py

@@ -0,0 +1,161 @@
+import warnings
+
+from typing import get_args, get_origin, TypeVar
+
+from fastapi import APIRouter, FastAPI
+from fastapi.routing import APIRoute
+
+
+def route_to_add_api_route_kwargs(route: APIRoute, **kwargs) -> dict:
+    """
+    Maps an APIRoute instance to a dict of kwargs suitable for add_api_route().
+    Any keyword arguments passed will override the corresponding route attributes.
+    """
+    result = dict(
+        path=route.path,
+        endpoint=route.endpoint,
+        response_model=route.response_model,
+        status_code=route.status_code,
+        tags=route.tags,
+        dependencies=route.dependencies,
+        summary=route.summary,
+        description=route.description,
+        response_description=route.response_description,
+        responses=route.responses,
+        deprecated=route.deprecated,
+        methods=route.methods,
+        operation_id=route.operation_id,
+        include_in_schema=route.include_in_schema,
+        response_class=route.response_class,
+        name=route.name,
+        callbacks=route.callbacks,
+        openapi_extra=route.openapi_extra,
+        generate_unique_id_function=route.generate_unique_id_function,
+    )
+    unknown_keys = set(kwargs) - set(result)
+    if unknown_keys:
+        warnings.warn(
+            f"route_to_add_api_route_kwargs() received unknown kwargs: {unknown_keys}",
+            stacklevel=2,
+        )
+    result.update(kwargs)
+    return result
+
+
+def build_schema(cls, base_path: str = "", default_tags=None, get_wrapper=None, disable_response_model=False):
+    """
+    Builds __router (APIRouter with all routes from mixins) and __app (FastAPI instance),
+    and attaches them to the class. Idempotent: if already called, returns immediately.
+    If get_wrapper is None, only __router is built (no FastAPI app, no endpoint wrapping).
+
+    disable_response_model: pass True when the class defines `finalize_response` (see
+    route_viewset.py) - that hook can change the shape of what's actually served (e.g. strip an
+    internal-only field), so FastAPI must not coerce/re-validate the endpoint's return value
+    against the ORIGINAL method's declared return type, which would silently undo the hook's
+    changes (missing fields reappear with their model defaults).
+    """
+    if hasattr(cls, "__router") and (get_wrapper is None or getattr(cls, "__router_full", False)):
+        return
+
+    celery_mode = get_wrapper is None
+    # Use a dict so that more-specific classes (visited later in reversed MRO) override
+    # routes from less-specific base classes.  This allows e.g. FilterableMixin to
+    # replace ListMixin's plain GET "" route with one that carries filter query params.
+    route_registry: dict[tuple, APIRoute] = {}
+
+    for base in reversed(cls.__mro__):
+        mangled_name = f"_{base.__name__}__router"
+        mixin_router = getattr(base, mangled_name, None)
+        if mixin_router and isinstance(mixin_router, APIRouter):
+            for route in mixin_router.routes:
+                if not isinstance(route, APIRoute):
+                    continue
+
+                full_path = f"{base_path.rstrip('/')}/{route.path.lstrip('/')}".rstrip("/")
+                if not full_path:
+                    full_path = "/"
+
+                route_key = (tuple(sorted(route.methods)), full_path)
+                route_registry[route_key] = route  # last (most specific) wins
+
+    all_routes = list(route_registry.values())
+
+    class_router = APIRouter()
+
+    if not celery_mode:
+        app = FastAPI()
+
+        def schema():
+            return app.openapi()
+
+        schema_route_kwargs = dict(
+            path=f"{base_path.rstrip('/')}/schema",
+            endpoint=schema,
+            tags=default_tags,
+            methods=["GET"],
+            description="Returns OpenAPI schema for the ViewSet",
+        )
+        class_router.add_api_route(**schema_route_kwargs)
+
+        for route in sorted(all_routes, key=route_sort_key, reverse=True):
+            full_path = f"{base_path.rstrip('/')}/{route.path.lstrip('/')}".rstrip("/")
+            if not full_path:
+                full_path = "/"
+
+            endpoint_wrapper, resolved_response_model = get_wrapper(route.endpoint, route.path, route.methods)
+
+            if disable_response_model:
+                response_model = None
+            else:
+                use_resolved = (
+                    route.response_model is None or isinstance(route.response_model, TypeVar) or
+                    (get_origin(route.response_model) and
+                     any(isinstance(arg, TypeVar) for arg in get_args(route.response_model)))
+                )
+                response_model = resolved_response_model if use_resolved else route.response_model
+
+            class_router.add_api_route(**route_to_add_api_route_kwargs(
+                route,
+                path=full_path,
+                endpoint=endpoint_wrapper,
+                response_model=response_model,
+                tags=route.tags or default_tags,
+            ))
+
+        app.include_router(class_router)
+        cls.__app = app
+    else:
+        # celery mode: store raw mixin routes directly, no FastAPI wrapping
+        for route in all_routes:
+            class_router.routes.append(route)
+
+    cls.__router = class_router
+    if not celery_mode:
+        cls.__router_full = True
+
+
+def route_sort_key(route: APIRoute):
+    path = route.path.strip("/")
+    methods = route.methods or set()
+
+    method_order = ["GET", "POST", "PUT", "PATCH", "DELETE"]
+    method_idx = min((method_order.index(m) for m in methods if m in method_order), default=10)
+
+    def segment_key(segment: str):
+        if segment == "":
+            return 0, ""
+        elif segment.startswith("{"):
+            return 1, segment
+        else:
+            return 2, segment
+
+    path_idx = tuple(segment_key(s) for s in path.split("/"))
+
+    # NOT flattened via `*path_idx, method_idx` - paths of different depths (e.g.
+    # "account/register" vs "account/register/verify/resend", a real case for custom,
+    # non-CRUD viewset actions) would then put `method_idx` (a bare int) at the same tuple
+    # position where a LONGER path still has a (int, str) segment tuple, and `sorted()` would
+    # raise `TypeError: '<' not supported between instances of 'int' and 'tuple'`. Keeping
+    # `path_idx` nested means every element at every depth is uniformly a 2-tuple - a shorter
+    # path_idx that is a prefix of a longer one compares as "less than" it with no type clash.
+    return path_idx, method_idx

fastapi_viewsets/decorators/celery_viewset/__init__.py

@@ -0,0 +1,51 @@
+import sys
+
+from ..lifecycle_runner import LifecycleType
+from .client import celery_viewset_client
+from .result_reader import get_result_queue_key, push_result, start_result_reader, stop_result_reader
+from .server import celery_viewset_server
+
+# Allow explicit override via set_is_celery_worker()
+_is_celery_worker: bool | None = None
+
+
+def set_is_celery_worker(is_worker: bool) -> None:
+    """Explicitly set whether we are running in a Celery worker context."""
+    global _is_celery_worker
+    _is_celery_worker = is_worker
+
+
+def _detect_is_celery_worker() -> bool:
+    """Auto-detect if we are running inside a Celery worker by inspecting sys.argv."""
+    if _is_celery_worker is not None:
+        return _is_celery_worker
+    return len(sys.argv) > 0 and "celery" in sys.argv[0].lower()
+
+
+def celery_viewset(celery_app, task_prefix: str, lifecycle: LifecycleType = "singleton", redis_client=None):
+    """
+    Convenience decorator that auto-detects whether to use client or server mode.
+
+    - 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.
+    """
+    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)
+
+
+__all__ = [
+    "celery_viewset",
+    "celery_viewset_client",
+    "celery_viewset_server",
+    "set_is_celery_worker",
+    "start_result_reader",
+    "stop_result_reader",
+    "push_result",
+    "get_result_queue_key",
+]