django-ninja-aio-crud 1.0.1__py3-none-any.whl → 1.0.2__py3-none-any.whl

ninja_aio/models.py

@@ -22,6 +22,23 @@ from .types import S_TYPES, F_TYPES, SCHEMA_TYPES, ModelSerializerMeta
 
 
 async def agetattr(obj, name: str, default=None):
+    """
+    Async wrapper around getattr using sync_to_async.
+
+    Parameters
+    ----------
+    obj : Any
+        Object from which to retrieve the attribute.
+    name : str
+        Attribute name.
+    default : Any, optional
+        Default value if attribute is missing.
+
+    Returns
+    -------
+    Any
+        Attribute value (or default).
+    """
     return await sync_to_async(getattr)(obj, name, default)
 
 
@@ -50,84 +67,112 @@ class ModelUtil:
 
     Key Methods
     -----------
-    - get_object(request, pk=None, filters=None, getters=None, with_qs_request=True)
-        Returns a single object (when pk/getters) or a queryset (otherwise), with
-        select_related + prefetch_related applied.
-    - get_reverse_relations()
-        Discovers reverse relation names for safe prefetch_related usage.
-    - parse_input_data(request, data)
-        Converts a Schema into a model-ready dict:
-          * Strips custom + ignored optionals.
-          * Decodes BinaryField (base64 -> bytes).
-          * Replaces FK ids with related instances.
-        Returns (payload, customs_dict).
-    - parse_output_data(request, data)
-        Post-processes serialized output; replaces nested FK/OneToOne dicts
-        with authoritative related instances and rewrites nested FK keys to <name>_id.
+    - get_object()
+    - parse_input_data()
+    - parse_output_data()
     - create_s / read_s / update_s / delete_s
-        High-level async CRUD operations wrapping the above transformations and hooks.
 
     Error Handling
     --------------
-    - Missing objects -> SerializeError({...}, 404).
-    - Bad base64 -> SerializeError({...}, 400).
+    - Missing objects -> NotFoundError(...)
+    - Bad base64 -> SerializeError({...}, 400)
 
     Performance Notes
     -----------------
-    - Each FK in parse_input_data triggers its own async fetch.
-    - Reverse relation prefetching is opportunistic; trim serializable fields
-      if over-fetching becomes an issue.
-
-    Return Shapes
-    -------------
-    - create_s / read_s / update_s -> dict (post-processed schema dump).
-    - delete_s -> None.
-    - get_object -> model instance or queryset.
-
-    Design Choices
-    --------------
-    - Stateless aside from holding the target model (safe to instantiate per request).
-    - Avoids caching; callers may add caching where profiling justifies it.
-    - Treats absent optional fields as "leave unchanged" (update) or "omit" (create).
-
-    Assumptions
-    -----------
-    - Schema provides model_dump(mode="json").
-    - Django async ORM (Django 4.1+).
-    - BinaryField inputs are base64 strings.
-    - Related primary keys are simple scalars on input.
+    - Each FK resolution is an async DB hit; batch when necessary externally.
 
+    Design
+    ------
+    - Stateless wrapper; safe per-request instantiation.
     """
 
     def __init__(self, model: type["ModelSerializer"] | models.Model):
+        """
+        Initialize with a Django model or ModelSerializer subclass.
+
+        Parameters
+        ----------
+        model : Model | ModelSerializerMeta
+            Target model class.
+        """
         self.model = model
 
     @property
     def serializable_fields(self):
+        """
+        List of fields considered serializable for read operations.
+
+        Returns
+        -------
+        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
 
     @property
     def model_fields(self):
+        """
+        Raw model field names (including forward relations).
+
+        Returns
+        -------
+        list[str]
+        """
         return [field.name for field in self.model._meta.get_fields()]
 
     @property
     def model_name(self) -> str:
+        """
+        Django internal model name.
+
+        Returns
+        -------
+        str
+        """
         return self.model._meta.model_name
 
     @property
     def model_pk_name(self) -> str:
+        """
+        Primary key attribute name (attname).
+
+        Returns
+        -------
+        str
+        """
         return self.model._meta.pk.attname
 
     @property
     def model_verbose_name_plural(self) -> str:
+        """
+        Human readable plural verbose name.
+
+        Returns
+        -------
+        str
+        """
         return self.model._meta.verbose_name_plural
 
     def verbose_name_path_resolver(self) -> str:
+        """
+        Slugify plural verbose name for URL path usage.
+
+        Returns
+        -------
+        str
+        """
         return "-".join(self.model_verbose_name_plural.split(" "))
 
     def verbose_name_view_resolver(self) -> str:
+        """
+        Camel-case plural verbose name for view name usage.
+
+        Returns
+        -------
+        str
+        """
         return self.model_verbose_name_plural.replace(" ", "")
 
     async def get_object(
@@ -142,6 +187,34 @@ class ModelUtil:
         | models.Model
         | models.QuerySet[type["ModelSerializer"] | models.Model]
     ):
+        """
+        Retrieve a single instance (by pk/getters) or a queryset if no lookup criteria.
+
+        Applies queryset_request (if ModelSerializerMeta), select_related, and
+        prefetch_related on discovered reverse relations.
+
+        Parameters
+        ----------
+        request : HttpRequest
+        pk : int | str, optional
+            Primary key lookup.
+        filters : dict, optional
+            Additional filter kwargs.
+        getters : dict, optional
+            Field lookups combined with pk lookup.
+        with_qs_request : bool
+            Whether to apply model-level queryset_request hook.
+
+        Returns
+        -------
+        Model | QuerySet
+            Instance if lookup provided; otherwise queryset.
+
+        Raises
+        ------
+        NotFoundError
+            If instance not found by lookup criteria.
+        """
         get_q = {self.model_pk_name: pk} if pk is not None else {}
         if getters:
             get_q |= getters
@@ -165,6 +238,14 @@ class ModelUtil:
         return obj
 
     def get_reverse_relations(self) -> list[str]:
+        """
+        Discover reverse relation names for safe prefetching.
+
+        Returns
+        -------
+        list[str]
+            Relation attribute names.
+        """
         reverse_rels = []
         for f in self.serializable_fields:
             field_obj = getattr(self.model, f)
@@ -178,11 +259,108 @@ class ModelUtil:
                 reverse_rels.append(field_obj.related.name)
         return reverse_rels
 
+    async def _get_field(self, k: str):
+        return (await agetattr(self.model, k)).field
+
+    def _decode_binary(self, payload: dict, k: str, v: Any, field_obj: models.Field):
+        if not isinstance(field_obj, models.BinaryField):
+            return
+        try:
+            payload[k] = base64.b64decode(v)
+        except Exception as exc:
+            raise SerializeError({k: ". ".join(exc.args)}, 400)
+
+    async def _resolve_fk(
+        self,
+        request: HttpRequest,
+        payload: dict,
+        k: str,
+        v: Any,
+        field_obj: models.Field,
+    ):
+        if not isinstance(field_obj, models.ForeignKey):
+            return
+        rel_util = ModelUtil(field_obj.related_model)
+        rel = await rel_util.get_object(request, v, with_qs_request=False)
+        payload[k] = rel
+
+    def _extract_field_obj(self, field_name: str):
+        """
+        Return the underlying Django Field (if any) for a given attribute name.
+        """
+        descriptor = getattr(self.model, field_name, None)
+        if descriptor is None:
+            return None
+        return getattr(descriptor, "field", None) or getattr(
+            descriptor, "related", None
+        )
+
+    def _should_process_nested(self, value: Any, field_obj: Any) -> bool:
+        """
+        Determine if a payload entry represents a nested FK / O2O relation dict.
+        """
+        if not isinstance(value, dict):
+            return False
+        return isinstance(field_obj, (models.ForeignKey, models.OneToOneField))
+
+    async def _fetch_related_instance(
+        self, request, field_obj: models.Field, nested_dict: dict
+    ):
+        """
+        Resolve the related instance from its primary key inside the nested dict.
+        """
+        rel_util = ModelUtil(field_obj.related_model)
+        rel_pk = nested_dict.get(rel_util.model_pk_name)
+        return await rel_util.get_object(request, rel_pk)
+
+    def _rewrite_nested_foreign_keys(self, rel_obj, nested_dict: dict):
+        """
+        Rewrite foreign key keys inside a nested dict from <key> to <key>_id.
+        """
+        keys_to_rewrite: list[str] = []
+        for rel_k in nested_dict.keys():
+            attr = getattr(rel_obj.__class__, rel_k, None)
+            fk_field = getattr(attr, "field", None)
+            if isinstance(fk_field, models.ForeignKey):
+                keys_to_rewrite.append(rel_k)
+            for old_k in keys_to_rewrite:
+                nested_dict[f"{old_k}_id"] = nested_dict.pop(old_k)
+
     async def parse_input_data(self, request: HttpRequest, data: Schema):
+        """
+        Transform inbound schema data to a model-ready payload.
+
+        Steps
+        -----
+        - Strip custom fields (retain separately).
+        - Drop optional fields with None (ModelSerializer only).
+        - Decode BinaryField base64 values.
+        - Resolve ForeignKey ids to model instances.
+
+        Parameters
+        ----------
+        request : HttpRequest
+        data : Schema
+            Incoming validated schema instance.
+
+        Returns
+        -------
+        tuple[dict, dict]
+            (payload_without_customs, customs_dict)
+
+        Raises
+        ------
+        SerializeError
+            On base64 decoding failure.
+        """
         payload = data.model_dump(mode="json")
-        customs = {}
-        optionals = []
-        if isinstance(self.model, ModelSerializerMeta):
+
+        is_serializer = isinstance(self.model, ModelSerializerMeta)
+
+        # Collect custom and optional fields (only if ModelSerializerMeta)
+        customs: dict[str, Any] = {}
+        optionals: list[str] = []
+        if is_serializer:
             customs = {
                 k: v
                 for k, v in payload.items()
@@ -191,62 +369,85 @@ class ModelUtil:
             optionals = [
                 k for k, v in payload.items() if self.model.is_optional(k) and v is None
             ]
+
+        skip_keys = set()
+        if is_serializer:
+            # Keys to skip during model field processing
+            skip_keys = {
+                k
+                for k, v in payload.items()
+                if (self.model.is_custom(k) and k not in self.model_fields)
+                or (self.model.is_optional(k) and v is None)
+            }
+
+        # Process payload fields
         for k, v in payload.items():
-            if isinstance(self.model, ModelSerializerMeta):
-                if self.model.is_custom(k) and k not in self.model_fields:
-                    continue
-                if self.model.is_optional(k) and v is None:
-                    continue
-            field_obj = (await agetattr(self.model, k)).field
-            if isinstance(field_obj, models.BinaryField):
-                try:
-                    payload |= {k: base64.b64decode(v)}
-                except Exception as exc:
-                    raise SerializeError({k: ". ".join(exc.args)}, 400)
-            if isinstance(field_obj, models.ForeignKey):
-                rel_util = ModelUtil(field_obj.related_model)
-                rel: ModelSerializer = await rel_util.get_object(
-                    request, v, with_qs_request=False
-                )
-                payload |= {k: rel}
-        new_payload = {
-            k: v for k, v in payload.items() if k not in (customs.keys() or optionals)
-        }
+            if k in skip_keys:
+                continue
+            field_obj = await self._get_field(k)
+            self._decode_binary(payload, k, v, field_obj)
+            await self._resolve_fk(request, payload, k, v, field_obj)
+
+        # Preserve original exclusion semantics (customs if present else optionals)
+        exclude_keys = customs.keys() or optionals
+        new_payload = {k: v for k, v in payload.items() if k not in exclude_keys}
+
         return new_payload, customs
 
     async def parse_output_data(self, request: HttpRequest, data: Schema):
-        olds_k: list[dict] = []
+        """
+        Post-process serialized output.
+
+        For nested FK / OneToOne dicts:
+        - Replace dict with authoritative related instance.
+        - Rewrite nested FK keys to <name>_id for nested foreign keys.
+
+        Parameters
+        ----------
+        request : HttpRequest
+        data : Schema
+            Schema (from_orm) instance.
+
+        Returns
+        -------
+        dict
+            Normalized output payload.
+        """
         payload = data.model_dump(mode="json")
+
         for k, v in payload.items():
-            try:
-                field_obj = (await agetattr(self.model, k)).field
-            except AttributeError:
-                try:
-                    field_obj = (await agetattr(self.model, k)).related
-                except AttributeError:
-                    pass
-            if isinstance(v, dict) and (
-                isinstance(field_obj, models.ForeignKey)
-                or isinstance(field_obj, models.OneToOneField)
-            ):
-                rel_util = ModelUtil(field_obj.related_model)
-                rel: ModelSerializer = await rel_util.get_object(
-                    request, v.get(rel_util.model_pk_name)
-                )
-                if isinstance(field_obj, models.ForeignKey):
-                    for rel_k, rel_v in v.items():
-                        field_rel_obj = await agetattr(rel, rel_k)
-                        if isinstance(field_rel_obj, models.ForeignKey):
-                            olds_k.append({rel_k: rel_v})
-                    for obj in olds_k:
-                        for old_k, old_v in obj.items():
-                            v.pop(old_k)
-                            v |= {f"{old_k}_id": old_v}
-                    olds_k = []
-                payload |= {k: rel}
+            field_obj = self._extract_field_obj(k)
+            if not self._should_process_nested(v, field_obj):
+                continue
+
+            rel_instance = await self._fetch_related_instance(request, field_obj, v)
+
+            if isinstance(field_obj, models.ForeignKey):
+                self._rewrite_nested_foreign_keys(rel_instance, v)
+
+            payload[k] = rel_instance
+
         return payload
 
     async def create_s(self, request: HttpRequest, data: Schema, obj_schema: Schema):
+        """
+        Create a new instance and return serialized output.
+
+        Applies custom_actions + post_create hooks if available.
+
+        Parameters
+        ----------
+        request : HttpRequest
+        data : Schema
+            Input schema instance.
+        obj_schema : Schema
+            Read schema class for output.
+
+        Returns
+        -------
+        dict
+            Serialized created object.
+        """
         payload, customs = await self.parse_input_data(request, data)
         pk = (await self.model.objects.acreate(**payload)).pk
         obj = await self.get_object(request, pk)
@@ -260,6 +461,27 @@ class ModelUtil:
         obj: type["ModelSerializer"],
         obj_schema: Schema,
     ):
+        """
+        Serialize an existing instance with the provided read schema.
+
+        Parameters
+        ----------
+        request : HttpRequest
+        obj : Model
+            Target instance.
+        obj_schema : Schema
+            Read schema class.
+
+        Returns
+        -------
+        dict
+            Serialized payload.
+
+        Raises
+        ------
+        SerializeError
+            If obj_schema not provided.
+        """
         if obj_schema is None:
             raise SerializeError({"obj_schema": "must be provided"}, 400)
         return await self.parse_output_data(
@@ -269,6 +491,26 @@ class ModelUtil:
     async def update_s(
         self, request: HttpRequest, data: Schema, pk: int | str, obj_schema: Schema
     ):
+        """
+        Update an existing instance and return serialized output.
+
+        Only non-null fields are applied to the instance.
+
+        Parameters
+        ----------
+        request : HttpRequest
+        data : Schema
+            Input update schema instance.
+        pk : int | str
+            Primary key of target object.
+        obj_schema : Schema
+            Read schema class for output.
+
+        Returns
+        -------
+        dict
+            Serialized updated object.
+        """
         obj = await self.get_object(request, pk)
         payload, customs = await self.parse_input_data(request, data)
         for k, v in payload.items():
@@ -281,6 +523,19 @@ class ModelUtil:
         return await self.read_s(request, updated_object, obj_schema)
 
     async def delete_s(self, request: HttpRequest, pk: int | str):
+        """
+        Delete an instance by primary key.
+
+        Parameters
+        ----------
+        request : HttpRequest
+        pk : int | str
+            Primary key.
+
+        Returns
+        -------
+        None
+        """
         obj = await self.get_object(request, pk)
         await obj.adelete()
         return None
@@ -295,105 +550,13 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
     related schemas.
 
     Goals
+    -----
     - Remove duplication between Model and separate serializer classes.
     - Provide clear extension points (sync + async hooks, custom synthetic fields).
 
-    Inner configuration classes
-    - CreateSerializer
-        fields    : required model fields on create
-        optionals : optional model fields (accepted if present; ignored if None)
-        customs   : [(name, type, default)] synthetic (non‑model) inputs
-        excludes  : model fields disallowed on create
-    - UpdateSerializer (same structure; usually use optionals for PATCH-like behavior)
-    - ReadSerializer
-        fields    : model fields to expose
-        excludes  : fields always excluded (e.g. password)
-        customs   : [(name, type, default)] computed outputs (property > callable > default)
-
-    Generated schema helpers
-    - generate_create_s()   -> input schema ("In")
-    - generate_update_s()   -> input schema for partial/full update ("Patch")
-    - generate_read_s()     -> detailed output schema ("Out")
-    - generate_related_s()  -> compact nested schema ("Related")
-
-    Relation handling (only if related model is also a ModelSerializer)
-    - Forward FK / OneToOne serialized as single nested objects
-    - Reverse OneToOne / Reverse FK / M2M serialized as single or list
-    - Relations skipped if related model exposes no read/custom fields
-
-    Classification helpers
-    - is_custom(field)   -> True if declared in create/update customs
-    - is_optional(field) -> True if declared in create/update optionals
-
-    Sync lifecycle hooks (override as needed)
-      save():
-        on_create_before_save()  (only first insert)
-        before_save()
-        super().save()
-        on_create_after_save()   (only first insert)
-        after_save()
-      delete():
-        super().delete()
-        on_delete()
-
-    Async extension points
-    - queryset_request(request): request-scoped queryset filtering
-    - post_create(): async logic after creation
-    - custom_actions(payload_customs): react to synthetic fields
-
-    Utilities
-    - has_changed(field): compares in-memory value vs DB persisted value
-    - verbose_name_path_resolver(): slugified plural verbose name
-
-    Implementation notes
-    - If both fields and excludes are empty (create/update), optionals are used as the base.
-    - customs + optionals are passed as custom_fields to the schema factory.
-    - Nested relation schemas generated only if the related model explicitly declares
-      readable or custom fields.
-
-    Minimal example
-    ```python
-    from django.db import models
-    from ninja_aio.models import ModelSerializer
-    
-    
-    class User(ModelSerializer):
-        username = models.CharField(max_length=150, unique=True)
-        email = models.EmailField(unique=True)
-
-        class CreateSerializer:
-            fields = ["username", "email"]
-
-        class ReadSerializer:
-            fields = ["id", "username", "email"]
-
-        def __str__(self):
-            return self.username
-    ```
-    -------------------------------------
-    Conceptual Equivalent (Ninja example)
-    Using django-ninja you might otherwise write:
-    ```python
-    from ninja import ModelSchema
-    from api.models import User
-    
-    
-    class UserIn(ModelSchema):
-        class Meta:
-            model = User
-            fields = ["username", "email"]
-    
-    
-    class UserOut(ModelSchema):
-        class Meta:
-            model = User
-            model_fields = ["id", "username", "email"]
-    ```
-
-    Summary
-    Centralizes serialization intent on the model, reducing boilerplate and keeping
-    API and model definitions consistent.
+    See inline docstrings for per-method behavior.
     """
+
     class Meta:
         abstract = True
 
@@ -409,156 +572,52 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
         Attributes
         ----------
         fields : list[str]
-            Explicit REQUIRED model field names for creation. If empty, the
-            implementation may infer required fields from the model (excluding
-            auto / read-only fields). Prefer being explicit.
+            REQUIRED model fields.
         optionals : list[tuple[str, type]]
-            Model fields allowed on create but not required. Each tuple:
-                (field_name, python_type)
-            If omitted in the payload they are ignored; if present with null/None
-            the caller signals an intentional null (subject to model constraints).
+            Optional model fields (nullable / patch-like).
         customs : list[tuple[str, type, Any]]
-            Non-model / synthetic input fields driving creation logic (e.g.,
-            password confirmation, initial related IDs, flags). Each tuple:
-                (name, python_type, default_value)
-            Resolution order (implementation-dependent):
-                1. Value provided by the incoming payload.
-                2. If default_value is callable -> invoked (passing model class or
-                   context if supported).
-                3. Literal default_value.
-            These values are typically consumed inside custom_actions or post_create
-            hooks and are NOT persisted directly unless you do so manually.
+            Synthetic input fields (non-model).
         excludes : list[str]
-            Model field names that must be rejected on create (e.g., "id",
-            audit fields, computed columns).
-
-        Recommended Conventions
-        -----------------------
-        - Always exclude primary keys and auto-managed timestamps.
-        - Keep customs minimal and clearly documented.
-        - Use optionals instead of putting nullable fields in fields if they are
-          not logically required for initial creation.
-
-        Extensibility
-        -------------
-        A higher-level builder can:
-            1. Collect fields + optionals + customs.
-            2. Build a schema where fields are required, optionals are Optional[…],
-               and customs become additional inputs not mapped directly to the model.
+            Disallowed model fields on create (e.g., id, timestamps).
         """
+
         fields: list[str] = []
         customs: list[tuple[str, type, Any]] = []
         optionals: list[tuple[str, type]] = []
         excludes: list[str] = []
 
     class ReadSerializer:
-        """Configuration container describing how to build a read (output) schema for a model.
+        """Configuration describing how to build a read (output) schema.
 
         Attributes
-        ---------
+        ----------
         fields : list[str]
-            Explicit model field names to include in the read schema. If empty, an
-            implementation may choose to include all model fields (or none, depending
-            on the consuming logic).
+            Explicit model fields to include.
         excludes : list[str]
-            Model field names to force-exclude even if they would otherwise be included
-            (e.g., sensitive columns like password, secrets, internal flags).
+            Fields to force exclude (safety).
         customs : list[tuple[str, type, Any]]
-            Additional computed / synthetic attributes to append to the serialized
-            output. Each tuple is:
-                (attribute_name, python_type, default_value)
-            The attribute is resolved in the following preferred order (implementation
-            dependent):
-                1. Attribute / property on the model instance with that name.
-                2. Callable (if the default_value is a callable) invoked to produce a value.
-                3. Fallback to the literal default_value.
-            Example:
-                customs = [
-                    ("full_name", str, lambda obj: f"{obj.first_name} {obj.last_name}".strip())
-                ]
-
-        Conceptual Equivalent (Ninja example)
-        -------------------------------------
-        Using django-ninja you might otherwise write:
-        
-        ```python
-        from ninja import ModelSchema
-        from api.models import User
-
-
-        class UserOut(ModelSchema):            
-            class Meta:
-                model = User
-                model_fields = ["id", "username", "email"]
-        ```
-        
-        This ReadSerializer object centralizes the same intent in a lightweight,
-        framework-agnostic configuration primitive that can be inspected to build
-        schemas dynamically.
-
-        Recommended Conventions
-        -----------------------
-        - Keep fields minimal; prefer explicit inclusion over implicit broad exposure.
-        - Use excludes as a safety net (e.g., always exclude "password").
-        - For customs, always specify a concrete python_type for better downstream
-          validation / OpenAPI generation.
-        - Prefer callables as default_value when computing derived data; use simple
-          literals only for static fallbacks.
-
-        Extensibility Notes
-        -------------------
-        A higher-level factory or metaclass can:
-            1. Read these lists.
-            2. Reflect on the model.
-            3. Generate a Pydantic / Ninja schema class at runtime.
-        This separation enables cleaner unit testing (the config is pure data) and
-        reduces coupling to a specific serialization framework."""
+            Computed / synthetic output attributes.
+        """
+
         fields: list[str] = []
         excludes: list[str] = []
         customs: list[tuple[str, type, Any]] = []
 
     class UpdateSerializer:
-        """Configuration container describing how to build an update (partial/full) input schema.
-
-        Purpose
-        -------
-        Defines which fields can be changed and how they are treated when updating
-        an existing instance (PATCH / PUT–style operations).
+        """Configuration describing update (PATCH/PUT) schema.
 
         Attributes
         ----------
         fields : list[str]
-            Explicit REQUIRED fields for an update operation (rare; most updates are
-            partial so this is often left empty). If non-empty, these must be present
-            in the payload.
+            Required update fields (rare).
         optionals : list[tuple[str, type]]
-            Updatable fields that are optional (most typical case). Omitted fields
-            are left untouched. Provided null/None values indicate an explicit attempt
-            to nullify (subject to model constraints).
+            Editable optional fields.
         customs : list[tuple[str, type, Any]]
-            Non-model / instruction fields guiding update behavior (e.g., "rotate_key",
-            "regenerate_token"). Each tuple:
-                (name, python_type, default_value)
-            Resolution order mirrors CreateSerializer (payload > callable > literal).
-            Typically consumed in custom_actions before or after saving.
+            Synthetic operational inputs.
         excludes : list[str]
-            Fields that must never be updated (immutable or managed fields).
-
-        Recommended Conventions
-        -----------------------
-        - Prefer listing editable columns in optionals rather than fields to facilitate
-          partial updates.
-        - Use customs for operational flags (e.g., "reset_password": bool).
-        - Keep excludes synchronized with CreateSerializer excludes where appropriate.
-
-        Extensibility
-        -------------
-        A schema builder can:
-            1. Treat fields as required.
-            2. Treat optionals as Optional[…].
-            3. Inject customs as additional validated inputs.
-            4. Enforce excludes by rejecting them if present in incoming data.
+            Immutable / blocked fields.
         """
+
         fields: list[str] = []
         customs: list[tuple[str, type, Any]] = []
         optionals: list[tuple[str, type]] = []
@@ -566,30 +625,63 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
 
     @property
     def has_custom_fields_create(self):
+        """
+        Whether CreateSerializer declares custom fields.
+        """
         return hasattr(self.CreateSerializer, "customs")
 
     @property
     def has_custom_fields_update(self):
+        """
+        Whether UpdateSerializer declares custom fields.
+        """
         return hasattr(self.UpdateSerializer, "customs")
 
     @property
     def has_custom_fields(self):
+        """
+        Whether any serializer declares custom fields.
+        """
         return self.has_custom_fields_create or self.has_custom_fields_update
 
     @property
     def has_optional_fields_create(self):
+        """
+        Whether CreateSerializer declares optional fields.
+        """
         return hasattr(self.CreateSerializer, "optionals")
 
     @property
     def has_optional_fields_update(self):
+        """
+        Whether UpdateSerializer declares optional fields.
+        """
         return hasattr(self.UpdateSerializer, "optionals")
 
     @property
     def has_optional_fields(self):
+        """
+        Whether any serializer declares optional fields.
+        """
         return self.has_optional_fields_create or self.has_optional_fields_update
 
     @classmethod
     def _get_fields(cls, s_type: type[S_TYPES], f_type: type[F_TYPES]):
+        """
+        Internal accessor for raw configuration lists.
+
+        Parameters
+        ----------
+        s_type : str
+            Serializer type ("create" | "update" | "read").
+        f_type : str
+            Field category ("fields" | "optionals" | "customs" | "excludes").
+
+        Returns
+        -------
+        list
+            Raw configuration list or empty list.
+        """
         match s_type:
             case "create":
                 fields = getattr(cls.CreateSerializer, f_type, [])
@@ -603,6 +695,19 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
     def _is_special_field(
         cls, s_type: type[S_TYPES], field: str, f_type: type[F_TYPES]
     ):
+        """
+        Determine if a field is declared in a given category for a serializer type.
+
+        Parameters
+        ----------
+        s_type : str
+        field : str
+        f_type : str
+
+        Returns
+        -------
+        bool
+        """
         special_fields = cls._get_fields(s_type, f_type)
         return any(field in special_f for special_f in special_fields)
 
@@ -612,6 +717,21 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
         schema_type: type[SCHEMA_TYPES],
         depth: int = None,
     ) -> Schema:
+        """
+        Core schema factory bridging configuration and ninja.orm.create_schema.
+
+        Parameters
+        ----------
+        schema_type : str
+            "In" | "Patch" | "Out" | "Related".
+        depth : int, optional
+            Relation depth for read schema.
+
+        Returns
+        -------
+        Schema | None
+            Generated schema class or None if no fields.
+        """
         match schema_type:
             case "In":
                 s_type = "create"
@@ -660,11 +780,28 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
 
     @classmethod
     def verbose_name_path_resolver(cls) -> str:
+        """
+        Slugify plural verbose name for URL path segment.
+
+        Returns
+        -------
+        str
+        """
         return "-".join(cls._meta.verbose_name_plural.split(" "))
 
     def has_changed(self, field: str) -> bool:
         """
-        Check if a model field has changed
+        Check if a model field has changed compared to the persisted value.
+
+        Parameters
+        ----------
+        field : str
+            Field name.
+
+        Returns
+        -------
+        bool
+            True if in-memory value differs from DB value.
         """
         if not self.pk:
             return False
@@ -678,27 +815,45 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
     @classmethod
     async def queryset_request(cls, request: HttpRequest):
         """
-        Override this method to return a filtered queryset based
-        on the request received
+        Override to return a request-scoped filtered queryset.
+
+        Parameters
+        ----------
+        request : HttpRequest
+
+        Returns
+        -------
+        QuerySet
         """
         return cls.objects.select_related().all()
 
     async def post_create(self) -> None:
         """
-        Override this method to execute code after the object
-        has been created
+        Async hook executed after first persistence (create path).
         """
         pass
 
     async def custom_actions(self, payload: dict[str, Any]):
         """
-        Override this method to execute custom actions based on
-        custom given fields. It could be useful for post create method.
+        Async hook for reacting to provided custom (synthetic) fields.
+
+        Parameters
+        ----------
+        payload : dict
+            Custom field name/value pairs.
         """
         pass
 
     @classmethod
     def get_related_schema_data(cls):
+        """
+        Build field/custom lists for 'Related' schema (flattening non-relational fields).
+
+        Returns
+        -------
+        tuple[list[str] | None, list[tuple] | None]
+            (related_fields, custom_related_fields) or (None, None)
+        """
         fields = cls.get_fields("read")
         custom_f = {
             name: (value, default)
@@ -728,13 +883,67 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
         related_fields = [f for f in _related_fields if f not in custom_f]
         return related_fields, custom_related_fields
 
+    @classmethod
+    def _build_schema_reverse_rel(cls, field_name: str, descriptor: Any):
+        """
+        Build a reverse relation schema component for 'Out' schema generation.
+        """
+        if isinstance(descriptor, ManyToManyDescriptor):
+            rel_model: ModelSerializer = descriptor.field.related_model
+            if descriptor.reverse:  # reverse side of M2M
+                rel_model = descriptor.field.model
+            rel_type = "many"
+        elif isinstance(descriptor, ReverseManyToOneDescriptor):
+            rel_model = descriptor.field.model
+            rel_type = "many"
+        else:  # ReverseOneToOneDescriptor
+            rel_model = descriptor.related.related_model
+            rel_type = "one"
+
+        if not isinstance(rel_model, ModelSerializerMeta):
+            return None
+        if not rel_model.get_fields("read") and not rel_model.get_custom_fields("read"):
+            return None
+
+        rel_schema = (
+            rel_model.generate_related_s()
+            if rel_type == "one"
+            else list[rel_model.generate_related_s()]
+        )
+        return (field_name, rel_schema | None, None)
+
+    @classmethod
+    def _build_schema_forward_rel(cls, field_name: str, descriptor: Any):
+        """
+        Build a forward relation schema component for 'Out' schema generation.
+        """
+        rel_model = descriptor.field.related_model
+        if not isinstance(rel_model, ModelSerializerMeta):
+            return True  # Signal: treat as plain field
+        if not rel_model.get_fields("read") and not rel_model.get_custom_fields("read"):
+            return None  # Skip entirely
+        rel_schema = rel_model.generate_related_s()
+        return (field_name, rel_schema | None, None)
+
     @classmethod
     def get_schema_out_data(cls):
-        fields = []
-        reverse_rels = []
-        rels = []
+        """
+        Collect components for 'Out' read schema generation.
+
+        Returns
+        -------
+        tuple
+            (fields, reverse_rel_descriptors, excludes, custom_fields_with_forward_relations)
+        """
+
+        fields: list[str] = []
+        reverse_rels: list[tuple] = []
+        rels: list[tuple] = []
+
         for f in cls.get_fields("read"):
             field_obj = getattr(cls, f)
+
+            # Reverse relations
             if isinstance(
                 field_obj,
                 (
@@ -743,46 +952,26 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
                     ReverseOneToOneDescriptor,
                 ),
             ):
-                if isinstance(field_obj, ManyToManyDescriptor):
-                    rel_obj: ModelSerializer = field_obj.field.related_model
-                    if field_obj.reverse:
-                        rel_obj = field_obj.field.model
-                    rel_type = "many"
-                elif isinstance(field_obj, ReverseManyToOneDescriptor):
-                    rel_obj = field_obj.field.model
-                    rel_type = "many"
-                else:  # ReverseOneToOneDescriptor
-                    rel_obj = field_obj.related.related_model
-                    rel_type = "one"
-                if not isinstance(rel_obj, ModelSerializerMeta):
-                    continue
-                if not rel_obj.get_fields("read") and not rel_obj.get_custom_fields(
-                    "read"
-                ):
+                rel_tuple = cls._build_schema_reverse_rel(f, field_obj)
+                if rel_tuple:
+                    reverse_rels.append(rel_tuple)
                     continue
-                rel_schema = (
-                    rel_obj.generate_related_s()
-                    if rel_type != "many"
-                    else list[rel_obj.generate_related_s()]
-                )
-                rel_data = (f, rel_schema | None, None)
-                reverse_rels.append(rel_data)
-                continue
+
+            # Forward relations
             if isinstance(
                 field_obj, (ForwardOneToOneDescriptor, ForwardManyToOneDescriptor)
             ):
-                rel_obj = field_obj.field.related_model
-                if not isinstance(rel_obj, ModelSerializerMeta):
+                rel_tuple = cls._build_schema_forward_rel(f, field_obj)
+                if rel_tuple is True:
                     fields.append(f)
-                    continue
-                if not rel_obj.get_fields("read") and not rel_obj.get_custom_fields(
-                    "read"
-                ):
-                    continue
-                rel_data = (f, rel_obj.generate_related_s() | None, None)
-                rels.append(rel_data)
+                elif rel_tuple:
+                    rels.append(rel_tuple)
+                # If rel_tuple is None -> skip
                 continue
+
+            # Plain field
             fields.append(f)
+
         return (
             fields,
             reverse_rels,
@@ -792,22 +981,88 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
 
     @classmethod
     def is_custom(cls, field: str):
+        """
+        Check if a field is declared as a custom input (create or update).
+
+        Parameters
+        ----------
+        field : str
+
+        Returns
+        -------
+        bool
+        """
         return cls._is_special_field(
             "create", field, "customs"
         ) or cls._is_special_field("update", field, "customs")
 
     @classmethod
     def is_optional(cls, field: str):
+        """
+        Check if a field is declared as optional (create or update).
+
+        Parameters
+        ----------
+        field : str
+
+        Returns
+        -------
+        bool
+        """
         return cls._is_special_field(
             "create", field, "optionals"
         ) or cls._is_special_field("update", field, "optionals")
 
     @classmethod
-    def get_custom_fields(cls, s_type: type[S_TYPES]) -> list[tuple]:
-        return cls._get_fields(s_type, "customs")
+    def get_custom_fields(cls, s_type: type[S_TYPES]) -> list[tuple[str, type, Any]]:
+        """
+        Normalize declared custom field specs into (name, py_type, default) triples.
+
+        Accepted tuple shapes:
+          (name, py_type, default) -> keeps provided default (callable or literal)
+          (name, py_type)          -> marks as required (default = Ellipsis)
+        Any other arity raises ValueError.
+
+        Parameters
+        ----------
+        s_type : str
+            "create" | "update" | "read"
+
+        Returns
+        -------
+        list[tuple[str, type, Any]]
+        """
+        raw_customs = cls._get_fields(s_type, "customs") or []
+        normalized: list[tuple[str, type, Any]] = []
+        for spec in raw_customs:
+            if not isinstance(spec, tuple):
+                raise ValueError(f"Custom field spec must be a tuple, got {type(spec)}")
+            match len(spec):
+                case 3:
+                    name, py_type, default = spec
+                case 2:
+                    name, py_type = spec
+                    default = ...
+                case _:
+                    raise ValueError(
+                        f"Custom field tuple must have length 2 or 3 (name, type[, default]); got {len(spec)}"
+                    )
+            normalized.append((name, py_type, default))
+        return normalized
 
     @classmethod
     def get_optional_fields(cls, s_type: type[S_TYPES]):
+        """
+        Return optional field specifications normalized to (name, type, None).
+
+        Parameters
+        ----------
+        s_type : str
+
+        Returns
+        -------
+        list[tuple[str, type, None]]
+        """
         return [
             (field, field_type, None)
             for field, field_type in cls._get_fields(s_type, "optionals")
@@ -815,64 +1070,117 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
 
     @classmethod
     def get_excluded_fields(cls, s_type: type[S_TYPES]):
+        """
+        Return excluded field names for a serializer type.
+
+        Parameters
+        ----------
+        s_type : str
+
+        Returns
+        -------
+        list[str]
+        """
         return cls._get_fields(s_type, "excludes")
 
     @classmethod
     def get_fields(cls, s_type: type[S_TYPES]):
+        """
+        Return explicit declared fields for a serializer type.
+
+        Parameters
+        ----------
+        s_type : str
+
+        Returns
+        -------
+        list[str]
+        """
         return cls._get_fields(s_type, "fields")
 
     @classmethod
     def generate_read_s(cls, depth: int = 1) -> Schema:
+        """
+        Generate read (Out) schema.
+
+        Parameters
+        ----------
+        depth : int
+            Relation depth.
+
+        Returns
+        -------
+        Schema | None
+        """
         return cls._generate_model_schema("Out", depth)
 
     @classmethod
     def generate_create_s(cls) -> Schema:
+        """
+        Generate create (In) schema.
+
+        Returns
+        -------
+        Schema | None
+        """
         return cls._generate_model_schema("In")
 
     @classmethod
     def generate_update_s(cls) -> Schema:
+        """
+        Generate update (Patch) schema.
+
+        Returns
+        -------
+        Schema | None
+        """
         return cls._generate_model_schema("Patch")
 
     @classmethod
     def generate_related_s(cls) -> Schema:
+        """
+        Generate related (nested) schema.
+
+        Returns
+        -------
+        Schema | None
+        """
         return cls._generate_model_schema("Related")
 
     def after_save(self):
         """
-        Override this method to execute code after the object
-        has been saved
+        Sync hook executed after any save (create or update).
         """
         pass
 
     def before_save(self):
         """
-        Override this method to execute code before the object
-        has been saved
+        Sync hook executed before any save (create or update).
         """
         pass
 
     def on_create_after_save(self):
         """
-        Override this method to execute code after the object
-        has been created
+        Sync hook executed only after initial creation save.
         """
         pass
 
     def on_create_before_save(self):
         """
-        Override this method to execute code before the object
-        has been created
+        Sync hook executed only before initial creation save.
         """
         pass
 
     def on_delete(self):
         """
-        Override this method to execute code after the object
-        has been deleted
+        Sync hook executed after delete.
         """
         pass
 
     def save(self, *args, **kwargs):
+        """
+        Override save lifecycle to inject create/update hooks.
+        """
         if self._state.adding:
             self.on_create_before_save()
         self.before_save()
@@ -882,6 +1190,14 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
         self.after_save()
 
     def delete(self, *args, **kwargs):
+        """
+        Override delete to inject on_delete hook.
+
+        Returns
+        -------
+        tuple(int, dict)
+            Django delete return signature.
+        """
         res = super().delete(*args, **kwargs)
         self.on_delete()
         return res