django-ninja-aio-crud 1.0.5__py3-none-any.whl → 2.0.0__py3-none-any.whl

{django_ninja_aio_crud-1.0.5.dist-info → django_ninja_aio_crud-2.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 1.0.5
+Version: 2.0.0
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
 Requires-Python: >=3.10
@@ -17,15 +17,17 @@ Classifier: License :: OSI Approved :: MIT License
 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: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Framework :: Django
 Classifier: Framework :: AsyncIO
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Topic :: Internet :: WWW/HTTP
 License-File: LICENSE
-Requires-Dist: django-ninja >=1.3.0, <=1.4.5
+Requires-Dist: django-ninja >=1.3.0, <=1.5.1
 Requires-Dist: joserfc >=1.0.0, <= 1.4.1
-Requires-Dist: orjson >= 3.10.7, <= 3.11.4
+Requires-Dist: orjson >= 3.10.7, <= 3.11.5
 Requires-Dist: coverage ; extra == "test"
 Project-URL: Documentation, https://django-ninja-aio.com
 Project-URL: Repository, https://github.com/caspel26/django-ninja-aio-crud

django_ninja_aio_crud-2.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+ninja_aio/__init__.py,sha256=cH3S5kz6llYjarJhndCM9pmxriBwh3GJdi7HBMPj5v8,119
+ninja_aio/api.py,sha256=SS1TYUiFkdYjfJLVy6GI90GOzvIHzPEeL-UcqWFRHkM,1684
+ninja_aio/auth.py,sha256=8jaEp7oEJvUUB9EuyE2fOYk-khyAaekT3i80E7AbgOA,5101
+ninja_aio/decorators.py,sha256=BHoFIiqdIVMFqSxGh-F6WeZFo1xZK4ieDw3dzKfxZIM,8147
+ninja_aio/exceptions.py,sha256=1-iRbrloIyi0CR6Tcrn5YR4_LloA7PPohKIBaxXJ0-8,2596
+ninja_aio/models.py,sha256=aJlo5a64O4o-fB8QESLMUJpoA5kcjRJxPBiAIMxg46k,47652
+ninja_aio/parsers.py,sha256=e_4lGCPV7zs-HTqtdJTc8yQD2KPAn9njbL8nF_Mmgkc,153
+ninja_aio/renders.py,sha256=VtmSliRJyZ6gjyoib8AXMVUBYF1jPNsiceCHujI_mAs,1699
+ninja_aio/types.py,sha256=TJSGlA7bt4g9fvPhJ7gzH5tKbLagPmZUzfgttEOp4xs,468
+ninja_aio/views.py,sha256=8vMFw-8au9O0Hpf-79jvB47PwokCzm7P8UY0DDWpN5A,16786
+ninja_aio/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ninja_aio/helpers/api.py,sha256=kgHxYPfbV6kQbp8Z4qMwQtwFiFIcRAenxI9MDowGtis,20181
+ninja_aio/helpers/query.py,sha256=tE8RjXvSig-WB_0LRQ0LqoE4G_HMHsu0Na5QzTNIm6U,4262
+ninja_aio/schemas/__init__.py,sha256=iLBwHg0pmL9k_UkIui5Q8QIl_gO4fgxSv2JHxDzqnSI,549
+ninja_aio/schemas/api.py,sha256=-VwXhBRhmMsZLIAmWJ-P7tB5klxXS75eukjabeKKYsc,360
+ninja_aio/schemas/generics.py,sha256=frjJsKJMAdM_NdNKv-9ddZNGxYy5PNzjIRGtuycgr-w,112
+ninja_aio/schemas/helpers.py,sha256=rmE0D15lJg95Unv8PU44Hbf0VDTcErMCZZFG3D_znTo,2823
+django_ninja_aio_crud-2.0.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-2.0.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-2.0.0.dist-info/METADATA,sha256=FKp28V4DMReIrIFlseCRVJy5hZezdESq4ZC0nw3DikA,8672
+django_ninja_aio_crud-2.0.0.dist-info/RECORD,,

ninja_aio/__init__.py

@@ -1,6 +1,6 @@
 """Django Ninja AIO CRUD - Rest Framework"""
 
-__version__ = "1.0.5"
+__version__ = "2.0.0"
 
 from .api import NinjaAIO
 

ninja_aio/api.py

@@ -23,7 +23,6 @@ class NinjaAIO(NinjaAPI):
         docs_decorator=None,
         servers: list[dict[str, Any]] | None = None,
         urls_namespace: str | None = None,
-        csrf: bool = False,
         auth: Sequence[Any] | NOT_SET_TYPE = NOT_SET,
         throttle: BaseThrottle | list[BaseThrottle] | NOT_SET_TYPE = NOT_SET,
         default_router: Router | None = None,
@@ -39,7 +38,6 @@ class NinjaAIO(NinjaAPI):
             docs_decorator=docs_decorator,
             servers=servers,
             urls_namespace=urls_namespace,
-            csrf=csrf,
             auth=auth,
             throttle=throttle,
             default_router=default_router,

ninja_aio/auth.py

@@ -2,8 +2,6 @@ from joserfc import jwt, jwk, errors
 from django.http.request import HttpRequest
 from ninja.security.http import HttpBearer
 
-from .exceptions import AuthError
-
 
 class AsyncJwtBearer(HttpBearer):
     """
@@ -71,6 +69,7 @@ class AsyncJwtBearer(HttpBearer):
     Return Semantics:
         - authenticate -> user object (success) | False (failure)
     """
+
     jwt_public: jwk.RSAKey
     claims: dict[str, dict]
     algorithms: list[str] = ["RS256"]
@@ -96,13 +95,13 @@ class AsyncJwtBearer(HttpBearer):
         """
         try:
             self.dcd = jwt.decode(token, self.jwt_public, algorithms=self.algorithms)
-        except ValueError as exc:
+        except ValueError:
             # raise AuthError(", ".join(exc.args), 401)
             return False
 
         try:
             self.validate_claims(self.dcd.claims)
-        except errors.JoseError as exc:
+        except errors.JoseError:
             return False
 
         return await self.auth_handler(request)

ninja_aio/decorators.py

@@ -46,10 +46,12 @@ def aatomic(func):
           your async ORM / database backend.
         - Only use on async functions.
     """
+
     @wraps(func)
     async def wrapper(*args, **kwargs):
         async with AsyncAtomicContextManager():
             return await func(*args, **kwargs)
+
     return wrapper
 
 
@@ -117,6 +119,7 @@ def unique_view(self: object | str, plural: bool = False):
     - Ensure that the modified name does not conflict with other functions after decoration.
     - Use cautiously when decorators relying on original __name__ appear earlier in the chain.
     """
+
     def decorator(func):
         # Allow usage as unique_view(self_instance) or unique_view("model_name")
         if isinstance(self, str):
@@ -140,3 +143,76 @@ def unique_view(self: object | str, plural: bool = False):
         return func  # Return original function (no wrapper)
 
     return decorator
+
+
+def decorate_view(*decorators):
+    """
+    Compose and apply multiple decorators to a view (sync or async) without adding an extra wrapper.
+
+    This utility was introduced to support class-based patterns where Django Ninja’s
+    built-in `decorate_view` does not fit well. For APIs implemented with vanilla
+    Django Ninja (function-based style), you should continue using Django Ninja’s
+    native `decorate_view`.
+
+    Behavior:
+    - Applies decorators in the same order as Python’s stacking syntax:
+        @d1
+        @d2
+      is equivalent to: view = d1(d2(view))
+    - Supports both synchronous and asynchronous views.
+    - Ignores None values, enabling conditional decoration.
+    - Does not introduce an additional wrapper; composition depends on each
+      decorator for signature/metadata preservation (e.g., using functools.wraps).
+
+        *decorators: Decorator callables to apply to the target view. Any None values
+            are skipped.
+
+        Callable: A decorator that applies the provided decorators in Python stacking order.
+
+        Method usage in class-based patterns:
+
+    Args:
+        *decorators: Decorator callables to apply to the target view. Any None
+            values are skipped.
+
+    Returns:
+        A decorator that applies the provided decorators in Python stacking order.
+
+    Examples:
+        Basic usage:
+            class MyAPIViewSet(APIViewSet):
+                api = api
+                model = MyModel
+
+                def views(self):
+                    @self.router.get('some-endpoint/')
+                    @decorate_view(authenticate, log_request)
+                    async def some_view(request):
+                        ...
+        
+        Conditional decoration (skips None):
+            class MyAPIViewSet(APIViewSet):
+                api = api
+                model = MyModel
+                cache_dec = cache_page(60) if settings.ENABLE_CACHE else None
+                def views(self):
+                    @self.router.get('data/')
+                    @decorate_view(self.cache_dec, authenticate)
+                    async def data_view(request):
+                        ...
+
+    Notes:
+        - Each decorator is applied in the order provided, with the first decorator
+          wrapping the result of the second, and so on.
+        - Ensure that each decorator is compatible with the view’s sync/async nature.
+    """
+
+    def _decorator(view):
+        wrapped = view
+        for dec in reversed(decorators):
+            if dec is None:
+                continue
+            wrapped = dec(wrapped)
+        return wrapped
+
+    return _decorator

ninja_aio/helpers/__init__.py

@@ -1,3 +0,0 @@
-from .api import ManyToManyAPI
-
-__all__ = ["ManyToManyAPI"]

ninja_aio/helpers/api.py

@@ -6,6 +6,7 @@ from ninja import Path, Query
 from ninja.pagination import paginate
 from ninja_aio.decorators import unique_view
 from ninja_aio.models import ModelSerializer, ModelUtil
+from ninja_aio.schemas.helpers import ObjectsQuerySchema
 from ninja_aio.schemas import (
     GenericMessageSchema,
     M2MRelationSchema,
@@ -37,27 +38,34 @@ class ManyToManyAPI:
     Core behaviors:
         - Dynamically generates per-relation filter schemas for query parameters.
         - Supports custom per-relation query filtering handlers on the parent view set
-            via a `{related_name}_query_params_handler` coroutine.
+          via a `{related_name}_query_params_handler` coroutine for GET list filters.
+        - Supports custom per-relation object resolution for add/remove validation via
+          `{related_name}_query_handler(request, pk, instance)` used during POST to
+          resolve a single related object before mutation.
         - Validates requested add/remove primary keys, producing granular success and
-            error feedback.
+          error feedback.
         - Performs add/remove operations concurrently using asyncio.gather when both
-            types of operations are requested in the same call.
+          types of operations are requested in the same call.
 
     Attributes established at initialization:
         relations: list of M2MRelationSchema defining each relation.
         view_set: The parent APIViewSet instance from which router, pagination, model util,
-                            and path schema are derived.
+                  and path schema are derived.
         router: Ninja router used to register generated endpoints.
         pagination_class: Pagination class used for GET related endpoints.
         path_schema: Pydantic schema used to validate path parameters (e.g., primary key).
         related_model_util: A ModelUtil instance cloned from the parent view set to access
-                                                base object retrieval helpers.
+                            base object retrieval helpers.
         relations_filters_schemas: Mapping of related_name -> generated Pydantic filter schema.
 
     Generated endpoint naming conventions:
         GET   -> get_{base_model_name}_{relation_path}
         POST  -> manage_{base_model_name}_{relation_path}
 
+    Endpoint registration details:
+        - GET: registered at `{retrieve_path}{relation_path}` with pagination; accepts Query filters.
+        - POST: registered at `{retrieve_path}{relation_path}/` (trailing slash) to manage add/remove.
+
     All responses standardize success and error reporting for POST as:
     {
         "results": {"count": int, "details": [str, ...]},
@@ -65,25 +73,29 @@ class ManyToManyAPI:
     }
 
     Concurrency note:
-        Add and remove operations are executed concurrently when both lists are non-empty,
-        minimizing round-trip latency for bulk mutations.
+        - Add and remove operations are executed concurrently when both lists are non-empty,
+          minimizing round-trip latency for bulk mutations.
+        - Uses related_manager.aadd(...) and related_manager.aremove(...) inside asyncio.gather.
 
     Error semantics:
         - Missing related objects: reported individually.
         - Invalid operation context (e.g., removing objects not currently related or adding
-            objects already related) reported per primary key.
+          objects already related) reported per primary key.
         - Successful operations yield a corresponding success detail string per PK.
 
     Security / auth:
         - Each relation may optionally override auth via its schema; otherwise falls back
-            to a default configured on the instance (self.default_auth).
+          to a default configured on the instance (self.default_auth).
 
     Pagination:
         - Applied only to GET related endpoints via @paginate(self.pagination_class).
 
     Extensibility:
         - Provide custom query param handling by defining an async method on the parent
-            view set: `<related_name>_query_params_handler(self, queryset, filters_dict)`.
+          view set: `<related_name>_query_params_handler(self, queryset, filters_dict)`.
+        - Provide custom per-PK resolution for POST validation by defining an async method:
+          `<related_name>_query_handler(self, request, pk, instance)` returning a queryset,
+          from which .afirst() is used to resolve the single target object.
         - Customize relation filtering schema via each relation's `filters` definition.
 
     -----------------------------------------------------------------------
@@ -113,9 +125,9 @@ class ManyToManyAPI:
 
     -----------------------------------------------------------------------
 
-    _get_query_handler(related_name)
-    Retrieve an optional per-relation query handler coroutine from the parent view set.
-    Naming convention: `<related_name>_query_params_handler`.
+    _get_query_params_handler(related_name)
+    Retrieve an optional per-relation query handler from the parent view set for GET list filters.
+    Naming convention: `<related_name}_query_params_handler`.
 
     Parameters:
         related_name (str): The relation's attribute name on the base model.
@@ -125,16 +137,32 @@ class ManyToManyAPI:
 
     -----------------------------------------------------------------------
 
-    _check_m2m_objs(request, objs_pks, model, related_manager, remove=False)
+    _get_query_handler(related_name)
+    Retrieve an optional per-relation single-object resolution handler from the parent view set
+    used during POST add/remove validation. If present, it receives `(request, pk, instance)` and
+    should return a queryset from which `.afirst()` will resolve the target object.
+
+    Parameters:
+        related_name (str): The relation's attribute name on the base model.
+
+    Returns:
+        Coroutine | None: Handler to resolve a single related object by pk.
+
+    -----------------------------------------------------------------------
+
+    _check_m2m_objs(request, objs_pks, related_model, related_manager, related_name, instance, remove=False)
     Validate requested primary keys for add/remove operations against the current
     relation state. Performs existence checks and logical consistency (e.g., prevents
-    adding already-related objects or removing non-related objects).
+    adding already-related objects or removing non-related objects). Uses `_get_query_handler`
+    when available; otherwise falls back to ModelUtil(...).get_objects(...) to resolve by pk.
 
     Parameters:
         request (HttpRequest): Incoming request context (passed to ModelUtil for access control).
         objs_pks (list): List of primary keys to add or remove.
-        model (ModelSerializer | Model): Model class or serializer used to resolve objects.
+        related_model (ModelSerializer | Model): Model class or serializer used to resolve objects.
         related_manager (QuerySet): Related manager for the base object's M2M field.
+        related_name (str): M2M field name on the base object.
+        instance (ModelSerializer | Model): Base object instance (owner of the relation).
         remove (bool): If True, treat operation as removal validation.
 
     Returns:
@@ -149,7 +177,7 @@ class ManyToManyAPI:
 
     -----------------------------------------------------------------------
 
-    _collect_m2m(request, pks, model, related_manager, remove=False)
+    _collect_m2m(request, pks, model, related_manager, related_name, instance, remove=False)
     Wrapper around _check_m2m_objs that short-circuits on empty PK lists.
 
     Parameters:
@@ -157,6 +185,8 @@ class ManyToManyAPI:
         pks (list): Primary keys proposed for mutation.
         model (ModelSerializer | Model)
         related_manager (QuerySet)
+        related_name (str)
+        instance (ModelSerializer | Model)
         remove (bool): Operation type flag.
 
     Returns:
@@ -164,38 +194,30 @@ class ManyToManyAPI:
 
     -----------------------------------------------------------------------
 
+    _register_get_relation_view(...)
+    Registers the GET endpoint for listing related objects. Applies optional
+    query params handler for filtering. Uses pagination and serializes via `list_read_s`.
+
+    -----------------------------------------------------------------------
+
+    _register_manage_relation_view(...)
+    Registers the POST endpoint for adding/removing related objects. Validates via
+    `_collect_m2m` and executes mutations concurrently using `aadd`/`aremove` with
+    `asyncio.gather`. Aggregates per-PK results and errors into a standardized payload.
+
+    -----------------------------------------------------------------------
+
     _build_views(relation)
     Dynamically define and register the GET and/or POST endpoints for a single M2M
     relation based on the relation's schema flags (get/add/remove). Builds filter
     schemas, resolves path fragments, and binds handlers to the router with unique
     operation IDs.
 
-    Parameters:
-        relation (M2MRelationSchema): Declarative specification for one M2M relation.
-
-    Side effects:
-        - Registers endpoints on self.router.
-        - Creates closures (get_related / manage_related) capturing relation context.
-
-    GET endpoint behavior:
-        - Retrieves base object via related_model_util.
-        - Fetches all related objects; applies optional query handler and filters.
-        - Serializes each related object with rel_util.read_s.
-
-    POST endpoint behavior:
-        - Parses add/remove PK lists.
-        - Validates objects via _collect_m2m.
-        - Performs asynchronous add/remove operations using aadd / aremove.
-        - Aggregates results and errors into standardized response payload.
-
     -----------------------------------------------------------------------
 
     _add_views()
     Iterates over all declared relations and invokes _build_views to attach endpoints.
 
-    Side effects:
-        - Populates router with all required M2M endpoints.
-
     -----------------------------------------------------------------------
 
     Usage Example (conceptual):
@@ -240,39 +262,56 @@ class ManyToManyAPI:
             for data in self.relations
         }
 
-    def _get_query_handler(self, related_name: str) -> Coroutine | None:
+    def _get_query_params_handler(self, related_name: str) -> Coroutine | None:
         return getattr(self.view_set, f"{related_name}_query_params_handler", None)
 
+    def _get_query_handler(self, related_name: str) -> Coroutine | None:
+        return getattr(self.view_set, f"{related_name}_query_handler", None)
+
     async def _check_m2m_objs(
         self,
         request: HttpRequest,
         objs_pks: list,
-        model: ModelSerializer | Model,
+        related_model: ModelSerializer | Model,
         related_manager: QuerySet,
+        related_name: str,
+        instance: ModelSerializer | Model,
         remove: bool = False,
     ):
         """
         Validate requested add/remove pk list for M2M operations.
         Returns (errors, details, objects_to_process).
+        Uses per-PK query handler if available, else falls back to ModelUtil lookup by pk.
         """
         errors, objs_detail, objs = [], [], []
         rel_objs = [rel_obj async for rel_obj in related_manager.select_related().all()]
-        rel_model_name = model._meta.verbose_name.capitalize()
+        rel_model_name = related_model._meta.verbose_name.capitalize()
         for obj_pk in objs_pks:
-            rel_obj = await (
-                await ModelUtil(model).get_object(request, filters={"pk": obj_pk})
-            ).afirst()
+            if query_handler := self._get_query_handler(related_name):
+                rel_obj = await (
+                    await query_handler(
+                        request,
+                        obj_pk,
+                        instance,
+                    )
+                ).afirst()
+            else:
+                rel_obj = await (
+                    await ModelUtil(related_model).get_objects(
+                        request, query_data=ObjectsQuerySchema(filters={"pk": obj_pk})
+                    )
+                ).afirst()
             if rel_obj is None:
                 errors.append(f"{rel_model_name} with pk {obj_pk} not found.")
                 continue
             if remove ^ (rel_obj in rel_objs):
                 errors.append(
-                    f"{rel_model_name} with id {obj_pk} is {'not ' if remove else ''}in {self.related_model_util.model_name}"
+                    f"{rel_model_name} with pk {obj_pk} is {'not ' if remove else ''}in {self.related_model_util.model_name}"
                 )
                 continue
             objs.append(rel_obj)
             objs_detail.append(
-                f"{rel_model_name} with id {obj_pk} successfully {'removed' if remove else 'added'}"
+                f"{rel_model_name} with pk {obj_pk} successfully {'removed' if remove else 'added'}"
             )
         return errors, objs_detail, objs
 
@@ -280,14 +319,22 @@ class ManyToManyAPI:
         self,
         request: HttpRequest,
         pks: list,
-        model: ModelSerializer | Model,
+        reletad_model: ModelSerializer | Model,
         related_manager: QuerySet,
-        remove=False,
+        related_name: str,
+        instance: ModelSerializer | Model,
+        remove: bool = False,
     ):
         if not pks:
             return ([], [], [])
         return await self._check_m2m_objs(
-            request, pks, model, related_manager, remove=remove
+            request,
+            pks,
+            reletad_model,
+            related_manager,
+            related_name,
+            instance,
+            remove=remove,
         )
 
     def _register_get_relation_view(
@@ -323,14 +370,14 @@ class ManyToManyAPI:
             related_manager = getattr(obj, related_name)
             related_qs = related_manager.all()
 
-            query_handler = self._get_query_handler(related_name)
+            query_handler = self._get_query_params_handler(related_name)
             if filters is not None and query_handler:
-                related_qs = await query_handler(related_qs, filters.model_dump())
+                if asyncio.iscoroutinefunction(query_handler):
+                    related_qs = await query_handler(related_qs, filters.model_dump())
+                else:
+                    related_qs = query_handler(related_qs, filters.model_dump())
 
-            return [
-                await rel_util.read_s(request, rel_obj, related_schema)
-                async for rel_obj in related_qs
-            ]
+            return await rel_util.list_read_s(related_schema, request, related_qs)
 
     def _resolve_action_schema(self, add: bool, remove: bool):
         return self.views_action_map[(add, remove)]
@@ -338,7 +385,7 @@ class ManyToManyAPI:
     def _register_manage_relation_view(
         self,
         *,
-        model,
+        related_model: ModelSerializer | Model,
         related_name: str,
         m2m_auth,
         rel_util: ModelUtil,
@@ -375,10 +422,21 @@ class ManyToManyAPI:
             remove_pks = getattr(data, "remove", []) if m2m_remove else []
 
             add_errors, add_details, add_objs = await self._collect_m2m(
-                request, add_pks, model, related_manager
+                request,
+                add_pks,
+                related_model,
+                related_manager,
+                related_name,
+                obj,
             )
             remove_errors, remove_details, remove_objs = await self._collect_m2m(
-                request, remove_pks, model, related_manager, remove=True
+                request,
+                remove_pks,
+                related_model,
+                related_manager,
+                related_name,
+                obj,
+                remove=True,
             )
 
             tasks = []
@@ -418,7 +476,7 @@ class ManyToManyAPI:
 
         if m2m_add or m2m_remove:
             self._register_manage_relation_view(
-                model=model,
+                related_model=model,
                 related_name=related_name,
                 m2m_auth=m2m_auth,
                 rel_util=rel_util,

ninja_aio/helpers/query.py

@@ -0,0 +1,103 @@
+from ninja_aio.types import ModelSerializerMeta
+from ninja_aio.schemas.helpers import (
+    ModelQuerySetSchema,
+    QueryUtilBaseScopesSchema,
+    ModelQuerySetExtraSchema,
+)
+
+
+class ScopeNamespace:
+    def __init__(self, **scopes):
+        for key, value in scopes.items():
+            setattr(self, key, value)
+
+    def __iter__(self):
+        return iter(self.__dict__.values())
+
+
+class QueryUtil:
+    """
+    Helper class to manage queryset optimizations based on predefined scopes.
+    Attributes:
+        model (ModelSerializerMeta): The model serializer meta to which this utility is attached.
+        SCOPES (ScopeNamespace): An enumeration-like object containing available scopes.
+        read_config (ModelQuerySetSchema): Configuration for the 'read' scope.
+        queryset_request_config (ModelQuerySetSchema): Configuration for the 'queryset_request' scope
+        extra_configs (dict): Additional configurations for custom scopes.
+    Methods:
+        apply_queryset_optimizations(queryset, scope): Applies select_related and prefetch_related
+            optimizations to the given queryset based on the specified scope.
+
+    Example:
+        query_util = QueryUtil(MyModelSerializer) or MyModel.query_util
+        qs = MyModel.objects.all()
+        optimized_qs = query_util.apply_queryset_optimizations(qs, query_util.SCOPES.READ)
+
+        # Applying optimizations for a custom scope
+        class MyModelSerializer(ModelSerializer):
+            class QuerySet:
+                extras = [
+                    ModelQuerySetExtraSchema(
+                        scope="custom_scope",
+                        select_related=["custom_fk_field"],
+                        prefetch_related=["custom_m2m_field"],
+                    )
+                ]
+        query_util = MyModelSerializer.query_util
+        qs = MyModelSerializer.objects.all()
+        optimized_qs_custom = query_util.apply_queryset_optimizations(qs, "custom_scope")
+    """
+
+    SCOPES: QueryUtilBaseScopesSchema
+
+    def __init__(self, model: ModelSerializerMeta):
+        self.model = model
+        self._configuration = getattr(self.model, "QuerySet", None)
+        self._extra_configuration: list[ModelQuerySetExtraSchema] = getattr(
+            self._configuration, "extras", []
+        )
+        self._BASE_SCOPES = QueryUtilBaseScopesSchema().model_dump()
+        self.SCOPES = ScopeNamespace(
+            **self._BASE_SCOPES,
+            **{extra.scope: extra.scope for extra in self._extra_configuration},
+        )
+        self.extra_configs = {extra.scope: extra for extra in self._extra_configuration}
+        self._configs = {
+            **{scope: self._get_config(scope) for scope in self._BASE_SCOPES.values()},
+            **self.extra_configs,
+        }
+        self.read_config: ModelQuerySetSchema = self._configs.get(self.SCOPES.READ, ModelQuerySetSchema())
+        self.queryset_request_config: ModelQuerySetSchema = self._configs.get(
+            self.SCOPES.QUERYSET_REQUEST, ModelQuerySetSchema()
+        )
+
+    def _get_config(self, conf_name: str) -> ModelQuerySetSchema:
+        """Helper method to retrieve configuration attributes."""
+        return getattr(self._configuration, conf_name, ModelQuerySetSchema())
+
+    def apply_queryset_optimizations(self, queryset, scope: str):
+        """
+        Apply select_related and prefetch_related optimizations to the queryset
+        according to the specified scope.
+
+        Args:
+            queryset (QuerySet): The Django queryset to optimize.
+            scope (str): The scope to apply. Must be in self.SCOPES.
+
+        Returns:
+            QuerySet: The optimized queryset.
+
+        Raises:
+            ValueError: If the given scope is not supported.
+        """
+        if scope not in self._configs:
+            valid_scopes = list(self._configs.keys())
+            raise ValueError(
+                f"Invalid scope '{scope}' for QueryUtil. Supported scopes: {valid_scopes}"
+            )
+        config = self._configs.get(scope, ModelQuerySetSchema())
+        if config.select_related:
+            queryset = queryset.select_related(*config.select_related)
+        if config.prefetch_related:
+            queryset = queryset.prefetch_related(*config.prefetch_related)
+        return queryset