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

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

@@ -20,6 +20,9 @@ on:
           - "2.6"
           - "2.6.1"
           - "2.7.0"
+          - "2.8"
+          - "2.9"
+          - "2.10"
       make_latest:
         description: 'Set as "latest" and default?'
         type: boolean
@@ -43,6 +46,9 @@ on:
           - "2.6"
           - "2.6.1"
           - "2.7.0"
+          - "2.8"
+          - "2.9"
+          - "2.10"
       delete_confirm:
         description: 'Confirm deletion of the selected version'
         type: boolean

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

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

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

@@ -149,11 +149,13 @@ class User(ModelSerializer):
 
 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                                        |
+| `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                                                        |
@@ -280,7 +282,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
+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.8.0 → django_ninja_aio_crud-2.10.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.8.0 → django_ninja_aio_crud-2.10.0}/docs/api/models/serializers.md

@@ -475,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"],
@@ -494,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.8.0 → django_ninja_aio_crud-2.10.0}/docs/api/views/mixins.md

@@ -140,6 +140,49 @@ class EventViewSet(LessEqualDateFilterViewSetMixin, APIViewSet):
     query_params = {"created_at": (datetime, None)}
 ```
 
+## RelationFilterViewSetMixin
+
+Filters by related model fields using configurable `RelationFilterSchema` entries.
+
+- Behavior: Maps query parameters to Django ORM lookups on related models.
+- Configuration: Define `relations_filters` as a list of `RelationFilterSchema` objects.
+- Query params are automatically registered from `relations_filters`.
+
+Each `RelationFilterSchema` requires:
+
+- `query_param`: The API query parameter name exposed to clients.
+- `query_filter`: The Django ORM lookup path (e.g., `author__id`, `category__name__icontains`).
+- `filter_type`: Tuple of `(type, default)` for schema generation (e.g., `(int, None)`).
+
+Example:
+
+```python
+from ninja_aio.views.mixins import RelationFilterViewSetMixin
+from ninja_aio.views.api import APIViewSet
+from ninja_aio.schemas import RelationFilterSchema
+
+class BookViewSet(RelationFilterViewSetMixin, APIViewSet):
+    model = models.Book
+    api = api
+    relations_filters = [
+        RelationFilterSchema(
+            query_param="author",
+            query_filter="author__id",
+            filter_type=(int, None),
+        ),
+        RelationFilterSchema(
+            query_param="category_name",
+            query_filter="category__name__icontains",
+            filter_type=(str, None),
+        ),
+    ]
+```
+
+This enables:
+
+- `GET /books?author=5` → `queryset.filter(author__id=5)`
+- `GET /books?category_name=fiction` → `queryset.filter(category__name__icontains="fiction")`
+
 ## Tips
 
 - Align `query_params` types with expected filter values; prefer Pydantic `date`/`datetime` for date filters so values implement `isoformat`.

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

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

{django_ninja_aio_crud-2.8.0 → django_ninja_aio_crud-2.10.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."""

{django_ninja_aio_crud-2.8.0 → django_ninja_aio_crud-2.10.0}/ninja_aio/models/serializers.py

@@ -61,6 +61,7 @@ class BaseSerializer:
         """
 
         read = ModelQuerySetSchema()
+        detail = ModelQuerySetSchema()
         queryset_request = ModelQuerySetSchema()
         extras: list[ModelQuerySetExtraSchema] = []
 
@@ -325,14 +326,18 @@ class BaseSerializer:
         ]
 
     @classmethod
-    def get_excluded_fields(cls, s_type: type[S_TYPES]):
+    def get_excluded_fields(cls, s_type: S_TYPES):
         """Return excluded field names for the serializer type."""
         return cls._get_fields(s_type, "excludes")
 
     @classmethod
-    def get_fields(cls, s_type: type[S_TYPES]):
+    def get_fields(cls, s_type: S_TYPES):
         """Return explicit declared fields for the serializer type."""
-        return cls._get_fields(s_type, "fields")
+        fields = cls._get_fields(s_type, "fields")
+        # Detail schema falls back to read fields if none declared
+        if not fields and s_type == "detail":
+            return cls._get_fields("read", "fields")
+        return fields
 
     @classmethod
     def is_custom(cls, field: str) -> bool:
@@ -406,7 +411,11 @@ class BaseSerializer:
         """Check if field is a reverse relation (M2M, reverse FK, reverse O2O)."""
         return isinstance(
             field_obj,
-            (ManyToManyDescriptor, ReverseManyToOneDescriptor, ReverseOneToOneDescriptor),
+            (
+                ManyToManyDescriptor,
+                ReverseManyToOneDescriptor,
+                ReverseOneToOneDescriptor,
+            ),
         )
 
     @classmethod
@@ -419,9 +428,8 @@ class BaseSerializer:
     @classmethod
     def _warn_missing_relation_serializer(cls, field_name: str, model) -> None:
         """Emit warning for reverse relations without explicit serializer mapping."""
-        if (
-            not isinstance(model, ModelSerializerMeta)
-            and not getattr(settings, "NINJA_AIO_TESTING", False)
+        if not isinstance(model, ModelSerializerMeta) and not getattr(
+            settings, "NINJA_AIO_TESTING", False
         ):
             warnings.warn(
                 f"{cls.__name__}: reverse relation '{field_name}' is listed in read fields "
@@ -469,7 +477,9 @@ class BaseSerializer:
             tuple: (fields, reverse_rels, excludes, customs_with_forward_rels, optionals)
         """
         if schema_type not in ("Out", "Detail"):
-            raise ValueError("get_schema_out_data only supports 'Out' or 'Detail' types")
+            raise ValueError(
+                "get_schema_out_data only supports 'Out' or 'Detail' types"
+            )
 
         fields_type = "read" if schema_type == "Out" else "detail"
         model = cls._get_model()
@@ -602,7 +612,7 @@ class BaseSerializer:
     @classmethod
     def generate_detail_s(cls, depth: int = 1) -> Schema:
         """Generate detail (single object Out) schema."""
-        return cls._generate_model_schema("Detail", depth)
+        return cls._generate_model_schema("Detail", depth) or cls.generate_read_s(depth)
 
     @classmethod
     def generate_create_s(cls) -> Schema: