django-ninja-aio-crud 2.6.1__tar.gz → 2.8.0__tar.gz

{django_ninja_aio_crud-2.6.1 → django_ninja_aio_crud-2.8.0}/.github/workflows/docs.yml

@@ -18,6 +18,8 @@ on:
           - "2.4"
           - "2.5"
           - "2.6"
+          - "2.6.1"
+          - "2.7.0"
       make_latest:
         description: 'Set as "latest" and default?'
         type: boolean
@@ -39,6 +41,8 @@ on:
           - "2.4"
           - "2.5"
           - "2.6"
+          - "2.6.1"
+          - "2.7.0"
       delete_confirm:
         description: 'Confirm deletion of the selected version'
         type: boolean

{django_ninja_aio_crud-2.6.1 → django_ninja_aio_crud-2.8.0}/PKG-INFO

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

{django_ninja_aio_crud-2.6.1 → django_ninja_aio_crud-2.8.0}/docs/api/models/model_serializer.md

@@ -145,6 +145,66 @@ class User(ModelSerializer):
 }
 ```
 
+### DetailSerializer
+
+Describes how to build a detail (single object) output schema. Use this when you want the retrieve endpoint to return more fields than the list endpoint.
+
+**Attributes:**
+
+| Attribute   | Type                     | Description                                                                   |
+| ----------- | ------------------------ | ----------------------------------------------------------------------------- |
+| `fields`    | `list[str]`              | Model fields to include in detail view                                        |
+| `excludes`  | `list[str]`              | Fields to exclude from detail view                                            |
+| `customs`   | `list[tuple]`            | Computed fields: `(name, type)` required; `(name, type, default)` optional    |
+| `optionals` | `list[tuple[str, type]]` | Optional output fields                                                        |
+
+**Example:**
+
+```python
+class Article(ModelSerializer):
+    title = models.CharField(max_length=200)
+    summary = models.TextField()
+    content = models.TextField()
+    author = models.ForeignKey(User, on_delete=models.CASCADE)
+    tags = models.ManyToManyField(Tag)
+    view_count = models.IntegerField(default=0)
+
+    class ReadSerializer:
+        # List view: minimal fields for performance
+        fields = ["id", "title", "summary", "author"]
+
+    class DetailSerializer:
+        # Detail view: all fields including expensive relations
+        fields = ["id", "title", "summary", "content", "author", "tags", "view_count"]
+        customs = [
+            ("reading_time", int, lambda obj: len(obj.content.split()) // 200),
+        ]
+```
+
+**Generated Output (List):**
+
+```json
+[
+  {"id": 1, "title": "Getting Started", "summary": "...", "author": {...}},
+  {"id": 2, "title": "Advanced Topics", "summary": "...", "author": {...}}
+]
+```
+
+**Generated Output (Detail):**
+
+```json
+{
+  "id": 1,
+  "title": "Getting Started",
+  "summary": "...",
+  "content": "Full article content here...",
+  "author": {...},
+  "tags": [{"id": 1, "name": "python"}, {"id": 2, "name": "django"}],
+  "view_count": 1234,
+  "reading_time": 5
+}
+```
+
 ### UpdateSerializer
 
 Describes how to build an update (partial/full) input schema.
@@ -194,14 +254,15 @@ class User(ModelSerializer):
 
 ### Auto-Generated Schemas
 
-ModelSerializer automatically generates four schema types:
+ModelSerializer automatically generates five schema types:
 
-| Method                     | Schema Type        | Purpose                        |
-| -------------------------- | ------------------ | ------------------------------ |
-| `generate_create_s()`      | Input ("In")       | POST endpoint payload          |
-| `generate_update_s()`      | Input ("Patch")    | PATCH/PUT endpoint payload     |
-| `generate_read_s(depth=1)` | Output ("Out")     | Response with nested relations |
-| `generate_related_s()`     | Output ("Related") | Compact nested representation  |
+| Method                       | Schema Type        | Purpose                              |
+| ---------------------------- | ------------------ | ------------------------------------ |
+| `generate_create_s()`        | Input ("In")       | POST endpoint payload                |
+| `generate_update_s()`        | Input ("Patch")    | PATCH/PUT endpoint payload           |
+| `generate_read_s(depth=1)`   | Output ("Out")     | List response with nested relations  |
+| `generate_detail_s(depth=1)` | Output ("Detail")  | Single object response (retrieve)    |
+| `generate_related_s()`       | Output ("Related") | Compact nested representation        |
 
 **Example:**
 
@@ -219,6 +280,7 @@ class User(ModelSerializer):
 # Auto-generate schemas
 UserCreateSchema = User.generate_create_s()
 UserReadSchema = User.generate_read_s()
+UserDetailSchema = User.generate_detail_s()  # Returns None if DetailSerializer not defined
 UserUpdateSchema = User.generate_update_s()
 UserRelatedSchema = User.generate_related_s()
 ```

{django_ninja_aio_crud-2.6.1 → django_ninja_aio_crud-2.8.0}/docs/api/models/serializers.md

@@ -20,7 +20,7 @@ While both `ModelSerializer` and `Serializer` provide schema generation and CRUD
 | Schema generation        | On-demand via generate_*() methods  | On-demand via generate_*() methods            |
 | Usage                    | Inherit from ModelSerializer        | Separate serializer class                     |
 | Query optimization       | QuerySet nested class               | QuerySet nested class (inherited)             |
-| Relation serializers     | Auto-resolved                       | Explicit via relations_serializers (supports string refs) |
+| Relation serializers     | Auto-resolved                       | Explicit via relations_serializers (supports string refs & Union) |
 
 ## Key points
 
@@ -28,6 +28,7 @@ While both `ModelSerializer` and `Serializer` provide schema generation and CRUD
 - Generates read/create/update/related schemas on demand via ninja.orm.create_schema.
 - Supports explicit relation serializers for forward and reverse relations.
 - **Supports string references in `relations_serializers` for forward/circular dependencies**.
+- **Supports Union types for polymorphic relations** (e.g., generic foreign keys, content types).
 - Plays nicely with APIViewSet to auto-wire schemas and queryset handling.
 
 ## Configuration
@@ -36,9 +37,10 @@ Define a Serializer subclass with a nested Meta:
 
 - **model**: Django model class
 - **schema_in**: SchemaModelConfig for create inputs
-- **schema_out**: SchemaModelConfig for read outputs
+- **schema_out**: SchemaModelConfig for read outputs (list endpoint)
+- **schema_detail**: SchemaModelConfig for detail outputs (retrieve endpoint)
 - **schema_update**: SchemaModelConfig for patch/update inputs
-- **relations_serializers**: Mapping of relation field name -> Serializer class **or string reference** (for forward/circular dependencies)
+- **relations_serializers**: Mapping of relation field name -> Serializer class, **string reference**, or **Union of serializers** (supports forward/circular dependencies and polymorphic relations)
 
 SchemaModelConfig fields:
 
@@ -54,13 +56,37 @@ Generate schemas explicitly using these methods:
 ```python
 # Explicitly generate schemas when needed
 ArticleSerializer.generate_create_s()  # Returns create (In) schema
-ArticleSerializer.generate_read_s()    # Returns read (Out) schema
+ArticleSerializer.generate_read_s()    # Returns read (Out) schema for list endpoint
+ArticleSerializer.generate_detail_s()  # Returns detail (Out) schema for retrieve endpoint
 ArticleSerializer.generate_update_s()  # Returns update (Patch) schema
 ArticleSerializer.generate_related_s() # Returns related (nested) schema
 ```
 
 Schemas support **forward references and circular dependencies** via string references in `relations_serializers`.
 
+### Detail Schema for Retrieve Endpoint
+
+Use `schema_detail` when you want the retrieve endpoint to return more fields than the list endpoint:
+
+```python
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_out = serializers.SchemaModelConfig(
+            # List view: minimal fields for performance
+            fields=["id", "title", "summary"]
+        )
+        schema_detail = serializers.SchemaModelConfig(
+            # Detail view: all fields including expensive relations
+            fields=["id", "title", "summary", "content", "author", "tags"],
+            customs=[("reading_time", int, lambda obj: len(obj.content.split()) // 200)]
+        )
+```
+
+When used with `APIViewSet`:
+- **List endpoint** (`GET /articles/`) uses `schema_out`
+- **Retrieve endpoint** (`GET /articles/{pk}`) uses `schema_detail` (falls back to `schema_out` if not defined)
+
 ## Example: simple FK
 
 ```python
@@ -180,16 +206,191 @@ class ArticleSerializer(serializers.Serializer):
         }
 ```
 
+**String Reference Formats:**
+
+1. **Class name in the same module:**
+   ```python
+   relations_serializers = {
+       "articles": "ArticleSerializer",  # Resolved in current module
+   }
+   ```
+
+2. **Absolute import path:**
+   ```python
+   relations_serializers = {
+       "articles": "myapp.serializers.ArticleSerializer",  # Full import path
+   }
+   ```
+
 **String Reference Requirements:**
-- String must be the class name of a serializer in the same module
+- String can be the class name of a serializer in the same module, or an absolute import path
+- Absolute paths use dot notation: `"package.module.ClassName"`
 - References are resolved lazily when schemas are generated
 - Both forward and circular references are supported
 
+**Example: Cross-Module References with Absolute Paths**
+
+```python
+# myapp/serializers.py
+from ninja_aio.models import serializers
+from . import models
+
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "author"]
+        )
+        relations_serializers = {
+            # Reference a serializer from another module
+            "author": "users.serializers.UserSerializer",
+        }
+
+# users/serializers.py
+from ninja_aio.models import serializers
+from . import models
+
+class UserSerializer(serializers.Serializer):
+    class Meta:
+        model = models.User
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "username", "email", "articles"]
+        )
+        relations_serializers = {
+            # Reference back to the article serializer
+            "articles": "myapp.serializers.ArticleSerializer",
+        }
+```
+
+## Union Types for Polymorphic Relations
+
+You can use `Union` types in `relations_serializers` to handle polymorphic relationships where a field can reference multiple possible serializer types. This is particularly useful for generic foreign keys, content types, or any scenario where a relation can point to different model types.
+
+```python
+from typing import Union
+from ninja_aio.models import serializers
+from . import models
+
+class VideoSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Video
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "duration", "url"]
+        )
+
+class ImageSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Image
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "width", "height", "url"]
+        )
+
+class CommentSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Comment
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "text", "content_object"]
+        )
+        relations_serializers = {
+            # content_object can be a Video or Image
+            "content_object": Union[VideoSerializer, ImageSerializer],
+        }
+```
+
+**Union Type Formats:**
+
+1. **Direct class references:**
+   ```python
+   relations_serializers = {
+       "field": Union[SerializerA, SerializerB],
+   }
+   ```
+
+2. **String references:**
+   ```python
+   relations_serializers = {
+       "field": Union["SerializerA", "SerializerB"],
+   }
+   ```
+
+3. **Mixed class and string references:**
+   ```python
+   relations_serializers = {
+       "field": Union[SerializerA, "SerializerB"],
+   }
+   ```
+
+4. **Absolute import paths:**
+   ```python
+   relations_serializers = {
+       "field": Union["myapp.serializers.SerializerA", SerializerB],
+   }
+   ```
+
+**Use Cases for Union Types:**
+
+- **Polymorphic relations:** Generic foreign keys or Django ContentType relations
+- **Flexible APIs:** Different response formats for the same field based on runtime type
+- **Gradual migrations:** Transitioning between different serializer implementations
+- **Multi-tenant systems:** Different serialization requirements per tenant
+
+**Complete Polymorphic Example:**
+
+```python
+from typing import Union
+from django.contrib.contenttypes.fields import GenericForeignKey
+from ninja_aio.models import serializers
+
+# Models
+class Comment(models.Model):
+    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
+    object_id = models.PositiveIntegerField()
+    content_object = GenericForeignKey('content_type', 'object_id')
+    text = models.TextField()
+
+# Serializers for different content types
+class BlogPostSerializer(serializers.Serializer):
+    class Meta:
+        model = models.BlogPost
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "body", "published_at"]
+        )
+
+class ProductSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Product
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "name", "price", "stock"]
+        )
+
+class EventSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Event
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "name", "date", "location"]
+        )
+
+# Comment serializer with Union support
+class CommentSerializer(serializers.Serializer):
+    class Meta:
+        model = Comment
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "text", "created_at", "content_object"]
+        )
+        relations_serializers = {
+            # Comments can be on blog posts, products, or events
+            "content_object": Union[BlogPostSerializer, ProductSerializer, EventSerializer],
+        }
+```
+
 Notes:
 
 - Forward relations are included as plain fields unless a related ModelSerializer/Serializer is declared.
 - Reverse relations require an entry in relations_serializers when using vanilla Django models.
 - When the related model is a ModelSerializer, related schemas can be auto-resolved.
+- Absolute import paths are useful for cross-module references and avoiding circular import issues at module load time.
+- 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.
 
 ## Using with APIViewSet
 

{django_ninja_aio_crud-2.6.1 → django_ninja_aio_crud-2.8.0}/docs/api/views/api_view_set.md

@@ -4,13 +4,13 @@
 
 ## Generated CRUD Endpoints
 
-| Method | Path            | Summary        | Response                           |
-| ------ | --------------- | -------------- | ---------------------------------- |
-| POST   | `/{base}/`      | Create Model   | `201 schema_out`                   |
-| GET    | `/{base}/`      | List Models    | `200 List[schema_out]` (paginated) |
-| GET    | `/{base}/{pk}`  | Retrieve Model | `200 schema_out`                   |
-| PATCH  | `/{base}/{pk}/` | Update Model   | `200 schema_out`                   |
-| DELETE | `/{base}/{pk}/` | Delete Model   | `204 No Content`                   |
+| Method | Path            | Summary        | Response                                      |
+| ------ | --------------- | -------------- | --------------------------------------------- |
+| POST   | `/{base}/`      | Create Model   | `201 schema_out`                              |
+| GET    | `/{base}/`      | List Models    | `200 List[schema_out]` (paginated)            |
+| GET    | `/{base}/{pk}`  | Retrieve Model | `200 schema_detail` (or `schema_out` if none) |
+| PATCH  | `/{base}/{pk}/` | Update Model   | `200 schema_out`                              |
+| DELETE | `/{base}/{pk}/` | Delete Model   | `204 No Content`                              |
 
 Notes:
 
@@ -100,7 +100,8 @@ class ArticleViewSet(APIViewSet):
 | `api`                       | `NinjaAPI`                    | —                                                  | API instance (required)                                                 |
 | `serializer_class`          | `Serializer \| None`          | `None`                                             | Serializer class for plain models (alternative to ModelSerializer)      |
 | `schema_in`                 | `Schema \| None`              | `None` (auto)                                      | Create input schema override                                            |
-| `schema_out`                | `Schema \| None`              | `None` (auto)                                      | Read/output schema override                                             |
+| `schema_out`                | `Schema \| None`              | `None` (auto)                                      | List/output schema override                                             |
+| `schema_detail`             | `Schema \| None`              | `None` (auto)                                      | Retrieve/detail schema override (falls back to `schema_out`)            |
 | `schema_update`             | `Schema \| None`              | `None` (auto)                                      | Update input schema override                                            |
 | `pagination_class`          | `type[AsyncPaginationBase]`   | `PageNumberPagination`                             | Pagination strategy                                                     |
 | `query_params`              | `dict[str, tuple[type, ...]]` | `{}`                                               | List endpoint filters definition                                        |
@@ -150,6 +151,7 @@ The transaction behavior is applied by default. Custom decorators can be added v
 If `model` is a subclass of `ModelSerializerMeta`:
 
 - `schema_out` is generated from `ReadSerializer`
+- `schema_detail` is generated from `DetailSerializer` (optional, falls back to `schema_out`)
 - `schema_in` from `CreateSerializer`
 - `schema_update` from `UpdateSerializer`
 
@@ -173,7 +175,42 @@ class ArticleViewSet(APIViewSet):
     serializer_class = ArticleSerializer
 ```
 
-Otherwise provide schemas manually via `schema_in`, `schema_out`, and `schema_update` attributes.
+Otherwise provide schemas manually via `schema_in`, `schema_out`, `schema_detail`, and `schema_update` attributes.
+
+### Detail Schema for Retrieve Endpoint
+
+Use `schema_detail` (or `DetailSerializer` on ModelSerializer) when you want the retrieve endpoint to return more fields than the list endpoint. This is useful for:
+
+- **Performance optimization**: List endpoints return minimal fields, retrieve endpoints include expensive relations
+- **API design**: Clients get a summary in lists and full details on individual requests
+
+```python
+from ninja_aio.models import ModelSerializer
+from django.db import models
+
+class Article(ModelSerializer):
+    title = models.CharField(max_length=200)
+    summary = models.TextField()
+    content = models.TextField()
+    author = models.ForeignKey(User, on_delete=models.CASCADE)
+    tags = models.ManyToManyField(Tag)
+
+    class ReadSerializer:
+        # List view: minimal fields
+        fields = ["id", "title", "summary"]
+
+    class DetailSerializer:
+        # Detail view: all fields
+        fields = ["id", "title", "summary", "content", "author", "tags"]
+
+@api.viewset(model=Article)
+class ArticleViewSet(APIViewSet):
+    pass  # Schemas auto-generated from model
+```
+
+Endpoints behavior:
+- `GET /articles/` returns `[{"id": 1, "title": "...", "summary": "..."}, ...]`
+- `GET /articles/1` returns `{"id": 1, "title": "...", "summary": "...", "content": "...", "author": {...}, "tags": [...]}`
 
 ## List Filtering
 
@@ -254,6 +291,7 @@ Relations are declared via `M2MRelationSchema` objects (not tuples). Each schema
 - `get`: enable GET listing (bool)
 - `filters`: dict of `{param_name: (type, default)}` for relation-level filtering
 - `related_schema`: optional pre-built schema for the related model (auto-generated if the `model` is a `ModelSerializer`)
+- `serializer_class`: optional `Serializer` class for plain Django models. When provided, `related_schema` is auto-generated from the serializer. Cannot be used when `model` is a `ModelSerializer`.
 - `append_slash`: bool to control trailing slash for the GET relation endpoint path. Defaults to `False` (no trailing slash) for backward compatibility. When `True`, the GET path ends with a trailing slash.
 
 If `path` is empty it falls back to the related model verbose name (lowercase plural).
@@ -285,21 +323,43 @@ async def tags_query_params_handler(self, queryset, filters_dict):
 
 Warning: Model support
 
-- You can supply a standard Django `Model` (not a `ModelSerializer`) in `M2MRelationSchema.model`. When doing so you must provide `related_schema` manually:
+- You can supply a standard Django `Model` (not a `ModelSerializer`) in `M2MRelationSchema.model`. When doing so you must provide either `related_schema` manually or `serializer_class`:
 
-```python
-M2MRelationSchema(
-    model=Tag,                # plain django.db.models.Model
-    related_name="tags",
-    related_schema=TagOut,    # a Pydantic/Ninja Schema you define
-    add=True,
-    remove=True,
-    get=True,
-)
-```
+=== "With related_schema"
+    ```python
+    M2MRelationSchema(
+        model=Tag,                # plain django.db.models.Model
+        related_name="tags",
+        related_schema=TagOut,    # a Pydantic/Ninja Schema you define
+        add=True,
+        remove=True,
+        get=True,
+    )
+    ```
+
+=== "With serializer_class"
+    ```python
+    from ninja_aio.models import serializers
+
+    class TagSerializer(serializers.Serializer):
+        class Meta:
+            model = Tag
+            schema_out = serializers.SchemaModelConfig(fields=["id", "name"])
+
+    M2MRelationSchema(
+        model=Tag,                        # plain django.db.models.Model
+        related_name="tags",
+        serializer_class=TagSerializer,   # auto-generates related_schema
+        add=True,
+        remove=True,
+        get=True,
+    )
+    ```
 
 For `ModelSerializer` models, `related_schema` can be inferred automatically (via internal helpers).
 
+Note: You cannot use `serializer_class` when `model` is already a `ModelSerializer` - this will raise a `ValueError`.
+
 Example with filters:
 
 ```python

{django_ninja_aio_crud-2.6.1 → django_ninja_aio_crud-2.8.0}/ninja_aio/__init__.py

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

{django_ninja_aio_crud-2.6.1 → django_ninja_aio_crud-2.8.0}/ninja_aio/helpers/api.py

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