django-ninja-aio-crud 2.7.0__tar.gz → 2.9.0__tar.gz

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.9.0}/.github/workflows/docs.yml

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

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.9.0}/PKG-INFO

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

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.9.0}/docs/api/models/model_serializer.md

@@ -145,6 +145,68 @@ 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.
+
+**Fallback Behavior:** If `DetailSerializer` is not defined, `generate_detail_s()` automatically falls back to the read schema (same as `generate_read_s()`). This means you only need to define `DetailSerializer` when you want different fields for single-object retrieval vs list views.
+
+**Attributes:**
+
+| Attribute   | Type                     | Description                                                                   |
+| ----------- | ------------------------ | ----------------------------------------------------------------------------- |
+| `fields`    | `list[str]`              | Model fields to include in detail view (falls back to ReadSerializer fields if not defined) |
+| `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 +256,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 +282,7 @@ class User(ModelSerializer):
 # Auto-generate schemas
 UserCreateSchema = User.generate_create_s()
 UserReadSchema = User.generate_read_s()
+UserDetailSchema = User.generate_detail_s()  # Falls back to read schema if DetailSerializer not defined
 UserUpdateSchema = User.generate_update_s()
 UserRelatedSchema = User.generate_related_s()
 ```

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.9.0}/docs/api/models/model_util.md

@@ -68,7 +68,7 @@ print(util.model_fields)
 
 ### `serializable_fields`
 
-Returns serializable fields (ReadSerializer fields or all model fields).
+Returns serializable fields for read operations (ReadSerializer fields or all model fields).
 
 ```python
 class User(ModelSerializer):
@@ -84,6 +84,27 @@ print(util.serializable_fields)
 # ["id", "username", "email"]  (password excluded)
 ```
 
+### `serializable_detail_fields`
+
+Returns serializable fields for detail operations (DetailSerializer fields, or falls back to ReadSerializer fields).
+
+```python
+class Article(ModelSerializer):
+    title = models.CharField(max_length=200)
+    summary = models.TextField()
+    content = models.TextField()
+
+    class ReadSerializer:
+        fields = ["id", "title", "summary"]
+
+    class DetailSerializer:
+        fields = ["id", "title", "summary", "content"]
+
+util = ModelUtil(Article)
+print(util.serializable_fields)        # ["id", "title", "summary"]
+print(util.serializable_detail_fields) # ["id", "title", "summary", "content"]
+```
+
 ### `model_name`
 
 Returns the Django internal model name.
@@ -118,6 +139,10 @@ class Book(ModelSerializer):
             select_related=["author", "category"],
             prefetch_related=["tags"],
         )
+        detail = ModelQuerySetSchema(
+            select_related=["author", "category", "publisher"],
+            prefetch_related=["tags", "reviews"],
+        )
         queryset_request = ModelQuerySetSchema(
             select_related=[],
             prefetch_related=["related_items"],
@@ -131,9 +156,10 @@ class Book(ModelSerializer):
         ]
 ```
 
-- read: applied to read operations (list/retrieve).
-- queryset_request: applied inside queryset_request hook.
-- extras: named configurations available via QueryUtil.SCOPES.
+- **read**: applied to list operations (`is_for="read"`).
+- **detail**: applied to retrieve operations (`is_for="detail"`). Falls back to `read` if not defined.
+- **queryset_request**: applied inside queryset_request hook.
+- **extras**: named configurations available via QueryUtil.SCOPES.
 
 ## QueryUtil
 
@@ -178,7 +204,7 @@ qs = await ModelUtil(Book).get_objects(
         prefetch_related=["tags"],
     ),
     with_qs_request=True,  # Apply queryset_request hook
-    is_for_read=True,  # union with auto-discovered relations
+    is_for="read",  # union with auto-discovered relations for read
 )
 ```
 
@@ -187,7 +213,7 @@ qs = await ModelUtil(Book).get_objects(
 - `request` (`HttpRequest`): Current HTTP request
 - `query_data` (`ObjectsQuerySchema | None`): Query configuration (filters, select_related, prefetch_related)
 - `with_qs_request` (`bool`): Apply queryset_request hook if available (default: True)
-- `is_for_read` (`bool`): Merge with read-specific optimizations (default: False)
+- `is_for` (`Literal["read", "detail"] | None`): Purpose of the query, determines which serializable fields to use for optimization. Use `"read"` for list operations, `"detail"` for retrieve operations. If `None`, only query_data optimizations are applied. (default: None)
 
 **Returns:** Optimized `QuerySet`
 
@@ -198,13 +224,13 @@ Fetch a single object by pk or getters with optimizations:
 ```python
 from ninja_aio.schemas.helpers import ObjectQuerySchema, QuerySchema
 
-# by pk + select/prefetch
+# by pk + select/prefetch for detail view
 obj = await ModelUtil(Book).get_object(
     request,
     pk=42,
     query_data=ObjectQuerySchema(select_related=["author"]),
     with_qs_request=True,
-    is_for_read=True,
+    is_for="detail",
 )
 
 # by getters (required if pk omitted)
@@ -220,7 +246,7 @@ obj = await ModelUtil(Book).get_object(
 - `pk` (`int | str | None`): Primary key value (optional if getters provided)
 - `query_data` (`ObjectQuerySchema | QuerySchema | None`): Query configuration
 - `with_qs_request` (`bool`): Apply queryset_request hook if available (default: True)
-- `is_for_read` (`bool`): Merge with read-specific optimizations (default: False)
+- `is_for` (`Literal["read", "detail"] | None`): Purpose of the query. Use `"detail"` for single object retrieval, `"read"` for list operations. (default: None)
 
 **Returns:** Model instance
 
@@ -235,16 +261,17 @@ Uniform serialization methods that accept either instances or query data:
 
 ```python
 schema = Book.generate_read_s()
+detail_schema = Book.generate_detail_s()
 
 # single instance
 data = await ModelUtil(Book).read_s(schema, request, instance=obj)
 
-# single via getters
+# single via getters (detail view)
 data = await ModelUtil(Book).read_s(
-    schema,
+    detail_schema,
     request,
     query_data=ObjectQuerySchema(getters={"pk": 42}),
-    is_for_read=True,
+    is_for="detail",
 )
 
 # list from queryset
@@ -255,7 +282,7 @@ items = await ModelUtil(Book).list_read_s(
     schema,
     request,
     query_data=ObjectsQuerySchema(filters={"is_published": True}),
-    is_for_read=True,
+    is_for="read",
 )
 ```
 
@@ -265,7 +292,7 @@ items = await ModelUtil(Book).list_read_s(
 - `request` (`HttpRequest`): Current HTTP request
 - `instance` (`Model | None`): Model instance to serialize (optional)
 - `query_data` (`ObjectQuerySchema | QuerySchema | None`): Query configuration for fetching (optional)
-- `is_for_read` (`bool`): Merge with read-specific optimizations (default: False)
+- `is_for` (`Literal["read", "detail"] | None`): Purpose of the query. Use `"detail"` for single object views, `"read"` for list views. (default: None)
 
 **Parameters (list_read_s):**
 
@@ -273,11 +300,12 @@ items = await ModelUtil(Book).list_read_s(
 - `request` (`HttpRequest`): Current HTTP request
 - `instances` (`QuerySet | list[Model] | None`): Instances to serialize (optional)
 - `query_data` (`ObjectsQuerySchema | None`): Query configuration for fetching (optional)
-- `is_for_read` (`bool`): Merge with read-specific optimizations (default: False)
+- `is_for` (`Literal["read", "detail"] | None`): Purpose of the query. Typically `"read"` for list views. (default: None)
 
 **Behavior:**
 
-- When `is_for_read=True`, select_related and prefetch_related are merged with model-discovered relations
+- When `is_for` is specified, select_related and prefetch_related are merged with model-discovered relations based on the operation type
+- When `is_for="detail"` but no `QuerySet.detail` is configured, falls back to `QuerySet.read` optimizations
 - Passing `instance`/`instances` skips fetching; passing `query_data` fetches automatically
 - Either `instance`/`instances` OR `query_data` must be provided, not both
 

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.9.0}/docs/api/models/serializers.md

@@ -37,7 +37,8 @@ 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, **string reference**, or **Union of serializers** (supports forward/circular dependencies and polymorphic relations)
 
@@ -55,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
@@ -450,12 +475,19 @@ class ArticleSerializer(serializers.Serializer):
         schema_out = serializers.SchemaModelConfig(
             fields=["id", "title", "content", "author", "category"]
         )
+        schema_detail = serializers.SchemaModelConfig(
+            fields=["id", "title", "content", "author", "category", "tags", "comments"]
+        )
 
     class QuerySet:
         read = ModelQuerySetSchema(
             select_related=["author", "category"],
             prefetch_related=["tags"],
         )
+        detail = ModelQuerySetSchema(
+            select_related=["author", "category", "author__profile"],
+            prefetch_related=["tags", "comments", "comments__author"],
+        )
         queryset_request = ModelQuerySetSchema(
             select_related=[],
             prefetch_related=["comments"],
@@ -469,7 +501,12 @@ class ArticleSerializer(serializers.Serializer):
         ]
 ```
 
-The QuerySet configuration is used by ModelUtil to automatically optimize database queries during read operations.
+The QuerySet configuration is used by ModelUtil to automatically optimize database queries:
+
+- **read**: Applied to list operations (`is_for="read"`)
+- **detail**: Applied to retrieve/detail operations (`is_for="detail"`). Falls back to `read` if not defined.
+- **queryset_request**: Applied inside the `queryset_request` hook
+- **extras**: Named configurations available via `QueryUtil.SCOPES`
 
 ## Complete Example
 

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.9.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.7.0 → django_ninja_aio_crud-2.9.0}/ninja_aio/__init__.py

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

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.9.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

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.9.0}/ninja_aio/helpers/query.py

@@ -75,6 +75,9 @@ class QueryUtil:
         self.queryset_request_config: ModelQuerySetSchema = self._configs.get(
             self.SCOPES.QUERYSET_REQUEST, ModelQuerySetSchema()
         )
+        self.detail_config: ModelQuerySetSchema = self._configs.get(
+            self.SCOPES.DETAIL, ModelQuerySetSchema()
+        )
 
     def _get_config(self, conf_name: str) -> ModelQuerySetSchema:
         """Helper method to retrieve configuration attributes."""