django-ninja-aio-crud 2.13.0__tar.gz → 2.15.0__tar.gz

{django_ninja_aio_crud-2.13.0 → django_ninja_aio_crud-2.15.0}/.github/workflows/docs.yml

@@ -25,6 +25,9 @@ on:
           - "2.10"
           - "2.11"
           - "2.12"
+          - "2.13"
+          - "2.14"
+          - "2.15"
       make_latest:
         description: 'Set as "latest" and default?'
         type: boolean
@@ -53,6 +56,9 @@ on:
           - "2.10"
           - "2.11"
           - "2.12"
+          - "2.13"
+          - "2.14"
+          - "2.15"
       delete_confirm:
         description: 'Confirm deletion of the selected version'
         type: boolean

{django_ninja_aio_crud-2.13.0 → django_ninja_aio_crud-2.15.0}/PKG-INFO

@@ -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 → django_ninja_aio_crud-2.15.0}/docs/api/models/model_serializer.md

@@ -100,11 +100,12 @@ Describes how to build a read (output) schema for a model.
 
 **Attributes**
 
-| Attribute  | Type            | Description |
-|-----------|-----------------|-------------|
-| `fields`   | `list[str]`     | **REQUIRED.** Model fields / related names explicitly included in the read (output) schema. |
-| `excludes` | `list[str]`     | Fields / related names to always omit (takes precedence over `fields` and `optionals`). Use for sensitive or noisy data (e.g., passwords, internal flags). |
-| `customs`  | `list[tuple]`   | Computed / synthetic output values. Tuple formats:<br>• `(name, type)` = required resolvable attribute (object attribute or property). Serialization error if not resolvable.<br>• `(name, type, default)` = optional; default may be a callable (`lambda obj: ...`) or a literal value. |
+| Attribute        | Type            | Description |
+|------------------|-----------------|-------------|
+| `fields`         | `list[str]`     | **REQUIRED.** Model fields / related names explicitly included in the read (output) schema. |
+| `excludes`       | `list[str]`     | Fields / related names to always omit (takes precedence over `fields` and `optionals`). Use for sensitive or noisy data (e.g., passwords, internal flags). |
+| `customs`        | `list[tuple]`   | Computed / synthetic output values. Tuple formats:<br>• `(name, type)` = required resolvable attribute (object attribute or property). Serialization error if not resolvable.<br>• `(name, type, default)` = optional; default may be a callable (`lambda obj: ...`) or a literal value. |
+| `relations_as_id`| `list[str]`     | Relation fields to serialize as IDs instead of nested objects. Works with forward FK, forward O2O, reverse FK, reverse O2O, and M2M relations. |
 
 **Example:**
 
@@ -405,6 +406,159 @@ class Book(ModelSerializer):
 }
 ```
 
+#### Relations as ID
+
+Use `relations_as_id` to serialize relation fields as IDs instead of nested objects. This is useful for:
+
+- Reducing response payload size
+- Avoiding circular serialization
+- Performance optimization when nested data isn't needed
+- API designs where clients fetch related data separately
+
+**Supported Relations:**
+
+| Relation Type      | Output Type       | Example Value        |
+|--------------------|-------------------|----------------------|
+| Forward FK         | `PK_TYPE \| None` | `5` or `null`        |
+| Forward O2O        | `PK_TYPE \| None` | `3` or `null`        |
+| Reverse FK         | `list[PK_TYPE]`   | `[1, 2, 3]`          |
+| Reverse O2O        | `PK_TYPE \| None` | `7` or `null`        |
+| M2M (forward)      | `list[PK_TYPE]`   | `[1, 2]`             |
+| M2M (reverse)      | `list[PK_TYPE]`   | `[4, 5, 6]`          |
+
+**Note:** `PK_TYPE` is automatically detected from the related model's primary key field. Supported types include `int` (default), `UUID`, `str`, and any other Django primary key type.
+
+**Example:**
+
+```python
+class Author(ModelSerializer):
+    name = models.CharField(max_length=200)
+
+    class ReadSerializer:
+        fields = ["id", "name", "books"]
+        relations_as_id = ["books"]  # Serialize as list of IDs
+
+class Book(ModelSerializer):
+    title = models.CharField(max_length=200)
+    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name="books")
+
+    class ReadSerializer:
+        fields = ["id", "title", "author"]
+        relations_as_id = ["author"]  # Serialize as ID
+```
+
+**Output (Author):**
+
+```json
+{
+  "id": 1,
+  "name": "J.K. Rowling",
+  "books": [1, 2, 3]
+}
+```
+
+**Output (Book):**
+
+```json
+{
+  "id": 1,
+  "title": "Harry Potter",
+  "author": 1
+}
+```
+
+**M2M Example:**
+
+```python
+class Tag(ModelSerializer):
+    name = models.CharField(max_length=50)
+
+    class ReadSerializer:
+        fields = ["id", "name", "articles"]
+        relations_as_id = ["articles"]  # Reverse M2M as IDs
+
+class Article(ModelSerializer):
+    title = models.CharField(max_length=200)
+    tags = models.ManyToManyField(Tag, related_name="articles")
+
+    class ReadSerializer:
+        fields = ["id", "title", "tags"]
+        relations_as_id = ["tags"]  # Forward M2M as IDs
+```
+
+**Output (Article):**
+
+```json
+{
+  "id": 1,
+  "title": "Getting Started with Django",
+  "tags": [1, 2, 5]
+}
+```
+
+**UUID Primary Key Example:**
+
+When models use UUID primary keys, the output type is automatically `UUID`:
+
+```python
+import uuid
+from django.db import models
+from ninja_aio.models import ModelSerializer
+
+class Author(ModelSerializer):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(max_length=200)
+
+    class ReadSerializer:
+        fields = ["id", "name", "books"]
+        relations_as_id = ["books"]
+
+class Book(ModelSerializer):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    title = models.CharField(max_length=200)
+    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name="books")
+
+    class ReadSerializer:
+        fields = ["id", "title", "author"]
+        relations_as_id = ["author"]
+```
+
+**Output (Author with UUID):**
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "J.K. Rowling",
+  "books": [
+    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+    "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
+  ]
+}
+```
+
+**Output (Book with UUID):**
+
+```json
+{
+  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+  "title": "Harry Potter",
+  "author": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+**Query Optimization Note:** When using `relations_as_id`, you should still use `select_related()` for forward relations and `prefetch_related()` for reverse/M2M relations to avoid N+1 queries:
+
+```python
+class Article(ModelSerializer):
+    # ...
+
+    class QuerySet:
+        read = ModelQuerySetSchema(
+            select_related=["author"],       # For forward FK
+            prefetch_related=["tags"],        # For M2M
+        )
+```
+
 ## Async Extension Points
 
 ### `queryset_request(request)`

{django_ninja_aio_crud-2.13.0 → django_ninja_aio_crud-2.15.0}/docs/api/models/serializers.md

@@ -41,6 +41,7 @@ Define a Serializer subclass with a nested Meta:
 - **schema_detail**: SchemaModelConfig for detail outputs (retrieve endpoint)
 - **schema_update**: SchemaModelConfig for patch/update inputs
 - **relations_serializers**: Mapping of relation field name -> Serializer class, **string reference**, or **Union of serializers** (supports forward/circular dependencies and polymorphic relations)
+- **relations_as_id**: List of relation field names to serialize as IDs instead of nested objects
 
 SchemaModelConfig fields:
 
@@ -415,6 +416,170 @@ Notes:
 - Union types are resolved lazily, so forward and circular references work seamlessly.
 - The schema generator will create a union of all possible schemas from the serializers in the Union.
 
+## Relations as ID
+
+Use `relations_as_id` in Meta to serialize relation fields as IDs instead of nested objects. This is useful for:
+
+- Reducing response payload size
+- Avoiding circular serialization
+- Performance optimization when nested data isn't needed
+- API designs where clients fetch related data separately
+
+**Supported Relations:**
+
+| Relation Type      | Output Type       | Example Value        |
+|--------------------|-------------------|----------------------|
+| Forward FK         | `PK_TYPE \| None` | `5` or `null`        |
+| Forward O2O        | `PK_TYPE \| None` | `3` or `null`        |
+| Reverse FK         | `list[PK_TYPE]`   | `[1, 2, 3]`          |
+| Reverse O2O        | `PK_TYPE \| None` | `7` or `null`        |
+| M2M (forward)      | `list[PK_TYPE]`   | `[1, 2]`             |
+| M2M (reverse)      | `list[PK_TYPE]`   | `[4, 5, 6]`          |
+
+**Note:** `PK_TYPE` is automatically detected from the related model's primary key field. Supported types include `int` (default), `UUID`, `str`, and any other Django primary key type.
+
+**Example:**
+
+```python
+from ninja_aio.models import serializers
+from . import models
+
+class AuthorSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Author
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "name", "books"]
+        )
+        relations_as_id = ["books"]  # Serialize reverse FK as list of IDs
+
+class BookSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Book
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "author"]
+        )
+        relations_as_id = ["author"]  # Serialize forward FK as ID
+```
+
+**Output (Author):**
+
+```json
+{
+  "id": 1,
+  "name": "J.K. Rowling",
+  "books": [1, 2, 3]
+}
+```
+
+**Output (Book):**
+
+```json
+{
+  "id": 1,
+  "title": "Harry Potter",
+  "author": 1
+}
+```
+
+**M2M Example:**
+
+```python
+class TagSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Tag
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "name", "articles"]
+        )
+        relations_as_id = ["articles"]  # Reverse M2M as list of IDs
+
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "tags"]
+        )
+        relations_as_id = ["tags"]  # Forward M2M as list of IDs
+```
+
+**Output (Article):**
+
+```json
+{
+  "id": 1,
+  "title": "Getting Started with Django",
+  "tags": [1, 2, 5]
+}
+```
+
+**UUID Primary Key Example:**
+
+When related models use UUID primary keys, the output type is automatically `UUID`:
+
+```python
+import uuid
+from django.db import models
+
+class Author(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(max_length=200)
+
+class AuthorSerializer(serializers.Serializer):
+    class Meta:
+        model = Author
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "name", "books"]
+        )
+        relations_as_id = ["books"]
+```
+
+**Output (Author with UUID):**
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "J.K. Rowling",
+  "books": [
+    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+    "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
+  ]
+}
+```
+
+**Combining with relations_serializers:**
+
+You can use both `relations_as_id` and `relations_serializers` in the same serializer. Fields in `relations_as_id` take precedence:
+
+```python
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "author", "tags", "category"]
+        )
+        relations_serializers = {
+            "author": AuthorSerializer,      # Nested object
+            "category": CategorySerializer,  # Nested object
+        }
+        relations_as_id = ["tags"]           # Just IDs
+```
+
+**Query Optimization Note:** When using `relations_as_id`, you should still use `select_related()` for forward relations and `prefetch_related()` for reverse/M2M relations to avoid N+1 queries:
+
+```python
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "author", "tags"]
+        )
+        relations_as_id = ["author", "tags"]
+
+    class QuerySet:
+        read = ModelQuerySetSchema(
+            select_related=["author"],       # For forward FK
+            prefetch_related=["tags"],        # For M2M
+        )
+
 ## Using with APIViewSet
 
 You can attach a Serializer to an APIViewSet to auto-generate schemas and leverage queryset_request when present:

{django_ninja_aio_crud-2.13.0 → django_ninja_aio_crud-2.15.0}/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
 

{django_ninja_aio_crud-2.13.0 → django_ninja_aio_crud-2.15.0}/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: