django-ninja-aio-crud 2.8.0__py3-none-any.whl → 2.10.0__py3-none-any.whl

{django_ninja_aio_crud-2.8.0.dist-info → django_ninja_aio_crud-2.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 2.8.0
+Version: 2.10.0
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
 Requires-Python: >=3.10, <3.15

{django_ninja_aio_crud-2.8.0.dist-info → django_ninja_aio_crud-2.10.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-ninja_aio/__init__.py,sha256=s2uQ_vbFbWOcD6laB1hG40Mv67xvXbSehMTUbkWCcrA,119
+ninja_aio/__init__.py,sha256=FZKyvJwguGusKjYpVUXSYB45Fssox9yEFHg47WX0BaE,120
 ninja_aio/api.py,sha256=tuC7vdvn7s1GkCnSFy9Kn1zv0glZfYptRQVvo8ZRtGQ,2429
 ninja_aio/auth.py,sha256=4sWdFPjKiQgUL1d_CSGDblVjnY5ptP6LQha6XXdluJA,9157
 ninja_aio/exceptions.py,sha256=_3xFqfFCOfrrMhSA0xbMqgXy8R0UQjhXaExrFvaDAjY,3891
@@ -12,18 +12,18 @@ ninja_aio/factory/__init__.py,sha256=IdH2z1ZZpv_IqonaDfVo7IsMzkgop6lHqz42RphUYBU
 ninja_aio/factory/operations.py,sha256=OgWGqq4WJ4arSQrH9FGAby9kx-HTdS7MOITxHdYMk18,12051
 ninja_aio/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ninja_aio/helpers/api.py,sha256=2beyexep-ehgaA_1bV5Yuh3zRDVcRCMkrW94nmfDWEA,20819
-ninja_aio/helpers/query.py,sha256=lzaH-htswoJVRT-W736HGMkpMba1VmN98TBLv5cZx9Q,4549
+ninja_aio/helpers/query.py,sha256=NMGkS_v-ZVYKNtf1XohEUzfwca52Eq5FTcQ5lehHjus,4682
 ninja_aio/models/__init__.py,sha256=L3UQnQAlKoI3F7jinadL-Nn55hkPvnSRPYW0JtnbWFo,114
-ninja_aio/models/serializers.py,sha256=uviKndPf9HRySup-0t_nULJs-vDLCeGFLtkkQGZvi2E,38142
-ninja_aio/models/utils.py,sha256=P-YfbVyzUfxm_s1BrgSd6Zs0HIGdZ79PU1qM0Ud9-Xs,30492
-ninja_aio/schemas/__init__.py,sha256=iLBwHg0pmL9k_UkIui5Q8QIl_gO4fgxSv2JHxDzqnSI,549
-ninja_aio/schemas/api.py,sha256=-VwXhBRhmMsZLIAmWJ-P7tB5klxXS75eukjabeKKYsc,360
+ninja_aio/models/serializers.py,sha256=I7pUz_vl0FElaVsrGaogT_Lj9T4uaNG7UDMGf5VMwW4,38468
+ninja_aio/models/utils.py,sha256=dxzwqE25b0lFZ--30XxeIJB-y4xbIDtc624vGaa_wOg,32885
+ninja_aio/schemas/__init__.py,sha256=_a092xZezlLc9QWCPWrybeklByCs39jbvf33zwdnrys,603
+ninja_aio/schemas/api.py,sha256=InzZgIFU4Zxkgj9u_zZzAMYs_vdaPD5eu12gG7xAFoQ,1047
 ninja_aio/schemas/generics.py,sha256=frjJsKJMAdM_NdNKv-9ddZNGxYy5PNzjIRGtuycgr-w,112
-ninja_aio/schemas/helpers.py,sha256=KkbDgT7DwvdeBHZ__wurQQ9A1AIy-toCIL9dCzkTFhM,8350
+ninja_aio/schemas/helpers.py,sha256=Vti5BfHWpxaJXj_ixZBJb34VRwhHODrlVjRlIuHh_ug,8428
 ninja_aio/views/__init__.py,sha256=DEzjWA6y3WF0V10nNF8eEurLNEodgxKzyFd09AqVp3s,148
-ninja_aio/views/api.py,sha256=l7z-Cg_BUPRi3TAGpO2EppVA2tUAWUftQAn_qOn6XlM,21963
-ninja_aio/views/mixins.py,sha256=Jh6BG8Cs823nurVlODlzCquTxKrLH7Pmo5udPqUGZek,11378
-django_ninja_aio_crud-2.8.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
-django_ninja_aio_crud-2.8.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-django_ninja_aio_crud-2.8.0.dist-info/METADATA,sha256=k3VWPUTlkXEe0tZRt7cWWtdA_5i_31gjkUM3t402nBI,9963
-django_ninja_aio_crud-2.8.0.dist-info/RECORD,,
+ninja_aio/views/api.py,sha256=CW74JB1tsdWfv3Y3x4K9o8yXsrMxCKWZ4QalhqJGan8,22072
+ninja_aio/views/mixins.py,sha256=01kEGMmpD3eTd8R5mX8sNr7KoizOfN0wvbV5y180IdE,13835
+django_ninja_aio_crud-2.10.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-2.10.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-2.10.0.dist-info/METADATA,sha256=-cSLMUj-s7djNL2RxRhLNkErv0yM49NK8CA8-zp-4zw,9964
+django_ninja_aio_crud-2.10.0.dist-info/RECORD,,

ninja_aio/__init__.py

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

ninja_aio/helpers/query.py

@@ -75,6 +75,9 @@ class QueryUtil:
         self.queryset_request_config: ModelQuerySetSchema = self._configs.get(
             self.SCOPES.QUERYSET_REQUEST, ModelQuerySetSchema()
         )
+        self.detail_config: ModelQuerySetSchema = self._configs.get(
+            self.SCOPES.DETAIL, ModelQuerySetSchema()
+        )
 
     def _get_config(self, conf_name: str) -> ModelQuerySetSchema:
         """Helper method to retrieve configuration attributes."""

ninja_aio/models/serializers.py

@@ -61,6 +61,7 @@ class BaseSerializer:
         """
 
         read = ModelQuerySetSchema()
+        detail = ModelQuerySetSchema()
         queryset_request = ModelQuerySetSchema()
         extras: list[ModelQuerySetExtraSchema] = []
 
@@ -325,14 +326,18 @@ class BaseSerializer:
         ]
 
     @classmethod
-    def get_excluded_fields(cls, s_type: type[S_TYPES]):
+    def get_excluded_fields(cls, s_type: S_TYPES):
         """Return excluded field names for the serializer type."""
         return cls._get_fields(s_type, "excludes")
 
     @classmethod
-    def get_fields(cls, s_type: type[S_TYPES]):
+    def get_fields(cls, s_type: S_TYPES):
         """Return explicit declared fields for the serializer type."""
-        return cls._get_fields(s_type, "fields")
+        fields = cls._get_fields(s_type, "fields")
+        # Detail schema falls back to read fields if none declared
+        if not fields and s_type == "detail":
+            return cls._get_fields("read", "fields")
+        return fields
 
     @classmethod
     def is_custom(cls, field: str) -> bool:
@@ -406,7 +411,11 @@ class BaseSerializer:
         """Check if field is a reverse relation (M2M, reverse FK, reverse O2O)."""
         return isinstance(
             field_obj,
-            (ManyToManyDescriptor, ReverseManyToOneDescriptor, ReverseOneToOneDescriptor),
+            (
+                ManyToManyDescriptor,
+                ReverseManyToOneDescriptor,
+                ReverseOneToOneDescriptor,
+            ),
         )
 
     @classmethod
@@ -419,9 +428,8 @@ class BaseSerializer:
     @classmethod
     def _warn_missing_relation_serializer(cls, field_name: str, model) -> None:
         """Emit warning for reverse relations without explicit serializer mapping."""
-        if (
-            not isinstance(model, ModelSerializerMeta)
-            and not getattr(settings, "NINJA_AIO_TESTING", False)
+        if not isinstance(model, ModelSerializerMeta) and not getattr(
+            settings, "NINJA_AIO_TESTING", False
         ):
             warnings.warn(
                 f"{cls.__name__}: reverse relation '{field_name}' is listed in read fields "
@@ -469,7 +477,9 @@ class BaseSerializer:
             tuple: (fields, reverse_rels, excludes, customs_with_forward_rels, optionals)
         """
         if schema_type not in ("Out", "Detail"):
-            raise ValueError("get_schema_out_data only supports 'Out' or 'Detail' types")
+            raise ValueError(
+                "get_schema_out_data only supports 'Out' or 'Detail' types"
+            )
 
         fields_type = "read" if schema_type == "Out" else "detail"
         model = cls._get_model()
@@ -602,7 +612,7 @@ class BaseSerializer:
     @classmethod
     def generate_detail_s(cls, depth: int = 1) -> Schema:
         """Generate detail (single object Out) schema."""
-        return cls._generate_model_schema("Detail", depth)
+        return cls._generate_model_schema("Detail", depth) or cls.generate_read_s(depth)
 
     @classmethod
     def generate_create_s(cls) -> Schema:

ninja_aio/models/utils.py

@@ -1,6 +1,6 @@
 import asyncio
 import base64
-from typing import Any
+from typing import Any, Literal
 
 from ninja import Schema
 from ninja.orm import fields
@@ -167,9 +167,19 @@ class ModelUtil:
         list[str]
             Explicit read fields if ModelSerializerMeta, otherwise all model fields.
         """
-        if isinstance(self.model, ModelSerializerMeta):
-            return self.model.get_fields("read")
-        return self.model_fields
+        return self._get_serializable_field_names("read")
+
+    @property
+    def serializable_detail_fields(self):
+        """
+        List of fields considered serializable for detail operations.
+
+        Returns
+        -------
+        list[str]
+            Explicit detail fields if ModelSerializerMeta, otherwise all model fields.
+        """
+        return self._get_serializable_field_names("detail")
 
     @property
     def model_fields(self):
@@ -235,12 +245,29 @@ class ModelUtil:
         """
         return self.model_verbose_name_plural.replace(" ", "")
 
+    def _get_serializable_field_names(
+        self, fields_type: Literal["read", "detail"]
+    ) -> list[str]:
+        """
+        Get serializable field names for the model.
+
+        Returns
+        -------
+        list[str]
+            List of serializable field names.
+        """
+        if isinstance(self.model, ModelSerializerMeta):
+            return self.model.get_fields(fields_type)
+        if self.with_serializer:
+            return self.serializer_class.get_fields(fields_type)
+        return self.model_fields
+
     async def _get_base_queryset(
         self,
         request: HttpRequest,
         query_data: QuerySchema,
         with_qs_request: bool,
-        is_for_read: bool,
+        is_for: Literal["read", "detail"] | None = None,
     ) -> models.QuerySet[type["ModelSerializer"] | models.Model]:
         """
         Build base queryset with optimizations and filters.
@@ -253,8 +280,9 @@ class ModelUtil:
             Query configuration with filters and optimizations.
         with_qs_request : bool
             Whether to apply queryset_request hook.
-        is_for_read : bool
-            Whether this is a read operation.
+        is_for : Literal["read", "detail"] | None
+            Purpose of the query, determines which serializable fields to use.
+            If None, only query_data optimizations are applied.
 
         Returns
         -------
@@ -269,7 +297,7 @@ class ModelUtil:
         )
 
         # Apply query optimizations
-        obj_qs = self._apply_query_optimizations(obj_qs, query_data, is_for_read)
+        obj_qs = self._apply_query_optimizations(obj_qs, query_data, is_for)
 
         # Apply queryset_request hook if available
         if isinstance(self.model, ModelSerializerMeta) and with_qs_request:
@@ -286,7 +314,7 @@ class ModelUtil:
         request: HttpRequest,
         query_data: ObjectsQuerySchema = None,
         with_qs_request=True,
-        is_for_read: bool = False,
+        is_for: Literal["read", "detail"] | None = None,
     ) -> models.QuerySet[type["ModelSerializer"] | models.Model]:
         """
         Retrieve a queryset with optimized database queries.
@@ -305,9 +333,9 @@ class ModelUtil:
         with_qs_request : bool, optional
             Whether to apply the model's queryset_request hook if available.
             Defaults to True.
-        is_for_read : bool, optional
-            Flag indicating if the query is for read operations, which may affect
-            query optimization strategies. Defaults to False.
+        is_for : Literal["read", "detail"] | None, optional
+            Purpose of the query, determines which serializable fields to use.
+            If None, only query_data optimizations are applied.
 
         Returns
         -------
@@ -323,7 +351,7 @@ class ModelUtil:
             query_data = ObjectsQuerySchema()
 
         return await self._get_base_queryset(
-            request, query_data, with_qs_request, is_for_read
+            request, query_data, with_qs_request, is_for
         )
 
     async def get_object(
@@ -332,7 +360,7 @@ class ModelUtil:
         pk: int | str = None,
         query_data: ObjectQuerySchema = None,
         with_qs_request=True,
-        is_for_read: bool = False,
+        is_for: Literal["read", "detail"] | None = None,
     ) -> type["ModelSerializer"] | models.Model:
         """
         Retrieve a single object with optimized database queries.
@@ -353,9 +381,9 @@ class ModelUtil:
         with_qs_request : bool, optional
             Whether to apply the model's queryset_request hook if available.
             Defaults to True.
-        is_for_read : bool, optional
-            Flag indicating if the query is for read operations, which may affect
-            query optimization strategies. Defaults to False.
+        is_for : Literal["read", "detail"] | None, optional
+            Purpose of the query, determines which serializable fields to use.
+            If None, only query_data optimizations are applied.
 
         Returns
         -------
@@ -385,7 +413,7 @@ class ModelUtil:
         # Build lookup query and get optimized queryset
         get_q = self._build_lookup_query(pk, query_data.getters)
         obj_qs = await self._get_base_queryset(
-            request, query_data, with_qs_request, is_for_read
+            request, query_data, with_qs_request, is_for
         )
 
         # Perform lookup
@@ -421,7 +449,7 @@ class ModelUtil:
         self,
         queryset: models.QuerySet,
         query_data: QuerySchema,
-        is_for_read: bool,
+        is_for: Literal["read", "detail"] | None = None,
     ) -> models.QuerySet:
         """
         Apply select_related and prefetch_related optimizations to queryset.
@@ -432,8 +460,9 @@ class ModelUtil:
             Base queryset to optimize.
         query_data : ModelQuerySchema
             Query configuration with select_related/prefetch_related lists.
-        is_for_read : bool
-            Whether to include model-level relation discovery.
+        is_for : Literal["read", "detail"] | None
+            Purpose of the query, determines which serializable fields to use.
+            If None, only query_data optimizations are applied.
 
         Returns
         -------
@@ -441,13 +470,13 @@ class ModelUtil:
             Optimized queryset.
         """
         select_related = (
-            query_data.select_related + self.get_select_relateds()
-            if is_for_read
+            query_data.select_related + self.get_select_relateds(is_for)
+            if is_for
             else query_data.select_related
         )
         prefetch_related = (
-            query_data.prefetch_related + self.get_reverse_relations()
-            if is_for_read
+            query_data.prefetch_related + self.get_reverse_relations(is_for)
+            if is_for
             else query_data.prefetch_related
         )
 
@@ -458,36 +487,52 @@ class ModelUtil:
 
         return queryset
 
-    def _get_read_optimizations(self) -> ModelQuerySetSchema:
+    def _get_read_optimizations(
+        self, is_for: Literal["read", "detail"] = "read"
+    ) -> ModelQuerySetSchema:
         """
         Retrieve read optimizations from model or serializer class.
 
+        When is_for="detail" and no detail config exists, falls back to read config.
+
         Returns
         -------
         ModelQuerySetSchema
             Read optimization configuration.
         """
         if isinstance(self.model, ModelSerializerMeta):
-            return getattr(self.model.QuerySet, "read", ModelQuerySetSchema())
+            result = getattr(self.model.QuerySet, is_for, None)
+            if result is None and is_for == "detail":
+                result = getattr(self.model.QuerySet, "read", None)
+            return result or ModelQuerySetSchema()
         if self.with_serializer:
-            return getattr(
-                self.serializer_class.QuerySet, "read", ModelQuerySetSchema()
-            )
+            result = getattr(self.serializer_class.QuerySet, is_for, None)
+            if result is None and is_for == "detail":
+                result = getattr(self.serializer_class.QuerySet, "read", None)
+            return result or ModelQuerySetSchema()
         return ModelQuerySetSchema()
 
-    def get_reverse_relations(self) -> list[str]:
+    def get_reverse_relations(
+        self, is_for: Literal["read", "detail"] = "read"
+    ) -> list[str]:
         """
         Discover reverse relation names for safe prefetching.
 
+        Parameters
+        ----------
+        is_for : Literal["read", "detail"]
+            Purpose of the query, determines which serializable fields to use.
+
         Returns
         -------
         list[str]
             Relation attribute names.
         """
-        reverse_rels = self._get_read_optimizations().prefetch_related.copy()
+        reverse_rels = self._get_read_optimizations(is_for).prefetch_related.copy()
         if reverse_rels:
             return reverse_rels
-        for f in self.serializable_fields:
+        serializable_fields = self._get_serializable_field_names(is_for)
+        for f in serializable_fields:
             field_obj = getattr(self.model, f)
             if isinstance(field_obj, ManyToManyDescriptor):
                 reverse_rels.append(f)
@@ -499,24 +544,32 @@ class ModelUtil:
                 reverse_rels.append(field_obj.related.name)
         return reverse_rels
 
-    def get_select_relateds(self) -> list[str]:
+    def get_select_relateds(
+        self, is_for: Literal["read", "detail"] = "read"
+    ) -> list[str]:
         """
         Discover forward relation names for safe select_related.
 
+        Parameters
+        ----------
+        is_for : Literal["read", "detail"]
+            Purpose of the query, determines which serializable fields to use.
+
         Returns
         -------
         list[str]
             Relation attribute names.
         """
-        select_rels = self._get_read_optimizations().select_related.copy()
+        select_rels = self._get_read_optimizations(is_for).select_related.copy()
         if select_rels:
             return select_rels
-        for f in self.serializable_fields:
+        serializable_fields = self._get_serializable_field_names(is_for)
+        for f in serializable_fields:
             field_obj = getattr(self.model, f)
-            if isinstance(field_obj, ForwardManyToOneDescriptor):
+            if isinstance(field_obj, ForwardOneToOneDescriptor):
                 select_rels.append(f)
                 continue
-            if isinstance(field_obj, ForwardOneToOneDescriptor):
+            if isinstance(field_obj, ForwardManyToOneDescriptor):
                 select_rels.append(f)
         return select_rels
 
@@ -577,17 +630,15 @@ class ModelUtil:
         request: HttpRequest,
         query_data: QuerySchema,
         schema: Schema,
-        is_for_read: bool,
+        is_for: Literal["read", "detail"] | None = None,
     ):
         """Handle different query modes (filters vs getters)."""
         if hasattr(query_data, "filters") and query_data.filters:
-            return await self._serialize_queryset(
-                request, query_data, schema, is_for_read
-            )
+            return await self._serialize_queryset(request, query_data, schema, is_for)
 
         if hasattr(query_data, "getters") and query_data.getters:
             return await self._serialize_single_object(
-                request, query_data, schema, is_for_read
+                request, query_data, schema, is_for
             )
 
         raise SerializeError(
@@ -599,12 +650,10 @@ class ModelUtil:
         request: HttpRequest,
         query_data: QuerySchema,
         schema: Schema,
-        is_for_read: bool,
+        is_for: Literal["read", "detail"] | None = None,
     ):
         """Serialize a queryset of objects."""
-        objs = await self.get_objects(
-            request, query_data=query_data, is_for_read=is_for_read
-        )
+        objs = await self.get_objects(request, query_data=query_data, is_for=is_for)
         return [await self._bump_object_from_schema(obj, schema) async for obj in objs]
 
     async def _serialize_single_object(
@@ -612,12 +661,10 @@ class ModelUtil:
         request: HttpRequest,
         query_data: QuerySchema,
         obj_schema: Schema,
-        is_for_read: bool,
+        is_for: Literal["read", "detail"] | None = None,
     ):
         """Serialize a single object."""
-        obj = await self.get_object(
-            request, query_data=query_data, is_for_read=is_for_read
-        )
+        obj = await self.get_object(request, query_data=query_data, is_for=is_for)
         return await self._bump_object_from_schema(obj, obj_schema)
 
     async def parse_input_data(self, request: HttpRequest, data: Schema):
@@ -649,7 +696,9 @@ class ModelUtil:
         """
         payload = data.model_dump(mode="json")
 
-        is_serializer = isinstance(self.model, ModelSerializerMeta) or self.with_serializer
+        is_serializer = (
+            isinstance(self.model, ModelSerializerMeta) or self.with_serializer
+        )
         serializer = self.serializer if self.with_serializer else self.model
 
         # Collect custom and optional fields (only if ModelSerializerMeta)
@@ -732,7 +781,7 @@ class ModelUtil:
         | type["ModelSerializer"]
         | models.Model = None,
         query_data: QuerySchema = None,
-        is_for_read: bool = False,
+        is_for: Literal["read", "detail"] | None = None,
     ):
         """
         Internal serialization method handling both single instances and querysets.
@@ -747,8 +796,8 @@ class ModelUtil:
             Instance(s) to serialize. If None, fetches based on query_data.
         query_data : QuerySchema, optional
             Query parameters for fetching objects when instance is None.
-        is_for_read : bool, optional
-            Whether to apply read-specific query optimizations.
+        is_for : Literal["read", "detail"] | None, optional
+            Purpose of the query, determines which serializable fields to use.
 
         Returns
         -------
@@ -772,7 +821,7 @@ class ModelUtil:
             return await self._bump_object_from_schema(instance, schema)
 
         self._validate_read_params(request, query_data)
-        return await self._handle_query_mode(request, query_data, schema, is_for_read)
+        return await self._handle_query_mode(request, query_data, schema, is_for)
 
     async def read_s(
         self,
@@ -780,7 +829,7 @@ class ModelUtil:
         request: HttpRequest = None,
         instance: type["ModelSerializer"] = None,
         query_data: ObjectQuerySchema = None,
-        is_for_read: bool = False,
+        is_for: Literal["read", "detail"] | None = None,
     ) -> dict:
         """
         Serialize a single model instance or fetch and serialize using query parameters.
@@ -799,8 +848,9 @@ class ModelUtil:
         query_data : ObjectQuerySchema, optional
             Query parameters with getters for single object lookup.
             Required when instance is None.
-        is_for_read : bool, optional
-            Whether to apply read-specific query optimizations. Defaults to False.
+        is_for : Literal["read", "detail"] | None, optional
+            Purpose of the query, determines which serializable fields to use.
+            Defaults to None.
 
         Returns
         -------
@@ -820,14 +870,14 @@ class ModelUtil:
         -----
         - Uses Pydantic's from_orm() with mode="json" for serialization
         - When instance is provided, request and query_data are ignored
-        - Query optimizations applied when is_for_read=True
+        - Query optimizations applied when is_for is specified
         """
         return await self._read_s(
             schema,
             request,
             instance,
             query_data,
-            is_for_read,
+            is_for,
         )
 
     async def list_read_s(
@@ -836,7 +886,7 @@ class ModelUtil:
         request: HttpRequest = None,
         instances: models.QuerySet[type["ModelSerializer"] | models.Model] = None,
         query_data: ObjectsQuerySchema = None,
-        is_for_read: bool = False,
+        is_for: Literal["read", "detail"] | None = None,
     ) -> list[dict]:
         """
         Serialize multiple model instances or fetch and serialize using query parameters.
@@ -855,8 +905,9 @@ class ModelUtil:
         query_data : ObjectsQuerySchema, optional
             Query parameters with filters for multiple object lookup.
             Required when instances is None.
-        is_for_read : bool, optional
-            Whether to apply read-specific query optimizations. Defaults to False.
+        is_for : Literal["read", "detail"] | None, optional
+            Purpose of the query, determines which serializable fields to use.
+            Defaults to None.
 
         Returns
         -------
@@ -874,7 +925,7 @@ class ModelUtil:
         -----
         - Uses Pydantic's from_orm() with mode="json" for serialization
         - When instances is provided, request and query_data are ignored
-        - Query optimizations applied when is_for_read=True
+        - Query optimizations applied when is_for is specified
         - Processes queryset asynchronously for efficiency
         """
         return await self._read_s(
@@ -882,7 +933,7 @@ class ModelUtil:
             request,
             instances,
             query_data,
-            is_for_read,
+            is_for,
         )
 
     async def update_s(

ninja_aio/schemas/__init__.py

@@ -5,6 +5,7 @@ from .api import (
     M2MAddSchemaIn,
     M2MRemoveSchemaIn,
     M2MSchemaIn,
+    RelationFilterSchema,
 )
 from .helpers import M2MRelationSchema, QuerySchema, ModelQuerySetSchema, ObjectQuerySchema, ObjectsQuerySchema
 
@@ -20,4 +21,5 @@ __all__ = [
     "ModelQuerySetSchema",
     "ObjectQuerySchema",
     "ObjectsQuerySchema",
+    "RelationFilterSchema",
 ]

ninja_aio/schemas/api.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 from ninja import Schema
 
 
@@ -21,4 +23,21 @@ class M2MRemoveSchemaIn(Schema):
 
 class M2MSchemaIn(Schema):
     add: list = []
-    remove: list = []
+    remove: list = []
+
+
+class RelationFilterSchema(Schema):
+    """
+    Schema for configuring relation-based filters in RelationFilterViewSetMixin.
+
+    Attributes:
+        filter_type: A tuple of (type, default_value) used to generate the query parameter
+            field in the filters schema. Example: (int, None) for optional integer filter.
+        query_param: The name of the query parameter exposed in the API endpoint.
+            This is what clients will use in requests (e.g., ?author_id=5).
+        query_filter: The Django ORM lookup to apply (e.g., "author__id", "category__slug").
+    """
+
+    filter_type: tuple[type, Any]
+    query_param: str
+    query_filter: str

ninja_aio/schemas/helpers.py

@@ -162,10 +162,12 @@ class QueryUtilBaseScopesSchema(BaseModel):
     Schema defining base scopes for query utilities.
     Attributes:
         READ (str): Scope for read operations.
+        DETAIL (str): Scope for detail operations.
         QUERYSET_REQUEST (str): Scope for queryset request operations.
     """
 
     READ: str = "read"
+    DETAIL: str = "detail"
     QUERYSET_REQUEST: str = "queryset_request"
 
 

ninja_aio/views/api.py

@@ -454,11 +454,13 @@ class APIViewSet(API):
             qs = await self.model_util.get_objects(
                 request,
                 query_data=self._get_query_data(),
-                is_for_read=True,
+                is_for="read",
             )
             if filters is not None:
                 qs = await self.query_params_handler(qs, filters.model_dump())
-            return await self.model_util.list_read_s(self.schema_out, request, qs)
+            return await self.model_util.list_read_s(
+                self.schema_out, request, qs, is_for="read"
+            )
 
         return list
 
@@ -491,6 +493,7 @@ class APIViewSet(API):
                 query_data=QuerySchema(
                     getters={"pk": self._get_pk(pk)}, **query_data.model_dump()
                 ),
+                is_for="detail" if self.schema_detail else "read",
             )
 
         return retrieve

ninja_aio/views/mixins.py

@@ -1,4 +1,5 @@
 from ninja_aio.views.api import APIViewSet
+from ninja_aio.schemas import RelationFilterSchema
 
 
 class IcontainsFilterViewSetMixin(APIViewSet):
@@ -273,3 +274,65 @@ class LessEqualDateFilterViewSetMixin(DateFilterViewSetMixin):
     """
 
     _compare_attr = "__lte"
+
+
+class RelationFilterViewSetMixin(APIViewSet):
+    """
+    Mixin providing filtering for related fields in Django QuerySets.
+
+    This mixin applies filters on related fields based on configured RelationFilterSchema
+    entries. Each entry maps a query parameter name to a Django ORM lookup path.
+
+    Attributes:
+        relations_filters: List of RelationFilterSchema defining the relation filters.
+            Each schema specifies:
+            - query_param: The API query parameter name (e.g., "author_id")
+            - query_filter: The Django ORM lookup (e.g., "author__id")
+            - filter_type: Tuple of (type, default) for schema generation
+
+    Example:
+        class BookViewSet(RelationFilterViewSetMixin, APIViewSet):
+            relations_filters = [
+                RelationFilterSchema(
+                    query_param="author_id",
+                    query_filter="author__id",
+                    filter_type=(int, None),
+                ),
+                RelationFilterSchema(
+                    query_param="category_slug",
+                    query_filter="category__slug",
+                    filter_type=(str, None),
+                ),
+            ]
+
+        # GET /books?author_id=5 -> queryset.filter(author__id=5)
+        # GET /books?category_slug=fiction -> queryset.filter(category__slug="fiction")
+
+    Notes:
+        - Filter values that are None or falsy are skipped.
+        - This mixin automatically registers query_params from relations_filters.
+    """
+
+    relations_filters: list[RelationFilterSchema] = []
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        cls.query_params = {
+            **cls.query_params,
+            **{
+                rel_filter.query_param: rel_filter.filter_type
+                for rel_filter in cls.relations_filters
+            },
+        }
+
+    async def query_params_handler(self, queryset, filters):
+        """
+        Apply relation filters to the queryset based on configured relations_filters.
+        """
+        base_qs = await super().query_params_handler(queryset, filters)
+        rel_filters = {}
+        for rel_filter in self.relations_filters:
+            value = filters.get(rel_filter.query_param)
+            if value is not None:
+                rel_filters[rel_filter.query_filter] = value
+        return base_qs.filter(**rel_filters) if rel_filters else base_qs