django-ninja-aio-crud 2.7.0__py3-none-any.whl → 2.9.0__py3-none-any.whl

{django_ninja_aio_crud-2.7.0.dist-info → django_ninja_aio_crud-2.9.0.dist-info}/METADATA

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

{django_ninja_aio_crud-2.7.0.dist-info → django_ninja_aio_crud-2.9.0.dist-info}/RECORD

@@ -1,29 +1,29 @@
-ninja_aio/__init__.py,sha256=FkPurmyPz8Yv7VAiIOZYbFEghPXZ7aeLYX5xBwFSMtk,119
+ninja_aio/__init__.py,sha256=YE75I1ewNyWylWEf1tZjFFmQlFLdsdYyYiQgxSr1Jdk,119
 ninja_aio/api.py,sha256=tuC7vdvn7s1GkCnSFy9Kn1zv0glZfYptRQVvo8ZRtGQ,2429
 ninja_aio/auth.py,sha256=4sWdFPjKiQgUL1d_CSGDblVjnY5ptP6LQha6XXdluJA,9157
 ninja_aio/exceptions.py,sha256=_3xFqfFCOfrrMhSA0xbMqgXy8R0UQjhXaExrFvaDAjY,3891
 ninja_aio/parsers.py,sha256=e_4lGCPV7zs-HTqtdJTc8yQD2KPAn9njbL8nF_Mmgkc,153
 ninja_aio/renders.py,sha256=89g46NWUT8nmDG-rG0nxUYbAQWhuXcYKrPh7e1r_Fc4,1735
-ninja_aio/types.py,sha256=nFqWEopm7eoEaHRzbi6EyA9WZ5Cneyd602ilFKypeQI,577
+ninja_aio/types.py,sha256=E3yfXbNKkvLVcr8bvkHTSyIiCRZ4zumzJaXj1aiBi5U,735
 ninja_aio/decorators/__init__.py,sha256=cDDHD_9EI4CP7c5eL1m2mGNl9bR24i8FAkQsT3_RNGM,371
 ninja_aio/decorators/operations.py,sha256=L9yt2ku5oo4CpOLixCADmkcFjLGsWAn-cg-sDcjFhMA,343
 ninja_aio/decorators/views.py,sha256=0RVU4XaM1HvTQ-BOt_NwUtbhwfHau06lh-O8El1LqQk,8139
 ninja_aio/factory/__init__.py,sha256=IdH2z1ZZpv_IqonaDfVo7IsMzkgop6lHqz42RphUYBU,72
 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=YMzuZ4-ZpUrJBQIabE26gb_GYwsH2rVosWRE95YfdPQ,20775
-ninja_aio/helpers/query.py,sha256=lzaH-htswoJVRT-W736HGMkpMba1VmN98TBLv5cZx9Q,4549
+ninja_aio/helpers/api.py,sha256=2beyexep-ehgaA_1bV5Yuh3zRDVcRCMkrW94nmfDWEA,20819
+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=AlZIkwIiOt-nGBfMDoXu9tJotfzH5L13fv3Rw_4sKUg,35697
-ninja_aio/models/utils.py,sha256=P-YfbVyzUfxm_s1BrgSd6Zs0HIGdZ79PU1qM0Ud9-Xs,30492
+ninja_aio/models/serializers.py,sha256=I7pUz_vl0FElaVsrGaogT_Lj9T4uaNG7UDMGf5VMwW4,38468
+ninja_aio/models/utils.py,sha256=N7waJGOCsoFvbbO1xXy94acKeG85WRK3hjZJz7IukhU,32885
 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=W6IeHi5Tmbjh3FXwDYqjqlLBTVj5uTYq3_JVkNUWayo,7355
+ninja_aio/schemas/helpers.py,sha256=Vti5BfHWpxaJXj_ixZBJb34VRwhHODrlVjRlIuHh_ug,8428
 ninja_aio/views/__init__.py,sha256=DEzjWA6y3WF0V10nNF8eEurLNEodgxKzyFd09AqVp3s,148
-ninja_aio/views/api.py,sha256=GRtjCvAv7jAp3TxpOirsbMVKpBd8hymSMILdE-JLxvI,21327
+ninja_aio/views/api.py,sha256=CW74JB1tsdWfv3Y3x4K9o8yXsrMxCKWZ4QalhqJGan8,22072
 ninja_aio/views/mixins.py,sha256=Jh6BG8Cs823nurVlODlzCquTxKrLH7Pmo5udPqUGZek,11378
-django_ninja_aio_crud-2.7.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
-django_ninja_aio_crud-2.7.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-django_ninja_aio_crud-2.7.0.dist-info/METADATA,sha256=_eQi4SR0xvfnLM6ShB-yvkxffFzUsxNCB39spSHWTOU,9963
-django_ninja_aio_crud-2.7.0.dist-info/RECORD,,
+django_ninja_aio_crud-2.9.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-2.9.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-2.9.0.dist-info/METADATA,sha256=7hbmX5K1ixoBn0RnFlkpnp3runSgZ1pi70v606cUX3Q,9963
+django_ninja_aio_crud-2.9.0.dist-info/RECORD,,

ninja_aio/__init__.py

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

ninja_aio/helpers/api.py

@@ -472,7 +472,7 @@ class ManyToManyAPI:
         model = relation.model
         related_name = relation.related_name
         m2m_auth = relation.auth or self.default_auth
-        rel_util = ModelUtil(model)
+        rel_util = ModelUtil(model, serializer_class=relation.serializer_class)
         rel_path = relation.path or rel_util.verbose_name_path_resolver()
         related_schema = relation.related_schema
         m2m_add, m2m_remove, m2m_get = relation.add, relation.remove, relation.get

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

@@ -1,4 +1,4 @@
-from typing import Any, List, Optional, Union, get_args, get_origin, ForwardRef
+from typing import Any, List, Literal, Optional, Union, get_args, get_origin, ForwardRef
 import warnings
 import sys
 
@@ -15,7 +15,13 @@ from django.db.models.fields.related_descriptors import (
     ForwardOneToOneDescriptor,
 )
 
-from ninja_aio.types import S_TYPES, F_TYPES, SCHEMA_TYPES, ModelSerializerMeta
+from ninja_aio.types import (
+    S_TYPES,
+    F_TYPES,
+    SCHEMA_TYPES,
+    ModelSerializerMeta,
+    SerializerMeta,
+)
 from ninja_aio.schemas.helpers import (
     ModelQuerySetSchema,
     ModelQuerySetExtraSchema,
@@ -55,6 +61,7 @@ class BaseSerializer:
         """
 
         read = ModelQuerySetSchema()
+        detail = ModelQuerySetSchema()
         queryset_request = ModelQuerySetSchema()
         extras: list[ModelQuerySetExtraSchema] = []
 
@@ -98,6 +105,7 @@ class BaseSerializer:
                 module = sys.modules.get(module_path)
                 if module is None:
                     import importlib
+
                     module = importlib.import_module(module_path)
 
                 # Get the serializer class from the module
@@ -136,7 +144,9 @@ class BaseSerializer:
         return serializer_class
 
     @classmethod
-    def _resolve_serializer_reference(cls, serializer_ref: str | type | Any) -> type | Any:
+    def _resolve_serializer_reference(
+        cls, serializer_ref: str | type | Any
+    ) -> type | Any:
         """
         Resolve a serializer reference that may be a string, a class, or a Union of serializers.
 
@@ -217,11 +227,11 @@ class BaseSerializer:
         Schema | Union[Schema, ...] | None
             Union of generated schemas or None if all schemas are None.
         """
-        # Generate schemas for each serializer in the Union
+        # Generate schemas for each serializer in the Union (single call per serializer)
         schemas = tuple(
-            serializer_type.generate_related_s()
+            schema
             for serializer_type in get_args(resolved_union)
-            if serializer_type.generate_related_s() is not None
+            if (schema := serializer_type.generate_related_s()) is not None
         )
 
         if not schemas:
@@ -316,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:
@@ -393,72 +407,105 @@ class BaseSerializer:
         return (field_name, schema | None, None)
 
     @classmethod
-    def get_schema_out_data(cls):
+    def _is_reverse_relation(cls, field_obj) -> bool:
+        """Check if field is a reverse relation (M2M, reverse FK, reverse O2O)."""
+        return isinstance(
+            field_obj,
+            (
+                ManyToManyDescriptor,
+                ReverseManyToOneDescriptor,
+                ReverseOneToOneDescriptor,
+            ),
+        )
+
+    @classmethod
+    def _is_forward_relation(cls, field_obj) -> bool:
+        """Check if field is a forward relation (FK, O2O)."""
+        return isinstance(
+            field_obj, (ForwardOneToOneDescriptor, ForwardManyToOneDescriptor)
+        )
+
+    @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
+        ):
+            warnings.warn(
+                f"{cls.__name__}: reverse relation '{field_name}' is listed in read fields "
+                "but has no entry in relations_serializers; it will be auto-resolved only "
+                "for ModelSerializer relations, otherwise skipped.",
+                UserWarning,
+                stacklevel=3,
+            )
+
+    @classmethod
+    def _process_field(
+        cls,
+        field_name: str,
+        model,
+        relations_serializers: dict,
+    ) -> tuple[str | None, tuple | None, tuple | None]:
         """
-        Collect components for 'Out' read schema generation.
-        Returns (fields, reverse_rel_descriptors, excludes, custom_fields_with_forward_relations, optionals).
-        Enforces relation serializers only when provided by subclass via _get_relations_serializers.
+        Process a single field and determine its classification.
+
+        Returns:
+            (plain_field, reverse_rel, forward_rel) - only one will be non-None
         """
-        fields: list[str] = []
-        reverse_rels: list[tuple] = []
-        rels: list[tuple] = []
-        relations_serializers = cls._get_relations_serializers() or {}
-        model = cls._get_model()
+        field_obj = getattr(model, field_name)
 
-        for f in cls.get_fields("read"):
-            field_obj = getattr(model, f)
-            is_reverse = isinstance(
-                field_obj,
-                (
-                    ManyToManyDescriptor,
-                    ReverseManyToOneDescriptor,
-                    ReverseOneToOneDescriptor,
-                ),
-            )
-            is_forward = isinstance(
-                field_obj, (ForwardOneToOneDescriptor, ForwardManyToOneDescriptor)
+        if cls._is_reverse_relation(field_obj):
+            if field_name not in relations_serializers:
+                cls._warn_missing_relation_serializer(field_name, model)
+            rel_tuple = cls._build_schema_reverse_rel(field_name, field_obj)
+            return (None, rel_tuple, None)
+
+        if cls._is_forward_relation(field_obj):
+            rel_tuple = cls._build_schema_forward_rel(field_name, field_obj)
+            if rel_tuple is True:
+                return (field_name, None, None)
+            return (None, None, rel_tuple)
+
+        return (field_name, None, None)
+
+    @classmethod
+    def get_schema_out_data(cls, schema_type: Literal["Out", "Detail"] = "Out"):
+        """
+        Collect components for output schema generation (Out or Detail).
+
+        Returns:
+            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"
             )
 
-            # If explicit relation serializers are declared, require mapping presence.
-            if (
-                is_reverse
-                and not isinstance(model, ModelSerializerMeta)
-                and f not in relations_serializers
-                and not getattr(settings, "NINJA_AIO_TESTING", False)
-            ):
-                warnings.warn(
-                    f"{cls.__name__}: reverse relation '{f}' is listed in read fields but has no entry in relations_serializers; "
-                    "it will be auto-resolved only for ModelSerializer relations, otherwise skipped.",
-                    UserWarning,
-                    stacklevel=2,
-                )
+        fields_type = "read" if schema_type == "Out" else "detail"
+        model = cls._get_model()
+        relations_serializers = cls._get_relations_serializers() or {}
+
+        fields: list[str] = []
+        reverse_rels: list[tuple] = []
+        forward_rels: list[tuple] = []
 
-            # Reverse relations
-            if is_reverse:
-                rel_tuple = cls._build_schema_reverse_rel(f, field_obj)
-                if rel_tuple:
-                    reverse_rels.append(rel_tuple)
-                continue
-
-            # Forward relations
-            if is_forward:
-                rel_tuple = cls._build_schema_forward_rel(f, field_obj)
-                if rel_tuple is True:
-                    fields.append(f)
-                elif rel_tuple:
-                    rels.append(rel_tuple)
-                # None -> skip entirely
-                continue
-
-            # Plain field
-            fields.append(f)
+        for field_name in cls.get_fields(fields_type):
+            plain, reverse, forward = cls._process_field(
+                field_name, model, relations_serializers
+            )
+            if plain:
+                fields.append(plain)
+            if reverse:
+                reverse_rels.append(reverse)
+            if forward:
+                forward_rels.append(forward)
 
         return (
             fields,
             reverse_rels,
-            cls.get_excluded_fields("read"),
-            cls.get_custom_fields("read") + rels,
-            cls.get_optional_fields("read"),
+            cls.get_excluded_fields(fields_type),
+            cls.get_custom_fields(fields_type) + forward_rels,
+            cls.get_optional_fields(fields_type),
         )
 
     @classmethod
@@ -474,15 +521,16 @@ class BaseSerializer:
         model = cls._get_model()
 
         # Handle special schema types with custom logic
-        if schema_type == "Out":
+        if schema_type == "Out" or schema_type == "Detail":
             fields, reverse_rels, excludes, customs, optionals = (
-                cls.get_schema_out_data()
+                cls.get_schema_out_data(schema_type)
             )
             if not any([fields, reverse_rels, excludes, customs]):
                 return None
+            schema_name = "SchemaOut" if schema_type == "Out" else "DetailSchemaOut"
             return create_schema(
                 model=model,
-                name=f"{model._meta.model_name}SchemaOut",
+                name=f"{model._meta.model_name}{schema_name}",
                 depth=depth,
                 fields=fields,
                 custom_fields=reverse_rels + customs + optionals,
@@ -561,6 +609,11 @@ class BaseSerializer:
         """Generate read (Out) schema."""
         return cls._generate_model_schema("Out", depth)
 
+    @classmethod
+    def generate_detail_s(cls, depth: int = 1) -> Schema:
+        """Generate detail (single object Out) schema."""
+        return cls._generate_model_schema("Detail", depth) or cls.generate_read_s(depth)
+
     @classmethod
     def generate_create_s(cls) -> Schema:
         """Generate create (In) schema."""
@@ -659,6 +712,26 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
         optionals: list[tuple[str, type]] = []
         excludes: list[str] = []
 
+    class DetailSerializer:
+        """Configuration describing detail (single object) read schema.
+
+        Attributes
+        ----------
+        fields : list[str]
+            Explicit model fields to include.
+        excludes : list[str]
+            Fields to force exclude (safety).
+        customs : list[tuple[str, type, Any]]
+            Computed / synthetic output attributes.
+        optionals : list[tuple[str, type]]
+            Optional output fields.
+        """
+
+        fields: list[str] = []
+        customs: list[tuple[str, type, Any]] = []
+        optionals: list[tuple[str, type]] = []
+        excludes: list[str] = []
+
     class UpdateSerializer:
         """Configuration describing update (PATCH/PUT) schema.
 
@@ -684,6 +757,7 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
         "create": "CreateSerializer",
         "update": "UpdateSerializer",
         "read": "ReadSerializer",
+        "detail": "DetailSerializer",
     }
 
     @classmethod
@@ -852,7 +926,7 @@ class SchemaModelConfig(Schema):
     customs: Optional[List[tuple[str, type, Any]]] = None
 
 
-class Serializer(BaseSerializer):
+class Serializer(BaseSerializer, metaclass=SerializerMeta):
     """
     Serializer
     ----------
@@ -867,6 +941,7 @@ class Serializer(BaseSerializer):
         "create": "in",
         "update": "update",
         "read": "out",
+        "detail": "detail",
     }
 
     def __init_subclass__(cls, **kwargs):
@@ -884,6 +959,7 @@ class Serializer(BaseSerializer):
         schema_in: Optional[SchemaModelConfig] = None
         schema_out: Optional[SchemaModelConfig] = None
         schema_update: Optional[SchemaModelConfig] = None
+        schema_detail: Optional[SchemaModelConfig] = None
         relations_serializers: dict[str, "Serializer"] = {}
 
     @classmethod
@@ -908,6 +984,8 @@ class Serializer(BaseSerializer):
                 return cls._get_meta_data("schema_out")
             case "update":
                 return cls._get_meta_data("schema_update")
+            case "detail":
+                return cls._get_meta_data("schema_detail")
             case _:
                 return None
 
@@ -1027,7 +1105,12 @@ class Serializer(BaseSerializer):
         dict
             Serialized data.
         """
-        return await self.util.read_s(schema=self.generate_read_s(), instance=instance)
+        schema = (
+            self.generate_read_s()
+            if self.generate_detail_s() is None
+            else self.generate_detail_s()
+        )
+        return await self.util.read_s(schema=schema, instance=instance)
 
     async def models_dump(
         self, instances: models.QuerySet[models.Model]

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,19 +544,27 @@ 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):
                 select_rels.append(f)
@@ -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/helpers.py

@@ -1,7 +1,7 @@
 from typing import List, Optional, Type
 
 from ninja import Schema
-from ninja_aio.types import ModelSerializerMeta
+from ninja_aio.types import ModelSerializerMeta, SerializerMeta
 from django.db.models import Model
 from pydantic import BaseModel, ConfigDict, model_validator
 
@@ -38,6 +38,10 @@ class M2MRelationSchema(BaseModel):
             Optional explicit schema to represent related objects in responses.
             If `model` is a ModelSerializerMeta, this is auto-derived via `model.generate_related_s()`.
             If `model` is a plain Django model, this must be provided.
+            If `model` is a plain DJango model and this is not provided but serializer_class is provided this last one would be used to generate it.
+        serializer_class (Serializer | None):
+            Optional serializer class associated with the related model. If provided alongside a plain Django model,
+            it can be used to auto-generate the `related_schema`.
         append_slash (bool):
             Whether to append a trailing slash to the generated GET endpoint path. Defaults to False for backward compatibility.
 
@@ -63,6 +67,7 @@ class M2MRelationSchema(BaseModel):
     auth: Optional[list] = None
     filters: Optional[dict[str, tuple]] = None
     related_schema: Optional[Type[Schema]] = None
+    serializer_class: Optional[SerializerMeta] = None
     append_slash: bool = False
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
@@ -70,15 +75,30 @@ class M2MRelationSchema(BaseModel):
     @model_validator(mode="before")
     @classmethod
     def validate_related_schema(cls, data):
-        related_schema = data.get("related_schema")
-        if related_schema is not None:
+        # Early return if related_schema is already provided
+        if data.get("related_schema") is not None:
             return data
+
         model = data.get("model")
-        if not isinstance(model, ModelSerializerMeta):
+        serializer_class = data.get("serializer_class")
+        is_model_serializer = isinstance(model, ModelSerializerMeta)
+
+        # Validate incompatible parameters
+        if is_model_serializer and serializer_class:
+            raise ValueError(
+                "Cannot provide serializer_class when model is a ModelSerializerMeta"
+            )
+
+        # Generate related_schema based on available information
+        if is_model_serializer:
+            data["related_schema"] = model.generate_related_s()
+        elif serializer_class:
+            data["related_schema"] = serializer_class.generate_related_s()
+        else:
             raise ValueError(
-                "related_schema must be provided if model is not a ModelSerializer",
+                "related_schema must be provided if model is not a ModelSerializer"
             )
-        data["related_schema"] = model.generate_related_s()
+
         return data
 
 
@@ -95,6 +115,7 @@ class ModelQuerySetExtraSchema(ModelQuerySetSchema):
         select_related (Optional[list[str]]): List of related fields for select_related optimization.
         prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
     """
+
     scope: str
 
 
@@ -106,6 +127,7 @@ class ObjectQuerySchema(ModelQuerySetSchema):
         select_related (Optional[list[str]]): List of related fields for select_related optimization.
         prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
     """
+
     getters: Optional[dict] = {}
 
 
@@ -117,6 +139,7 @@ class ObjectsQuerySchema(ModelQuerySetSchema):
         select_related (Optional[list[str]]): List of related fields for select_related optimization.
         prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
     """
+
     filters: Optional[dict] = {}
 
 
@@ -129,6 +152,7 @@ class QuerySchema(ModelQuerySetSchema):
         select_related (Optional[list[str]]): List of related fields for select_related optimization.
         prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
     """
+
     filters: Optional[dict] = {}
     getters: Optional[dict] = {}
 
@@ -138,9 +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"
 
 
@@ -163,6 +190,7 @@ class DecoratorsSchema(Schema):
           Consider initializing these in __init__ or using default_factory (if using pydantic/dataclasses)
           to avoid unintended side effects.
     """
+
     list: Optional[List] = []
     retrieve: Optional[List] = []
     create: Optional[List] = []

ninja_aio/types.py

@@ -4,16 +4,21 @@ from joserfc import jwk
 from django.db.models import Model
 from typing import TypeAlias
 
-S_TYPES = Literal["read", "create", "update"]
+S_TYPES = Literal["read", "detail", "create", "update"]
 F_TYPES = Literal["fields", "customs", "optionals", "excludes"]
-SCHEMA_TYPES = Literal["In", "Out", "Patch", "Related"]
+SCHEMA_TYPES = Literal["In", "Out", "Detail", "Patch", "Related"]
 VIEW_TYPES = Literal["list", "retrieve", "create", "update", "delete", "all"]
 JwtKeys: TypeAlias = jwk.RSAKey | jwk.ECKey | jwk.OctKey
 
-class ModelSerializerType(type):
-    def __repr__(self):
-        return self.__name__
 
+class SerializerMeta(type):
+    """Metaclass for serializers - extend with custom behavior as needed."""
+
+    def __repr__(cls):
+        return cls.__name__
+
+
+class ModelSerializerMeta(SerializerMeta, type(Model)):
+    """Metaclass combining SerializerMeta with Django's ModelBase."""
 
-class ModelSerializerMeta(ModelSerializerType, type(Model)):
     pass

ninja_aio/views/api.py

@@ -225,6 +225,7 @@ class APIViewSet(API):
     serializer_class: serializers.Serializer | None = None
     schema_in: Schema | None = None
     schema_out: Schema | None = None
+    schema_detail: Schema | None = None
     schema_update: Schema | None = None
     get_auth: list | None = NOT_SET
     post_auth: list | None = NOT_SET
@@ -262,7 +263,9 @@ class APIViewSet(API):
             if not isinstance(self.model, ModelSerializerMeta)
             else self.model.util
         )
-        self.schema_out, self.schema_in, self.schema_update = self.get_schemas()
+        self.schema_out, self.schema_detail, self.schema_in, self.schema_update = (
+            self.get_schemas()
+        )
         self.path_schema = self._generate_path_schema()
         self.filters_schema = self._generate_filters_schema()
         self.model_verbose_name = (
@@ -365,22 +368,24 @@ class APIViewSet(API):
 
     def get_schemas(self):
         """
-        Compute and return (schema_out, schema_in, schema_update).
+        Compute and return (schema_out, schema_detail, schema_in, schema_update).
 
-        - If model is a ModelSerializer (ModelSerializerMeta), auto-generate read/create/update schemas.
+        - If model is a ModelSerializer (ModelSerializerMeta), auto-generate read/detail/create/update schemas.
         - Otherwise, use existing schemas or generate from serializer_class if provided.
         """
         # ModelSerializer case: prefer explicitly set schemas, otherwise generate from the model
         if isinstance(self.model, ModelSerializerMeta):
             return (
                 self.schema_out or self.model.generate_read_s(),
+                self.schema_detail or self.model.generate_detail_s(),
                 self.schema_in or self.model.generate_create_s(),
                 self.schema_update or self.model.generate_update_s(),
             )
 
         # Non-ModelSerializer: start from provided schemas
-        schema_out, schema_in, schema_update = (
+        schema_out, schema_detail, schema_in, schema_update = (
             self.schema_out,
+            self.schema_detail,
             self.schema_in,
             self.schema_update,
         )
@@ -389,9 +394,10 @@ class APIViewSet(API):
         if self.serializer_class:
             schema_in = schema_in or self.serializer_class.generate_create_s()
             schema_out = schema_out or self.serializer_class.generate_read_s()
+            schema_detail = schema_detail or self.serializer_class.generate_detail_s()
             schema_update = schema_update or self.serializer_class.generate_update_s()
 
-        return (schema_out, schema_in, schema_update)
+        return (schema_out, schema_detail, schema_in, schema_update)
 
     async def query_params_handler(
         self, queryset: QuerySet[ModelSerializer], filters: dict
@@ -448,35 +454,46 @@ 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
 
+    def _get_retrieve_schema(self) -> Schema:
+        """
+        Return the schema to use for retrieve endpoint.
+        Uses schema_detail if available, otherwise falls back to schema_out.
+        """
+        return self.schema_detail or self.schema_out
+
     def retrieve_view(self):
         """
         Register retrieve endpoint.
         """
+        retrieve_schema = self._get_retrieve_schema()
 
         @self.router.get(
             self.get_path_retrieve,
             auth=self.get_view_auth(),
             summary=f"Retrieve {self.model_verbose_name}",
             description=self.retrieve_docs,
-            response={200: self.schema_out, self.error_codes: GenericMessageSchema},
+            response={200: retrieve_schema, self.error_codes: GenericMessageSchema},
         )
         @decorate_view(unique_view(self), *self.extra_decorators.retrieve)
         async def retrieve(request: HttpRequest, pk: Path[self.path_schema]):  # type: ignore
             query_data = self._get_query_data()
             return await self.model_util.read_s(
-                self.schema_out,
+                retrieve_schema,
                 request,
                 query_data=QuerySchema(
                     getters={"pk": self._get_pk(pk)}, **query_data.model_dump()
                 ),
+                is_for="detail" if self.schema_detail else "read",
             )
 
         return retrieve