django-ninja-aio-crud 2.17.0__py3-none-any.whl → 2.18.0__py3-none-any.whl

ninja_aio/models/serializers.py

@@ -25,6 +25,7 @@ from django.db.models.fields.related_descriptors import (
     ForwardOneToOneDescriptor,
 )
 from pydantic import BeforeValidator, Field
+from pydantic._internal._decorators import PydanticDescriptorProxy
 
 from ninja_aio.types import (
     S_TYPES,
@@ -102,14 +103,116 @@ class BaseSerializer:
         queryset_request = ModelQuerySetSchema()
         extras: list[ModelQuerySetExtraSchema] = []
 
+    @classmethod
+    def _collect_validators(cls, source_class) -> dict:
+        """
+        Collect Pydantic validator descriptors from a class.
+
+        Iterates over the class attributes looking for ``PydanticDescriptorProxy``
+        instances (created by ``@field_validator`` and ``@model_validator`` decorators).
+
+        Parameters
+        ----------
+        source_class : type | None
+            The class to scan for validators.
+
+        Returns
+        -------
+        dict
+            Mapping of attribute name to ``PydanticDescriptorProxy`` instance.
+        """
+        validators = {}
+        if source_class is None:
+            return validators
+        for attr_name, attr_value in vars(source_class).items():
+            if isinstance(attr_value, PydanticDescriptorProxy):
+                validators[attr_name] = attr_value
+        return validators
+
+    @classmethod
+    def _apply_validators(cls, schema, validators: dict):
+        """
+        Create a subclass of the given schema with validators attached.
+
+        Pydantic discovers validators via ``PydanticDescriptorProxy`` instances
+        during class creation, so placing them on a subclass is sufficient.
+
+        Parameters
+        ----------
+        schema : Schema | None
+            The base schema class generated by ``create_schema``.
+        validators : dict
+            Mapping of validator names to ``PydanticDescriptorProxy`` instances.
+
+        Returns
+        -------
+        Schema | None
+            A subclass with validators applied, or the original schema if no
+            validators are provided.
+        """
+        if not schema or not validators:
+            return schema
+        return type(schema.__name__, (schema,), validators)
+
+    @classmethod
+    def _get_validators(cls, schema_type: type[SCHEMA_TYPES]) -> dict:
+        """
+        Return collected validators for the given schema type.
+
+        Subclasses must implement this to map schema types to the appropriate
+        validator source class.
+
+        Parameters
+        ----------
+        schema_type : SCHEMA_TYPES
+            One of ``"In"``, ``"Patch"``, ``"Out"``, ``"Detail"``, or ``"Related"``.
+
+        Returns
+        -------
+        dict
+            Mapping of validator names to ``PydanticDescriptorProxy`` instances.
+        """
+        return {}
+
     @classmethod
     def _get_fields(cls, s_type: type[S_TYPES], f_type: type[F_TYPES]):
-        # Subclasses provide implementation.
+        """
+        Return raw configuration list for the given serializer/field category.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type (``"create"`` | ``"update"`` | ``"read"`` | ``"detail"``).
+        f_type : F_TYPES
+            Field category (``"fields"`` | ``"optionals"`` | ``"customs"`` | ``"excludes"``).
+
+        Returns
+        -------
+        list
+            Raw configuration list for the requested category.
+
+        Raises
+        ------
+        NotImplementedError
+            Subclasses must provide an implementation.
+        """
         raise NotImplementedError
 
     @classmethod
     def _get_model(cls) -> models.Model:
-        # Subclasses provide implementation.
+        """
+        Return the Django model class associated with this serializer.
+
+        Returns
+        -------
+        models.Model
+            The Django model class.
+
+        Raises
+        ------
+        NotImplementedError
+            Subclasses must provide an implementation.
+        """
         raise NotImplementedError
 
     @classmethod
@@ -246,12 +349,32 @@ class BaseSerializer:
 
     @classmethod
     def _get_relations_serializers(cls) -> dict[str, "Serializer"]:
-        # Optional in subclasses. Default to no explicit relation serializers.
+        """
+        Return mapping of relation field names to their serializer classes.
+
+        Subclasses may override to provide explicit serializer mappings for
+        relation fields used during read schema generation.
+
+        Returns
+        -------
+        dict[str, Serializer]
+            Mapping of field name to serializer class. Empty by default.
+        """
         return {}
 
     @classmethod
     def _get_relations_as_id(cls) -> list[str]:
-        # Optional in subclasses. Default to no relations as ID.
+        """
+        Return relation field names that should be serialized as IDs.
+
+        Subclasses may override to specify which relation fields should be
+        represented as primary key values instead of nested objects.
+
+        Returns
+        -------
+        list[str]
+            Field names to serialize as IDs. Empty by default.
+        """
         return []
 
     @classmethod
@@ -330,17 +453,50 @@ class BaseSerializer:
     def _is_special_field(
         cls, s_type: type[S_TYPES], field: str, f_type: type[F_TYPES]
     ) -> bool:
-        """Return True if field appears in the given category for s_type."""
+        """
+        Check whether a field appears in the given category for a serializer type.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type (``"create"`` | ``"update"`` | ``"read"`` | ``"detail"``).
+        field : str
+            The field name to look up.
+        f_type : F_TYPES
+            Field category (``"fields"`` | ``"optionals"`` | ``"customs"`` | ``"excludes"``).
+
+        Returns
+        -------
+        bool
+            ``True`` if the field is found in the specified category.
+        """
         special_fields = cls._get_fields(s_type, f_type)
         return any(field in special_f for special_f in special_fields)
 
     @classmethod
     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).
+        Normalize declared custom field specs into ``(name, py_type, default)`` tuples.
+
         Accepted tuple shapes:
-        - (name, py_type, default)
-        - (name, py_type) -> default Ellipsis (required)
+
+        - ``(name, py_type, default)`` -- field with explicit default.
+        - ``(name, py_type)`` -- required field (default set to ``Ellipsis``).
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type whose custom fields to retrieve.
+
+        Returns
+        -------
+        list[tuple[str, type, Any]]
+            Normalized list of ``(name, type, default)`` tuples.
+
+        Raises
+        ------
+        ValueError
+            If a custom field spec is not a tuple or has an invalid length.
         """
         raw_customs = cls._get_fields(s_type, "customs") or []
         normalized: list[tuple[str, Any, Any]] = []
@@ -362,7 +518,19 @@ class BaseSerializer:
 
     @classmethod
     def get_optional_fields(cls, s_type: type[S_TYPES]):
-        """Return optional field specs normalized to (name, type, None)."""
+        """
+        Return optional field specs normalized to ``(name, type, None)`` tuples.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type whose optional fields to retrieve.
+
+        Returns
+        -------
+        list[tuple[str, type, None]]
+            Normalized list where each entry defaults to ``None``.
+        """
         return [
             (field, field_type, None)
             for field, field_type in cls._get_fields(s_type, "optionals")
@@ -370,12 +538,39 @@ class BaseSerializer:
 
     @classmethod
     def get_excluded_fields(cls, s_type: S_TYPES):
-        """Return excluded field names for the serializer type."""
+        """
+        Return excluded field names for the given serializer type.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type whose exclusions to retrieve.
+
+        Returns
+        -------
+        list[str]
+            Field names excluded from schema generation.
+        """
         return cls._get_fields(s_type, "excludes")
 
     @classmethod
     def get_fields(cls, s_type: S_TYPES):
-        """Return explicit declared field names for the serializer type (excludes inline customs)."""
+        """
+        Return explicit declared field names for the serializer type.
+
+        Filters out inline custom field tuples from the fields list, returning
+        only string field names.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type whose fields to retrieve.
+
+        Returns
+        -------
+        list[str]
+            Model field names (excludes inline custom tuples).
+        """
         fields = cls._get_fields(s_type, "fields")
         # Filter out inline custom field tuples, return only string field names
         return [f for f in fields if isinstance(f, str)]
@@ -411,14 +606,40 @@ class BaseSerializer:
 
     @classmethod
     def is_custom(cls, field: str) -> bool:
-        """True if field is declared as a custom input in create or update."""
+        """
+        Check if a field is declared as a custom input in create or update.
+
+        Parameters
+        ----------
+        field : str
+            The field name to check.
+
+        Returns
+        -------
+        bool
+            ``True`` if the field appears in the customs category for either
+            ``create`` or ``update`` serializer types.
+        """
         return cls._is_special_field(
             "create", field, "customs"
         ) or cls._is_special_field("update", field, "customs")
 
     @classmethod
     def is_optional(cls, field: str) -> bool:
-        """True if field is declared as optional in create or update."""
+        """
+        Check if a field is declared as optional in create or update.
+
+        Parameters
+        ----------
+        field : str
+            The field name to check.
+
+        Returns
+        -------
+        bool
+            ``True`` if the field appears in the optionals category for either
+            ``create`` or ``update`` serializer types.
+        """
         return cls._is_special_field(
             "create", field, "optionals"
         ) or cls._is_special_field("update", field, "optionals")
@@ -531,7 +752,20 @@ class BaseSerializer:
 
     @classmethod
     def _is_reverse_relation(cls, field_obj) -> bool:
-        """Check if field is a reverse relation (M2M, reverse FK, reverse O2O)."""
+        """
+        Check if a field descriptor represents a reverse relation.
+
+        Parameters
+        ----------
+        field_obj : Any
+            Django model field descriptor.
+
+        Returns
+        -------
+        bool
+            ``True`` if the descriptor is a ``ManyToManyDescriptor``,
+            ``ReverseManyToOneDescriptor``, or ``ReverseOneToOneDescriptor``.
+        """
         return isinstance(
             field_obj,
             (
@@ -543,14 +777,39 @@ class BaseSerializer:
 
     @classmethod
     def _is_forward_relation(cls, field_obj) -> bool:
-        """Check if field is a forward relation (FK, O2O)."""
+        """
+        Check if a field descriptor represents a forward relation.
+
+        Parameters
+        ----------
+        field_obj : Any
+            Django model field descriptor.
+
+        Returns
+        -------
+        bool
+            ``True`` if the descriptor is a ``ForwardOneToOneDescriptor``
+            or ``ForwardManyToOneDescriptor``.
+        """
         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."""
+        """
+        Emit a warning for reverse relations without an explicit serializer mapping.
+
+        Only warns when the related model is not a ``ModelSerializer`` and the
+        ``NINJA_AIO_RAISE_SERIALIZATION_WARNINGS`` setting is enabled (default).
+
+        Parameters
+        ----------
+        field_name : str
+            Name of the reverse relation field.
+        model : type
+            The Django model class owning the field.
+        """
         if not isinstance(model, ModelSerializerMeta) and getattr(
             settings, "NINJA_AIO_RAISE_SERIALIZATION_WARNINGS", True
         ):
@@ -675,10 +934,26 @@ class BaseSerializer:
         depth: int = None,
     ) -> Schema:
         """
-        Core schema factory bridging configuration to ninja.orm.create_schema.
-        Handles In/Patch/Out/Related.
+        Core schema factory bridging serializer configuration to ``ninja.orm.create_schema``.
+
+        Dispatches to the appropriate field/custom/exclude gathering logic based
+        on the requested schema type and delegates to Django Ninja's
+        ``create_schema`` for the actual Pydantic model construction.
+
+        Parameters
+        ----------
+        schema_type : SCHEMA_TYPES
+            One of ``"In"``, ``"Patch"``, ``"Out"``, ``"Detail"``, or ``"Related"``.
+        depth : int, optional
+            Nesting depth for related model schemas (used by ``Out`` and ``Detail``).
+
+        Returns
+        -------
+        Schema | None
+            Generated Pydantic schema, or ``None`` if no fields are configured.
         """
         model = cls._get_model()
+        validators = cls._get_validators(schema_type)
 
         # Handle special schema types with custom logic
         if schema_type == "Out" or schema_type == "Detail":
@@ -688,7 +963,7 @@ class BaseSerializer:
             if not any([fields, reverse_rels, excludes, customs]):
                 return None
             schema_name = "SchemaOut" if schema_type == "Out" else "DetailSchemaOut"
-            return create_schema(
+            schema = create_schema(
                 model=model,
                 name=f"{model._meta.model_name}{schema_name}",
                 depth=depth,
@@ -696,26 +971,26 @@ class BaseSerializer:
                 custom_fields=reverse_rels + customs + optionals,
                 exclude=excludes,
             )
+            return cls._apply_validators(schema, validators)
 
         if schema_type == "Related":
             fields, customs = cls.get_related_schema_data()
             if not fields and not customs:
                 return None
-            return create_schema(
+            schema = create_schema(
                 model=model,
                 name=f"{model._meta.model_name}SchemaRelated",
                 fields=fields,
                 custom_fields=customs,
             )
+            return cls._apply_validators(schema, validators)
 
         # Handle standard In/Patch schema types
         s_type = "create" if schema_type == "In" else "update"
         fields = cls.get_fields(s_type)
         optionals = cls.get_optional_fields(s_type)
         customs = (
-            cls.get_custom_fields(s_type)
-            + optionals
-            + cls.get_inline_customs(s_type)
+            cls.get_custom_fields(s_type) + optionals + cls.get_inline_customs(s_type)
         )
         excludes = cls.get_excluded_fields(s_type)
 
@@ -736,13 +1011,14 @@ class BaseSerializer:
         if not any([fields, customs, excludes]):
             return None
 
-        return create_schema(
+        schema = create_schema(
             model=model,
             name=f"{model._meta.model_name}Schema{schema_type}",
             fields=fields,
             custom_fields=customs,
             exclude=excludes,
         )
+        return cls._apply_validators(schema, validators)
 
     @classmethod
     def get_related_schema_data(cls):
@@ -780,27 +1056,78 @@ class BaseSerializer:
 
     @classmethod
     def generate_read_s(cls, depth: int = 1) -> Schema:
-        """Generate read (Out) schema."""
+        """
+        Generate the read (Out) schema for list responses.
+
+        Parameters
+        ----------
+        depth : int, optional
+            Nesting depth for related models. Defaults to ``1``.
+
+        Returns
+        -------
+        Schema | None
+            Generated Pydantic schema, or ``None`` if no read fields are configured.
+        """
         return cls._generate_model_schema("Out", depth)
 
     @classmethod
     def generate_detail_s(cls, depth: int = 1) -> Schema:
-        """Generate detail (single object Out) schema."""
+        """
+        Generate the detail (single-object) read schema.
+
+        Falls back to the standard read schema if no detail-specific
+        configuration is defined.
+
+        Parameters
+        ----------
+        depth : int, optional
+            Nesting depth for related models. Defaults to ``1``.
+
+        Returns
+        -------
+        Schema
+            Generated Pydantic schema (never ``None``; falls back to read 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."""
+        """
+        Generate the create (In) schema for input validation.
+
+        Returns
+        -------
+        Schema | None
+            Generated Pydantic schema, or ``None`` if no create fields are configured.
+        """
         return cls._generate_model_schema("In")
 
     @classmethod
     def generate_update_s(cls) -> Schema:
-        """Generate update (Patch) schema."""
+        """
+        Generate the update (Patch) schema for partial updates.
+
+        Returns
+        -------
+        Schema | None
+            Generated Pydantic schema, or ``None`` if no update fields are configured.
+        """
         return cls._generate_model_schema("Patch")
 
     @classmethod
     def generate_related_s(cls) -> Schema:
-        """Generate related (nested) schema."""
+        """
+        Generate the related (nested) schema for embedding in parent schemas.
+
+        Includes only non-relational model fields and custom fields, preventing
+        infinite nesting of related objects.
+
+        Returns
+        -------
+        Schema | None
+            Generated Pydantic schema, or ``None`` if no fields are configured.
+        """
         return cls._generate_model_schema("Related")
 
     @classmethod
@@ -861,8 +1188,8 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
             Disallowed model fields on create (e.g., id, timestamps).
         """
 
-        fields: list[str | tuple[str, Any, Any]] = []
-        customs: list[tuple[str, Any, Any]] = []
+        fields: list[str | tuple[str, Any, Any] | tuple[str, Any]] = []
+        customs: list[tuple[str, Any, Any] | tuple[str, Any]] = []
         optionals: list[tuple[str, Any]] = []
         excludes: list[str] = []
 
@@ -883,8 +1210,8 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
             Relation fields to serialize as IDs instead of nested objects.
         """
 
-        fields: list[str | tuple[str, Any, Any]] = []
-        customs: list[tuple[str, Any, Any]] = []
+        fields: list[str | tuple[str, Any, Any] | tuple[str, Any]] = []
+        customs: list[tuple[str, Any, Any] | tuple[str, Any]] = []
         optionals: list[tuple[str, Any]] = []
         excludes: list[str] = []
         relations_as_id: list[str] = []
@@ -904,8 +1231,8 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
             Optional output fields.
         """
 
-        fields: list[str | tuple[str, Any, Any]] = []
-        customs: list[tuple[str, Any, Any]] = []
+        fields: list[str | tuple[str, Any, Any] | tuple[str, Any]] = []
+        customs: list[tuple[str, Any, Any] | tuple[str, Any]] = []
         optionals: list[tuple[str, Any]] = []
         excludes: list[str] = []
 
@@ -937,9 +1264,47 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
         "detail": "DetailSerializer",
     }
 
+    # Schema type to serializer type mapping for validator resolution
+    _SCHEMA_TO_S_TYPE = {
+        "In": "create",
+        "Patch": "update",
+        "Out": "read",
+        "Detail": "detail",
+        "Related": "read",
+    }
+
+    @classmethod
+    def _get_validators(cls, schema_type: type[SCHEMA_TYPES]) -> dict:
+        """
+        Collect validators from the inner serializer class for the given schema type.
+
+        Parameters
+        ----------
+        schema_type : SCHEMA_TYPES
+            One of ``"In"``, ``"Patch"``, ``"Out"``, ``"Detail"``, or ``"Related"``.
+
+        Returns
+        -------
+        dict
+            Mapping of validator names to ``PydanticDescriptorProxy`` instances.
+        """
+        s_type = cls._SCHEMA_TO_S_TYPE.get(schema_type)
+        config_name = cls._SERIALIZER_CONFIG_MAP.get(s_type)
+        config_class = getattr(cls, config_name, None) if config_name else None
+        return cls._collect_validators(config_class)
+
     @classmethod
     def _get_relations_as_id(cls) -> list[str]:
-        """Return relation fields to serialize as IDs instead of nested objects."""
+        """
+        Return relation fields to serialize as primary key values.
+
+        Reads the ``relations_as_id`` attribute from ``ReadSerializer``.
+
+        Returns
+        -------
+        list[str]
+            Field names whose related objects should be serialized as IDs.
+        """
         return getattr(cls.ReadSerializer, "relations_as_id", [])
 
     @classmethod
@@ -970,17 +1335,30 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
 
     @classmethod
     def _get_model(cls) -> "ModelSerializer":
-        """Return the model class itself."""
+        """
+        Return the model class itself.
+
+        Since ``ModelSerializer`` is mixed directly into the model, the model
+        class is the serializer class.
+
+        Returns
+        -------
+        ModelSerializer
+            The model/serializer class.
+        """
         return cls
 
     @classmethod
     def verbose_name_path_resolver(cls) -> str:
         """
-        Slugify plural verbose name for URL path segment.
+        Slugify the plural verbose name for use as a URL path segment.
+
+        Replaces spaces with hyphens in the model's ``verbose_name_plural``.
 
         Returns
         -------
         str
+            Hyphen-separated URL-safe path segment.
         """
         return "-".join(cls._meta.verbose_name_plural.split(" "))
 
@@ -1103,14 +1481,16 @@ class SchemaModelConfig(Schema):
         Optional model fields. Type can be any valid type annotation including Union.
     exclude : Optional[List[str]]
         Model fields to exclude.
-    customs : Optional[List[tuple[str, Any, Any]]]
+    customs : Optional[List[tuple[str, Any, Any] | tuple[str, Any]]]
         Custom / synthetic fields. Type can be any valid type annotation including Union.
+        - 2-tuple: (name, type) - required field
+        - 3-tuple: (name, type, default) - optional field with default
     """
 
     fields: Optional[List[str | tuple[str, Any, Any] | tuple[str, Any]]] = None
     optionals: Optional[List[tuple[str, Any]]] = None
     exclude: Optional[List[str]] = None
-    customs: Optional[List[tuple[str, Any, Any]]] = None
+    customs: Optional[List[tuple[str, Any, Any] | tuple[str, Any]]] = None
 
 
 class Serializer(BaseSerializer, metaclass=SerializerMeta):
@@ -1131,6 +1511,15 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         "detail": "detail",
     }
 
+    # Schema type to validators inner class mapping
+    _VALIDATORS_CLASS_MAP = {
+        "In": "CreateValidators",
+        "Patch": "UpdateValidators",
+        "Out": "ReadValidators",
+        "Detail": "DetailValidators",
+        "Related": "ReadValidators",
+    }
+
     def __init_subclass__(cls, **kwargs):
         super().__init_subclass__(**kwargs)
         from ninja_aio.models.utils import ModelUtil
@@ -1150,26 +1539,118 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         relations_serializers: dict[str, "Serializer"] = {}
         relations_as_id: list[str] = []
 
+    def _parse_payload(self, payload: dict[str, Any] | Schema) -> dict[str, Any]:
+        """
+        Parse and return the input payload.
+
+        Can be overridden to implement custom parsing logic.
+
+        Parameters
+        ----------
+        payload : dict | Schema
+            Input data.
+
+        Returns
+        -------
+        dict
+            Parsed payload.
+        """
+        return payload.model_dump() if isinstance(payload, Schema) else payload
+
+    @classmethod
+    def _get_validators(cls, schema_type: type[SCHEMA_TYPES]) -> dict:
+        """
+        Collect validators from the inner validators class for the given schema type.
+
+        Looks for inner classes named ``CreateValidators``, ``ReadValidators``,
+        ``UpdateValidators``, or ``DetailValidators`` on the serializer.
+
+        Parameters
+        ----------
+        schema_type : SCHEMA_TYPES
+            One of ``"In"``, ``"Patch"``, ``"Out"``, ``"Detail"``, or ``"Related"``.
+
+        Returns
+        -------
+        dict
+            Mapping of validator names to ``PydanticDescriptorProxy`` instances.
+        """
+        class_name = cls._VALIDATORS_CLASS_MAP.get(schema_type)
+        validators_class = getattr(cls, class_name, None) if class_name else None
+        return cls._collect_validators(validators_class)
+
     @classmethod
     def _get_relations_as_id(cls) -> list[str]:
+        """
+        Return relation fields to serialize as primary key values.
+
+        Reads the ``relations_as_id`` attribute from ``Meta``.
+
+        Returns
+        -------
+        list[str]
+            Field names whose related objects should be serialized as IDs.
+        """
         relations_as_id = cls._get_meta_data("relations_as_id")
         return relations_as_id or []
 
     @classmethod
     def _get_meta_data(cls, attr_name: str) -> Any:
+        """
+        Retrieve an attribute from the nested ``Meta`` class.
+
+        Parameters
+        ----------
+        attr_name : str
+            Name of the ``Meta`` attribute to look up.
+
+        Returns
+        -------
+        Any
+            The attribute value, or ``None`` if not defined.
+        """
         return getattr(cls.Meta, attr_name, None)
 
     @classmethod
     def _get_model(cls) -> models.Model:
+        """
+        Return the Django model class from ``Meta.model``.
+
+        Returns
+        -------
+        models.Model
+            The validated Django model class.
+        """
         return cls._validate_model()
 
     @classmethod
     def _get_relations_serializers(cls) -> dict[str, "Serializer"]:
+        """
+        Return the explicit relation-to-serializer mapping from ``Meta``.
+
+        Returns
+        -------
+        dict[str, Serializer]
+            Mapping of relation field names to serializer classes.
+        """
         relations_serializers = cls._get_meta_data("relations_serializers")
         return relations_serializers or {}
 
     @classmethod
     def _get_schema_meta(cls, schema_type: str) -> SchemaModelConfig | None:
+        """
+        Retrieve the ``SchemaModelConfig`` for the given schema type.
+
+        Parameters
+        ----------
+        schema_type : str
+            One of ``"in"``, ``"out"``, ``"update"``, or ``"detail"``.
+
+        Returns
+        -------
+        SchemaModelConfig | None
+            The configuration object, or ``None`` if not defined.
+        """
         match schema_type:
             case "in":
                 return cls._get_meta_data("schema_in")
@@ -1184,6 +1665,19 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
 
     @classmethod
     def _validate_model(cls):
+        """
+        Validate and return the model defined in ``Meta.model``.
+
+        Returns
+        -------
+        models.Model
+            The validated Django model class.
+
+        Raises
+        ------
+        ValueError
+            If ``Meta.model`` is not defined or is not a Django model subclass.
+        """
         model = cls._get_meta_data("model")
         if not model:
             raise ValueError("Meta.model must be defined for Serializer.")
@@ -1193,7 +1687,23 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
 
     @classmethod
     def _get_fields(cls, s_type: type[S_TYPES], f_type: type[F_TYPES]):
-        """Internal accessor for raw configuration lists from Meta schemas."""
+        """
+        Return raw configuration list from the Meta schema for the given categories.
+
+        Falls back to the ``out`` schema when ``detail`` is requested but not defined.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type (``"create"`` | ``"update"`` | ``"read"`` | ``"detail"``).
+        f_type : F_TYPES
+            Field category (``"fields"`` | ``"optionals"`` | ``"customs"`` | ``"excludes"``).
+
+        Returns
+        -------
+        list
+            Raw configuration list, or empty list if not configured.
+        """
         schema_key = cls._SCHEMA_META_MAP.get(s_type)
         if not schema_key:
             return []
@@ -1248,13 +1758,13 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         self.after_save(instance)
         return instance
 
-    async def create(self, payload: dict[str, Any]) -> models.Model:
+    async def create(self, payload: dict[str, Any] | Schema) -> models.Model:
         """
         Create a new model instance from the provided payload.
 
         Parameters
         ----------
-        payload : dict
+        payload : dict | Schema
             Input data.
 
         Returns
@@ -1262,11 +1772,11 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         models.Model
             Created model instance.
         """
-        instance: models.Model = self.model(**payload)
+        instance: models.Model = self.model(**self._parse_payload(payload))
         return await self.save(instance)
 
     async def update(
-        self, instance: models.Model, payload: dict[str, Any]
+        self, instance: models.Model, payload: dict[str, Any] | Schema
     ) -> models.Model:
         """
         Update an existing model instance with the provided payload.
@@ -1275,7 +1785,7 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         ----------
         instance : models.Model
             The model instance to update.
-        payload : dict
+        payload : dict | Schema
             Input data.
 
         Returns
@@ -1283,7 +1793,7 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         models.Model
             Updated model instance.
         """
-        for attr, value in payload.items():
+        for attr, value in self._parse_payload(payload).items():
             setattr(instance, attr, value)
         return await self.save(instance)