django-ninja-aio-crud 2.11.1__tar.gz → 2.12.0__tar.gz

{django_ninja_aio_crud-2.11.1 → django_ninja_aio_crud-2.12.0}/PKG-INFO

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

{django_ninja_aio_crud-2.11.1 → django_ninja_aio_crud-2.12.0}/docs/api/models/model_serializer.md

@@ -149,16 +149,23 @@ 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.
+**Fallback Behavior:** `DetailSerializer` supports **per-field-type fallback** to `ReadSerializer`. Each attribute (`fields`, `customs`, `optionals`, `excludes`) is checked independently:
+
+- If `DetailSerializer.fields` is empty → uses `ReadSerializer.fields`
+- If `DetailSerializer.customs` is empty → uses `ReadSerializer.customs`
+- If `DetailSerializer.optionals` is empty → uses `ReadSerializer.optionals`
+- If `DetailSerializer.excludes` is empty → uses `ReadSerializer.excludes`
+
+This allows partial overrides: define only `DetailSerializer.fields` while inheriting `customs` from `ReadSerializer`.
 
 **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                                                        |
+| `fields`    | `list[str]`              | Model fields to include in detail view (falls back to ReadSerializer.fields if empty) |
+| `excludes`  | `list[str]`              | Fields to exclude from detail view (falls back to ReadSerializer.excludes if empty) |
+| `customs`   | `list[tuple]`            | Computed fields: `(name, type)` required; `(name, type, default)` optional (falls back to ReadSerializer.customs if empty) |
+| `optionals` | `list[tuple[str, type]]` | Optional output fields (falls back to ReadSerializer.optionals if empty) |
 
 **Example:**
 
@@ -174,21 +181,22 @@ class Article(ModelSerializer):
     class ReadSerializer:
         # List view: minimal fields for performance
         fields = ["id", "title", "summary", "author"]
+        customs = [
+            ("word_count", int, lambda obj: len(obj.content.split())),
+        ]
 
     class DetailSerializer:
         # Detail view: all fields including expensive relations
+        # customs inherited from ReadSerializer (word_count)
         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": {...}}
+  {"id": 1, "title": "Getting Started", "summary": "...", "author": {...}, "word_count": 500},
+  {"id": 2, "title": "Advanced Topics", "summary": "...", "author": {...}, "word_count": 1200}
 ]
 ```
 
@@ -203,10 +211,26 @@ class Article(ModelSerializer):
   "author": {...},
   "tags": [{"id": 1, "name": "python"}, {"id": 2, "name": "django"}],
   "view_count": 1234,
-  "reading_time": 5
+  "word_count": 500
 }
 ```
 
+**Example with Custom Override:**
+
+```python
+class Article(ModelSerializer):
+    # ... fields ...
+
+    class ReadSerializer:
+        fields = ["id", "title", "summary"]
+        customs = [("word_count", int, lambda obj: len(obj.content.split()))]
+
+    class DetailSerializer:
+        fields = ["id", "title", "summary", "content"]
+        # Override customs - reading_time instead of word_count
+        customs = [("reading_time", int, lambda obj: len(obj.content.split()) // 200)]
+```
+
 ### UpdateSerializer
 
 Describes how to build an update (partial/full) input schema.

{django_ninja_aio_crud-2.11.1 → django_ninja_aio_crud-2.12.0}/docs/api/models/serializers.md

@@ -87,6 +87,29 @@ 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)
 
+**Fallback Behavior:** Unlike `ModelSerializer`, `Serializer` uses **schema-level fallback**:
+
+- If `schema_detail` is **not defined** → all field types (`fields`, `customs`, `optionals`, `exclude`) fall back to `schema_out`
+- If `schema_detail` **is defined** → no inheritance from `schema_out`, even for empty field types
+
+This means you must explicitly define all needed configurations in `schema_detail` if you define it at all:
+
+```python
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title"],
+            customs=[("word_count", int, 0)],  # This custom...
+        )
+        schema_detail = serializers.SchemaModelConfig(
+            fields=["id", "title", "content"],
+            # ...is NOT inherited here because schema_detail is defined
+            # You must explicitly add it if needed:
+            # customs=[("word_count", int, 0)],
+        )
+```
+
 ## Example: simple FK
 
 ```python

{django_ninja_aio_crud-2.11.1 → django_ninja_aio_crud-2.12.0}/ninja_aio/__init__.py

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

{django_ninja_aio_crud-2.11.1 → django_ninja_aio_crud-2.12.0}/ninja_aio/models/serializers.py

@@ -333,11 +333,7 @@ class BaseSerializer:
     @classmethod
     def get_fields(cls, s_type: S_TYPES):
         """Return explicit declared fields for the serializer type."""
-        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
+        return cls._get_fields(s_type, "fields")
 
     @classmethod
     def is_custom(cls, field: str) -> bool:
@@ -428,8 +424,9 @@ 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)
+            or getattr(settings, "NINJA_AIO_RAISE_SERIALIZATION_WARNINGS", False)
         ):
             warnings.warn(
                 f"{cls.__name__}: reverse relation '{field_name}' is listed in read fields "
@@ -781,7 +778,10 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
         if not config_class_name:
             return []
         config_class = getattr(cls, config_class_name)
-        return getattr(config_class, f_type, [])
+        fields = getattr(config_class, f_type, [])
+        if not fields and s_type == "detail":
+            fields = getattr(cls.ReadSerializer, f_type, [])
+        return fields
 
     @classmethod
     def _get_model(cls) -> "ModelSerializer":
@@ -1006,7 +1006,10 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
             return []
         schema = cls._get_schema_meta(schema_key)
         if not schema:
-            return []
+            if s_type == "detail":
+                schema = cls._get_schema_meta("out")
+            else:
+                return []
         return getattr(schema, f_type, []) or []
 
     @classmethod

{django_ninja_aio_crud-2.11.1 → django_ninja_aio_crud-2.12.0}/ninja_aio/models/utils.py

@@ -601,7 +601,7 @@ class ModelUtil:
     async def _bump_object_from_schema(
         self, obj: type["ModelSerializer"] | models.Model, schema: Schema
     ):
-        return (await sync_to_async(schema.from_orm)(obj)).model_dump(mode="json")
+        return (await sync_to_async(schema.from_orm)(obj)).model_dump()
 
     def _validate_read_params(self, request: HttpRequest, query_data: QuerySchema):
         """Validate required parameters for read operations."""

{django_ninja_aio_crud-2.11.1 → django_ninja_aio_crud-2.12.0}/tests/test_app/models.py

@@ -187,3 +187,39 @@ class TestModelSerializerWithDetail(BaseTestModelSerializer):
     class DetailSerializer:
         fields = ["id", "name", "description", "extra_info"]
         customs = [("computed_field", str, "computed_value")]
+
+
+class TestModelSerializerWithReadCustoms(BaseTestModelSerializer):
+    """Model with customs on ReadSerializer but no DetailSerializer."""
+
+    class ReadSerializer:
+        fields = ["id", "name"]
+        customs = [("custom_field", str, "default")]
+
+
+class TestModelSerializerWithReadOptionals(BaseTestModelSerializer):
+    """Model with optionals on ReadSerializer but no DetailSerializer."""
+
+    class ReadSerializer:
+        fields = ["id", "name"]
+        optionals = [("description", str)]
+
+
+class TestModelSerializerWithReadExcludes(BaseTestModelSerializer):
+    """Model with excludes on ReadSerializer but no DetailSerializer."""
+
+    class ReadSerializer:
+        fields = ["id", "name", "description"]
+        excludes = ["description"]
+
+
+class TestModelSerializerWithBothSerializers(BaseTestModelSerializer):
+    """Model with both ReadSerializer and DetailSerializer configured."""
+
+    class ReadSerializer:
+        fields = ["id", "name"]
+        customs = [("read_custom", str, "default")]
+
+    class DetailSerializer:
+        fields = ["id", "name", "description"]
+        # No customs defined - should NOT inherit from read

{django_ninja_aio_crud-2.11.1 → django_ninja_aio_crud-2.12.0}/tests/test_serializers.py

@@ -298,6 +298,94 @@ class DetailSerializerTestCase(TestCase):
     def setUp(self):
         warnings.simplefilter("ignore", UserWarning)
 
+    def test_detail_fallback_customs_from_read(self):
+        """Test that detail schema falls back to read customs when not configured."""
+
+        class DetailFallbackCustomsSerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_out = serializers.SchemaModelConfig(
+                    fields=["id", "name"],
+                    customs=[("read_custom", str, "default")],
+                )
+                # No schema_detail defined - should fall back to schema_out
+
+        # Detail should inherit customs from read schema
+        schema_detail = DetailFallbackCustomsSerializer.generate_detail_s()
+        self.assertIsNotNone(schema_detail)
+        self.assertIn("id", schema_detail.model_fields)
+        self.assertIn("name", schema_detail.model_fields)
+        self.assertIn("read_custom", schema_detail.model_fields)
+
+    def test_detail_fallback_optionals_from_read(self):
+        """Test that detail schema falls back to read optionals when not configured."""
+
+        class DetailFallbackOptionalsSerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_out = serializers.SchemaModelConfig(
+                    fields=["id", "name"],
+                    optionals=[("description", str)],
+                )
+                # No schema_detail defined - should fall back to schema_out
+
+        # Detail should inherit optionals from read schema
+        schema_detail = DetailFallbackOptionalsSerializer.generate_detail_s()
+        self.assertIsNotNone(schema_detail)
+        self.assertIn("id", schema_detail.model_fields)
+        self.assertIn("name", schema_detail.model_fields)
+        self.assertIn("description", schema_detail.model_fields)
+
+    def test_detail_fallback_excludes_from_read(self):
+        """Test that detail schema falls back to read excludes when not configured."""
+
+        class DetailFallbackExcludesSerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_out = serializers.SchemaModelConfig(
+                    fields=["id", "name"],
+                    exclude=["test_model"],  # Exclude forward relation
+                )
+                # No schema_detail defined - should fall back to schema_out
+
+        # Detail should inherit excludes from read schema
+        schema_detail = DetailFallbackExcludesSerializer.generate_detail_s()
+        read_schema = DetailFallbackExcludesSerializer.generate_read_s()
+        self.assertIsNotNone(schema_detail)
+        # Both should have the same excludes applied
+        self.assertEqual(
+            set(schema_detail.model_fields.keys()),
+            set(read_schema.model_fields.keys()),
+        )
+
+    def test_detail_does_not_inherit_when_defined(self):
+        """Test that detail does NOT inherit from read when schema_detail is defined."""
+
+        class DetailDoesNotInheritSerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_out = serializers.SchemaModelConfig(
+                    fields=["id", "name"],
+                    customs=[("read_custom", str, "default")],
+                )
+                schema_detail = serializers.SchemaModelConfig(
+                    fields=["id", "name", "description"],
+                    # No customs defined - does NOT inherit from read
+                    # because schema_detail is defined (fallback is at schema level)
+                )
+
+        # Read schema should have the custom
+        schema_read = DetailDoesNotInheritSerializer.generate_read_s()
+        self.assertIn("read_custom", schema_read.model_fields)
+
+        # Detail schema does NOT inherit customs from read because schema_detail is defined
+        # (Serializer fallback is at the schema level, not per-field-type)
+        schema_detail = DetailDoesNotInheritSerializer.generate_detail_s()
+        self.assertIn("id", schema_detail.model_fields)
+        self.assertIn("name", schema_detail.model_fields)
+        self.assertIn("description", schema_detail.model_fields)
+        self.assertNotIn("read_custom", schema_detail.model_fields)
+
     def test_generate_detail_schema_with_serializer(self):
         """Test generate_detail_s() with Serializer class."""
 
@@ -416,3 +504,97 @@ class DetailSerializerTestCase(TestCase):
         self.assertIn("id", schema_detail.model_fields)
         self.assertIn("name", schema_detail.model_fields)
         self.assertIn("description", schema_detail.model_fields)
+
+
+@tag("serializers", "detail", "model_serializer")
+class ModelSerializerDetailFallbackTestCase(TestCase):
+    """Test cases for ModelSerializer detail->read fallback behavior."""
+
+    def setUp(self):
+        warnings.simplefilter("ignore", UserWarning)
+
+    def test_model_serializer_detail_fallback_fields(self):
+        """Test ModelSerializer detail falls back to read fields when not configured."""
+        from tests.test_app.models import TestModelSerializer
+
+        # TestModelSerializer has ReadSerializer with fields but no DetailSerializer
+        read_fields = TestModelSerializer.get_fields("read")
+        detail_fields = TestModelSerializer.get_fields("detail")
+
+        # Detail should fall back to read fields
+        self.assertEqual(read_fields, detail_fields)
+
+    def test_model_serializer_detail_fallback_customs(self):
+        """Test ModelSerializer detail falls back to read customs when not configured."""
+        from tests.test_app.models import TestModelSerializerWithReadCustoms
+
+        read_customs = TestModelSerializerWithReadCustoms.get_custom_fields("read")
+        detail_customs = TestModelSerializerWithReadCustoms.get_custom_fields("detail")
+
+        # Detail should fall back to read customs
+        self.assertEqual(read_customs, detail_customs)
+        self.assertEqual(len(detail_customs), 1)
+        self.assertEqual(detail_customs[0][0], "custom_field")
+
+    def test_model_serializer_detail_fallback_optionals(self):
+        """Test ModelSerializer detail falls back to read optionals when not configured."""
+        from tests.test_app.models import TestModelSerializerWithReadOptionals
+
+        read_optionals = TestModelSerializerWithReadOptionals.get_optional_fields("read")
+        detail_optionals = TestModelSerializerWithReadOptionals.get_optional_fields("detail")
+
+        # Detail should fall back to read optionals
+        self.assertEqual(read_optionals, detail_optionals)
+        self.assertEqual(len(detail_optionals), 1)
+        self.assertEqual(detail_optionals[0][0], "description")
+
+    def test_model_serializer_detail_fallback_excludes(self):
+        """Test ModelSerializer detail falls back to read excludes when not configured."""
+        from tests.test_app.models import TestModelSerializerWithReadExcludes
+
+        read_excludes = TestModelSerializerWithReadExcludes.get_excluded_fields("read")
+        detail_excludes = TestModelSerializerWithReadExcludes.get_excluded_fields("detail")
+
+        # Detail should fall back to read excludes
+        self.assertEqual(read_excludes, detail_excludes)
+        self.assertIn("description", detail_excludes)
+
+    def test_model_serializer_detail_inherits_per_field_type(self):
+        """Test ModelSerializer detail inherits from read per-field-type when empty."""
+        from tests.test_app.models import TestModelSerializerWithBothSerializers
+
+        read_customs = TestModelSerializerWithBothSerializers.get_custom_fields("read")
+        detail_customs = TestModelSerializerWithBothSerializers.get_custom_fields("detail")
+
+        # Read has customs defined
+        self.assertEqual(len(read_customs), 1)
+        # Detail inherits customs from read because DetailSerializer.customs is empty
+        # (fallback is per-field-type, not per-serializer)
+        self.assertEqual(len(detail_customs), 1)
+        self.assertEqual(detail_customs[0][0], "read_custom")
+
+        # But fields are different (DetailSerializer.fields overrides)
+        read_fields = TestModelSerializerWithBothSerializers.get_fields("read")
+        detail_fields = TestModelSerializerWithBothSerializers.get_fields("detail")
+        self.assertEqual(read_fields, ["id", "name"])
+        self.assertEqual(detail_fields, ["id", "name", "description"])
+
+    def test_model_serializer_with_detail_generates_different_schemas(self):
+        """Test that ModelSerializer with DetailSerializer generates distinct schemas."""
+        from tests.test_app.models import TestModelSerializerWithDetail
+
+        read_schema = TestModelSerializerWithDetail.generate_read_s()
+        detail_schema = TestModelSerializerWithDetail.generate_detail_s()
+
+        # Read schema should have fewer fields
+        self.assertIn("id", read_schema.model_fields)
+        self.assertIn("name", read_schema.model_fields)
+        self.assertNotIn("description", read_schema.model_fields)
+        self.assertNotIn("extra_info", read_schema.model_fields)
+
+        # Detail schema should have more fields plus custom
+        self.assertIn("id", detail_schema.model_fields)
+        self.assertIn("name", detail_schema.model_fields)
+        self.assertIn("description", detail_schema.model_fields)
+        self.assertIn("extra_info", detail_schema.model_fields)
+        self.assertIn("computed_field", detail_schema.model_fields)