django-ninja-aio-crud 2.13.0__py3-none-any.whl → 2.15.0__py3-none-any.whl

{django_ninja_aio_crud-2.13.0.dist-info → django_ninja_aio_crud-2.15.0.dist-info}/METADATA

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

{django_ninja_aio_crud-2.13.0.dist-info → django_ninja_aio_crud-2.15.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-ninja_aio/__init__.py,sha256=927xxMRmWc-R42YP-42eXiVvPNa8N9YLu1m4VPIaPvY,120
+ninja_aio/__init__.py,sha256=1ZReAODrup4BI5sHOAuanMqhDqfl36W8gVvhBrf5IZ0,120
 ninja_aio/api.py,sha256=tuC7vdvn7s1GkCnSFy9Kn1zv0glZfYptRQVvo8ZRtGQ,2429
 ninja_aio/auth.py,sha256=4sWdFPjKiQgUL1d_CSGDblVjnY5ptP6LQha6XXdluJA,9157
 ninja_aio/exceptions.py,sha256=_3xFqfFCOfrrMhSA0xbMqgXy8R0UQjhXaExrFvaDAjY,3891
@@ -14,7 +14,7 @@ ninja_aio/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU
 ninja_aio/helpers/api.py,sha256=O2nGvP3VSsG-AReQRn90yDH8vS3kMKh125j-ikwgGoQ,20987
 ninja_aio/helpers/query.py,sha256=Lqv4nrWYr543tC5K-SEcBottLID8cb83aDc26i2Wxj4,5053
 ninja_aio/models/__init__.py,sha256=L3UQnQAlKoI3F7jinadL-Nn55hkPvnSRPYW0JtnbWFo,114
-ninja_aio/models/serializers.py,sha256=VtyWiSGA9vOmxC2S-2lG6mvF33T61sUkNaDmGkAIiOM,38535
+ninja_aio/models/serializers.py,sha256=tm2ACQO-n877NTYN0YR-6qVZrZQpWgPDh0EeOZo_TWY,42824
 ninja_aio/models/utils.py,sha256=lAXtc3YY7_n4f0jIacX4DSXhUOzMy7y5MsBnInNxtfk,32874
 ninja_aio/schemas/__init__.py,sha256=dHILiYBKMb51lDcyQdiXRw_0nzqM7Lu81UX2hv7kEfo,837
 ninja_aio/schemas/api.py,sha256=dGUpJXR1iAf93QNR4kYj1uqIkTjiMfXultCotY6GtaQ,361
@@ -24,7 +24,7 @@ ninja_aio/schemas/helpers.py,sha256=h4zQRf21NVLMQbIVH-psAE4FICUBc857EqngblEy7og,
 ninja_aio/views/__init__.py,sha256=DEzjWA6y3WF0V10nNF8eEurLNEodgxKzyFd09AqVp3s,148
 ninja_aio/views/api.py,sha256=AAqkj0xT8J3PmJvsbluZ33cfrmrXJHiV9ARe2BqnfQ8,22492
 ninja_aio/views/mixins.py,sha256=Zl6J8gbVagwT85bzDuKyJTk3iFxxFgX0YgYkjiUxZGg,17040
-django_ninja_aio_crud-2.13.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
-django_ninja_aio_crud-2.13.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-django_ninja_aio_crud-2.13.0.dist-info/METADATA,sha256=dj3-NSAn8DeyBSViefyGt8rLp_f5bfSaZmkbVaQ2gbA,9964
-django_ninja_aio_crud-2.13.0.dist-info/RECORD,,
+django_ninja_aio_crud-2.15.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-2.15.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-2.15.0.dist-info/METADATA,sha256=m89g4FLCQgQvwCkSoJLxzsUwCuf4ESwyqKJLX31qKAo,9964
+django_ninja_aio_crud-2.15.0.dist-info/RECORD,,

ninja_aio/__init__.py

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

ninja_aio/models/serializers.py

@@ -1,4 +1,14 @@
-from typing import Any, List, Literal, Optional, Union, get_args, get_origin, ForwardRef
+from typing import (
+    Annotated,
+    Any,
+    List,
+    Literal,
+    Optional,
+    Union,
+    get_args,
+    get_origin,
+    ForwardRef,
+)
 import warnings
 import sys
 
@@ -14,6 +24,7 @@ from django.db.models.fields.related_descriptors import (
     ForwardManyToOneDescriptor,
     ForwardOneToOneDescriptor,
 )
+from pydantic import BeforeValidator, Field
 
 from ninja_aio.types import (
     S_TYPES,
@@ -28,6 +39,32 @@ from ninja_aio.schemas.helpers import (
 )
 
 
+def _extract_pk(v: Any) -> Any:
+    """Extract primary key from a model instance or return value as-is."""
+    if hasattr(v, "pk"):
+        return v.pk
+    return v
+
+
+class PkFromModel:
+    """Subscriptable type for extracting PK from model instances during serialization.
+
+    Usage:
+        PkFromModel[int]   -> for integer PKs
+        PkFromModel[str]   -> for string PKs
+        PkFromModel[UUID]  -> for UUID PKs
+        PkFromModel        -> defaults to int (backwards compatible)
+    """
+
+    _default = Annotated[int, BeforeValidator(_extract_pk)]
+
+    def __class_getitem__(cls, pk_type: type) -> type:
+        return Annotated[pk_type, BeforeValidator(_extract_pk)]
+
+    def __new__(cls):
+        return cls._default
+
+
 class BaseSerializer:
     """
     BaseSerializer
@@ -212,6 +249,11 @@ class BaseSerializer:
         # Optional in subclasses. Default to no explicit relation serializers.
         return {}
 
+    @classmethod
+    def _get_relations_as_id(cls) -> list[str]:
+        # Optional in subclasses. Default to no relations as ID.
+        return []
+
     @classmethod
     def _generate_union_schema(cls, resolved_union: Any) -> Any:
         """
@@ -350,10 +392,25 @@ class BaseSerializer:
         ) or cls._is_special_field("update", field, "optionals")
 
     @classmethod
-    def _build_schema_reverse_rel(cls, field_name: str, descriptor: Any):
+    def _build_schema_reverse_rel(
+        cls, field_name: str, descriptor: Any, relations_as_id: list[str]
+    ):
         """
         Build a reverse relation schema component for 'Out' schema generation.
-        Returns a custom field tuple or None to skip.
+
+        Parameters
+        ----------
+        field_name : str
+            Name of the relation field.
+        descriptor : Any
+            Django field descriptor (ManyToManyDescriptor, ReverseManyToOneDescriptor, etc.).
+        relations_as_id : list[str]
+            Pre-fetched list of fields to serialize as IDs.
+
+        Returns
+        -------
+        tuple | None
+            Custom field tuple for schema generation, or None to skip.
         """
         # Resolve related model and cardinality
         if isinstance(descriptor, ManyToManyDescriptor):
@@ -371,6 +428,17 @@ class BaseSerializer:
             rel_model = descriptor.related.related_model
             many = False
 
+        # Handle relations_as_id for reverse relations
+        if field_name in relations_as_id:
+            from ninja_aio.models.utils import ModelUtil
+            pk_field_type = ModelUtil(rel_model).pk_field_type
+            if many:
+                # For many relations, use PkFromModel to extract PKs from model instances
+                return (field_name, list[PkFromModel[pk_field_type]], Field(default_factory=list))
+            else:
+                # For single reverse relations (ReverseOneToOne), extract pk
+                return (field_name, PkFromModel[pk_field_type] | None, None)
+
         schema = cls._resolve_relation_schema(field_name, rel_model)
         if not schema:
             return None
@@ -379,14 +447,36 @@ class BaseSerializer:
         return (field_name, rel_schema_type | None, None)
 
     @classmethod
-    def _build_schema_forward_rel(cls, field_name: str, descriptor: Any):
+    def _build_schema_forward_rel(
+        cls, field_name: str, descriptor: Any, relations_as_id: list[str]
+    ):
         """
         Build a forward relation schema component for 'Out' schema generation.
-        Returns True to treat as plain field, a custom field tuple to include relation schema,
-        or None to skip entirely.
+
+        Parameters
+        ----------
+        field_name : str
+            Name of the relation field.
+        descriptor : Any
+            Django field descriptor (ForwardOneToOneDescriptor, ForwardManyToOneDescriptor).
+        relations_as_id : list[str]
+            Pre-fetched list of fields to serialize as IDs.
+
+        Returns
+        -------
+        True | tuple | None
+            True to treat as plain field, a custom field tuple to include relation schema,
+            or None to skip entirely.
         """
         rel_model = descriptor.field.related_model
 
+        # Handle relations_as_id: serialize as the raw FK ID
+        if field_name in relations_as_id:
+            from ninja_aio.models.utils import ModelUtil
+            pk_field_type = ModelUtil(rel_model).pk_field_type
+            # Use PkFromModel to extract pk from the related instance during serialization
+            return (field_name, PkFromModel[pk_field_type] | None, None)
+
         # Special case: ModelSerializer with no readable fields should be skipped entirely
         if isinstance(rel_model, ModelSerializerMeta):
             if not (
@@ -441,23 +531,44 @@ class BaseSerializer:
         field_name: str,
         model,
         relations_serializers: dict,
+        relations_as_id: list[str],
     ) -> tuple[str | None, tuple | None, tuple | None]:
         """
         Process a single field and determine its classification.
 
-        Returns:
+        Parameters
+        ----------
+        field_name : str
+            Name of the field to process.
+        model : Model
+            Django model class.
+        relations_serializers : dict
+            Mapping of relation field names to serializer classes.
+        relations_as_id : list[str]
+            Pre-fetched list of fields to serialize as IDs.
+
+        Returns
+        -------
+        tuple
             (plain_field, reverse_rel, forward_rel) - only one will be non-None
         """
         field_obj = getattr(model, field_name)
 
         if cls._is_reverse_relation(field_obj):
-            if field_name not in relations_serializers:
+            if (
+                field_name not in relations_serializers
+                and field_name not in relations_as_id
+            ):
                 cls._warn_missing_relation_serializer(field_name, model)
-            rel_tuple = cls._build_schema_reverse_rel(field_name, field_obj)
+            rel_tuple = cls._build_schema_reverse_rel(
+                field_name, field_obj, relations_as_id
+            )
             return (None, rel_tuple, None)
 
         if cls._is_forward_relation(field_obj):
-            rel_tuple = cls._build_schema_forward_rel(field_name, field_obj)
+            rel_tuple = cls._build_schema_forward_rel(
+                field_name, field_obj, relations_as_id
+            )
             if rel_tuple is True:
                 return (field_name, None, None)
             return (None, None, rel_tuple)
@@ -469,8 +580,15 @@ class BaseSerializer:
         """
         Collect components for output schema generation (Out or Detail).
 
-        Returns:
-            tuple: (fields, reverse_rels, excludes, customs_with_forward_rels, optionals)
+        Parameters
+        ----------
+        schema_type : Literal["Out", "Detail"]
+            Type of schema to generate.
+
+        Returns
+        -------
+        tuple
+            (fields, reverse_rels, excludes, customs_with_forward_rels, optionals)
         """
         if schema_type not in ("Out", "Detail"):
             raise ValueError(
@@ -480,6 +598,8 @@ class BaseSerializer:
         fields_type = "read" if schema_type == "Out" else "detail"
         model = cls._get_model()
         relations_serializers = cls._get_relations_serializers() or {}
+        # Fetch once to avoid repeated method calls during field processing
+        relations_as_id = cls._get_relations_as_id()
 
         fields: list[str] = []
         reverse_rels: list[tuple] = []
@@ -487,7 +607,7 @@ class BaseSerializer:
 
         for field_name in cls.get_fields(fields_type):
             plain, reverse, forward = cls._process_field(
-                field_name, model, relations_serializers
+                field_name, model, relations_serializers, relations_as_id
             )
             if plain:
                 fields.append(plain)
@@ -701,12 +821,15 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
             Computed / synthetic output attributes.
         optionals : list[tuple[str, type]]
             Optional output fields.
+        relations_as_id : list[str]
+            Relation fields to serialize as IDs instead of nested objects.
         """
 
         fields: list[str] = []
         customs: list[tuple[str, type, Any]] = []
         optionals: list[tuple[str, type]] = []
         excludes: list[str] = []
+        relations_as_id: list[str] = []
 
     class DetailSerializer:
         """Configuration describing detail (single object) read schema.
@@ -756,6 +879,11 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
         "detail": "DetailSerializer",
     }
 
+    @classmethod
+    def _get_relations_as_id(cls) -> list[str]:
+        """Return relation fields to serialize as IDs instead of nested objects."""
+        return getattr(cls.ReadSerializer, "relations_as_id", [])
+
     @classmethod
     def _get_fields(cls, s_type: type[S_TYPES], f_type: type[F_TYPES]):
         """
@@ -960,6 +1088,12 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         schema_update: Optional[SchemaModelConfig] = None
         schema_detail: Optional[SchemaModelConfig] = None
         relations_serializers: dict[str, "Serializer"] = {}
+        relations_as_id: list[str] = []
+
+    @classmethod
+    def _get_relations_as_id(cls) -> list[str]:
+        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: