django-ninja-aio-crud 2.16.0__tar.gz → 2.16.2__tar.gz

{django_ninja_aio_crud-2.16.0 → django_ninja_aio_crud-2.16.2}/.github/workflows/docs.yml

@@ -28,6 +28,7 @@ on:
           - "2.13"
           - "2.14"
           - "2.15"
+          - "2.16"
       make_latest:
         description: 'Set as "latest" and default?'
         type: boolean
@@ -59,6 +60,7 @@ on:
           - "2.13"
           - "2.14"
           - "2.15"
+          - "2.16"
       delete_confirm:
         description: 'Confirm deletion of the selected version'
         type: boolean

{django_ninja_aio_crud-2.16.0 → django_ninja_aio_crud-2.16.2}/PKG-INFO

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

{django_ninja_aio_crud-2.16.0 → django_ninja_aio_crud-2.16.2}/docs/api/views/api_view_set.md

@@ -294,6 +294,8 @@ Relations are declared via `M2MRelationSchema` objects (not tuples). Each schema
 - `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.
 - `verbose_name_plural`: optional human-readable plural name for the related model, used in endpoint summaries and descriptions. When not provided, defaults to the related model's `_meta.verbose_name_plural`.
+- `get_decorators`: optional list of decorators to apply to the GET (list related objects) endpoint. Decorators are applied via `decorate_view()` alongside built-in decorators like `unique_view` and `paginate`.
+- `post_decorators`: optional list of decorators to apply to the POST (add/remove) endpoint. Decorators are applied via `decorate_view()` alongside the built-in `unique_view` decorator.
 
 If `path` is empty it falls back to the related model verbose name (lowercase plural).
 If `filters` is provided, a per-relation filters schema is auto-generated and exposed on the GET relation endpoint:
@@ -489,6 +491,44 @@ M2MRelationSchema(
 )
 ```
 
+Example with custom decorators:
+
+```python
+from functools import wraps
+
+def cache_response(timeout=60):
+    """Cache decorator for GET endpoints."""
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # caching logic here
+            return await func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+def rate_limit(max_calls=100):
+    """Rate limiting decorator for POST endpoints."""
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # rate limiting logic here
+            return await func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+M2MRelationSchema(
+    model=Tag,
+    related_name="tags",
+    get_decorators=[cache_response(timeout=300)],  # Cache GET for 5 minutes
+    post_decorators=[rate_limit(max_calls=50)],     # Rate limit POST operations
+    add=True,
+    remove=True,
+    get=True,
+)
+```
+
+Note: Decorators are applied in addition to built-in decorators (`unique_view`, `paginate`). The order follows standard Python decorator stacking: decorators listed first are applied outermost.
+
 ## Custom Views
 
 Preferred (decorators): see the section above.

{django_ninja_aio_crud-2.16.0 → django_ninja_aio_crud-2.16.2}/docs/api/views/decorators.md

@@ -63,6 +63,23 @@ class MyViewSet(APIViewSet):
 
 These are applied in combination with built-ins (e.g., unique_view, paginate) using decorate_view in the implementation.
 
+## M2MRelationSchema decorators
+
+Apply custom decorators to Many-to-Many relation endpoints via `get_decorators` and `post_decorators`:
+
+```python
+from ninja_aio.schemas import M2MRelationSchema
+
+M2MRelationSchema(
+    model=Tag,
+    related_name="tags",
+    get_decorators=[cache_decorator, log_decorator],   # Applied to GET (list related)
+    post_decorators=[rate_limit_decorator],            # Applied to POST (add/remove)
+)
+```
+
+These decorators are applied alongside built-in decorators (`unique_view`, `paginate`) using `decorate_view`. See [APIViewSet M2M Relations](api_view_set.md#many-to-many-relations) for more details.
+
 ## ApiMethodFactory.decorators
 
 Example: use api_get within a ViewSet with extra decorators:

{django_ninja_aio_crud-2.16.0 → django_ninja_aio_crud-2.16.2}/docs/getting_started/quick_start.md

@@ -1,8 +1,13 @@
-## 🚀 Quick Start
+## 🚀 Quick Start (ModelSerializer)
+
+This guide shows how to create a CRUD API using `ModelSerializer`, which combines your Django model and serialization configuration in a single class.
+
+!!! tip "Alternative Approach"
+    If you prefer to keep your models unchanged and define serialization separately, see [Quick Start (Serializer)](quick_start_serializer.md).
 
 ### 1. Create Your Model
 
-Define your model using `ModelSerializer`:
+Define your model using `ModelSerializer` with embedded serializer configuration:
 
 ```python
 # models.py
@@ -44,12 +49,9 @@ from .models import Article
 api = NinjaAIO(title="My Blog API", version="1.0.0")
 
 
+@api.viewset(model=Article)
 class ArticleViewSet(APIViewSet):
-    model = Article
-    api = api
-
-
-ArticleViewSet().add_views_to_route()
+    pass
 ```
 
 ### 3. Configure URLs

django_ninja_aio_crud-2.16.2/docs/getting_started/quick_start_serializer.md

@@ -0,0 +1,220 @@
+## 🚀 Quick Start (Serializer)
+
+This guide shows how to create a CRUD API using the `Serializer` class with plain Django models. This approach keeps your models unchanged and defines API configuration separately.
+
+!!! tip "Alternative Approach"
+    If you prefer an all-in-one approach with embedded serialization, see [Quick Start (ModelSerializer)](quick_start.md).
+
+### When to Use Serializer
+
+Choose the `Serializer` approach when:
+
+- You have existing Django models you don't want to modify
+- You want to keep models and API concerns separated
+- You're adding API functionality to an existing project
+- Multiple teams work on models vs. API layers
+
+### 1. Create Your Model
+
+Use a standard Django model:
+
+```python
+# models.py
+from django.db import models
+
+
+class Article(models.Model):
+    title = models.CharField(max_length=200)
+    content = models.TextField()
+    is_published = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        ordering = ["-created_at"]
+```
+
+### 2. Create Your Serializer
+
+Define a `Serializer` class with API configuration in a nested `Meta` class:
+
+```python
+# serializers.py
+from ninja_aio.models import serializers
+from .models import Article
+
+
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = Article
+        schema_in = serializers.SchemaModelConfig(
+            fields=["title", "content"],
+            optionals=[("is_published", bool)],
+        )
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "content", "is_published", "created_at"]
+        )
+        schema_update = serializers.SchemaModelConfig(
+            optionals=[
+                ("title", str),
+                ("content", str),
+                ("is_published", bool),
+            ]
+        )
+```
+
+### 3. Create Your ViewSet
+
+Define your API views using `APIViewSet` with `serializer_class`:
+
+```python
+# views.py
+from ninja_aio import NinjaAIO
+from ninja_aio.views import APIViewSet
+from .models import Article
+from .serializers import ArticleSerializer
+
+api = NinjaAIO(title="My Blog API", version="1.0.0")
+
+
+@api.viewset(model=Article)
+class ArticleViewSet(APIViewSet):
+    serializer_class = ArticleSerializer
+```
+
+### 4. Configure URLs
+
+Add the API to your URL configuration:
+
+```python
+# urls.py
+from django.urls import path
+from .views import api
+
+urlpatterns = [
+    path("api/", api.urls),
+]
+```
+
+### 5. Run Your Server
+
+```bash
+python manage.py runserver
+```
+
+Visit **[http://localhost:8000/api/docs](http://localhost:8000/api/docs)** to see your auto-generated API documentation!
+
+## Adding Relationships
+
+The `Serializer` approach supports nested serialization for related models:
+
+```python
+# models.py
+from django.db import models
+
+
+class Author(models.Model):
+    name = models.CharField(max_length=200)
+    email = models.EmailField()
+
+
+class Article(models.Model):
+    title = models.CharField(max_length=200)
+    content = models.TextField()
+    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name="articles")
+    is_published = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+```
+
+```python
+# serializers.py
+from ninja_aio.models import serializers
+from .models import Author, Article
+
+
+class AuthorSerializer(serializers.Serializer):
+    class Meta:
+        model = Author
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "name", "email"]
+        )
+
+
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = Article
+        schema_in = serializers.SchemaModelConfig(
+            fields=["title", "content", "author"],
+        )
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "content", "author", "is_published", "created_at"]
+        )
+        schema_update = serializers.SchemaModelConfig(
+            optionals=[
+                ("title", str),
+                ("content", str),
+                ("is_published", bool),
+            ]
+        )
+        # Nested serialization for the author field
+        relations_serializers = {
+            "author": AuthorSerializer,
+        }
+
+    class QuerySet:
+        # Optimize queries with select_related
+        read = serializers.ModelQuerySetSchema(
+            select_related=["author"]
+        )
+```
+
+## Adding Lifecycle Hooks
+
+Add custom logic to CRUD operations using hooks:
+
+```python
+# serializers.py
+from ninja_aio.models import serializers
+from .models import Article
+
+
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = Article
+        schema_in = serializers.SchemaModelConfig(
+            fields=["title", "content"],
+            customs=[("notify_subscribers", bool, False)],  # Custom field
+        )
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "content", "is_published", "created_at"]
+        )
+        schema_update = serializers.SchemaModelConfig(
+            optionals=[("title", str), ("content", str), ("is_published", bool)]
+        )
+
+    async def custom_actions(self, payload, instance):
+        """Execute after field assignment, before save."""
+        if payload.get("notify_subscribers"):
+            await send_notification(instance.title)
+
+    async def post_create(self, instance):
+        """Execute after instance creation."""
+        await AuditLog.objects.acreate(
+            action="article_created",
+            article_id=instance.id
+        )
+
+    def before_save(self, instance):
+        """Execute before any save (sync hook)."""
+        instance.slug = slugify(instance.title)
+
+    def on_delete(self, instance):
+        """Execute after deletion (sync hook)."""
+        logger.info(f"Article {instance.id} deleted")
+```
+
+## Next Steps
+
+- Learn more about [Serializer configuration](../api/models/serializers.md)
+- Explore [APIViewSet features](../api/views/api_view_set.md)
+- Add [Authentication](../api/authentication.md) to your API
+- Configure [Pagination](../api/pagination.md)

{django_ninja_aio_crud-2.16.0 → django_ninja_aio_crud-2.16.2}/mkdocs.yml

@@ -9,7 +9,8 @@ nav:
   - Home: index.md
   - Getting Started:
     - Installation: getting_started/installation.md
-    - Quick Start: getting_started/quick_start.md
+    - Quick Start (ModelSerializer): getting_started/quick_start.md
+    - Quick Start (Serializer): getting_started/quick_start_serializer.md
   - Tutorial:
     - 'Step 1: Define Your Model': tutorial/model.md
     - 'Step 2: Create CRUD Views': tutorial/crud.md

{django_ninja_aio_crud-2.16.0 → django_ninja_aio_crud-2.16.2}/ninja_aio/__init__.py

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

{django_ninja_aio_crud-2.16.0 → django_ninja_aio_crud-2.16.2}/ninja_aio/exceptions.py

@@ -78,7 +78,7 @@ def _default_error(
 
 
 def _pydantic_validation_error(
-    request: HttpRequest, exc: ValidationError, api: type[NinjaAPI]
+    request: HttpRequest, exc: PydanticValidationError, api: type[NinjaAPI]
 ) -> HttpResponse:
     """Translate a pydantic ValidationError into a normalized API error response."""
     error = PydanticValidationError(exc.errors(include_input=False))

{django_ninja_aio_crud-2.16.0 → django_ninja_aio_crud-2.16.2}/ninja_aio/models/serializers.py

@@ -669,9 +669,18 @@ class BaseSerializer:
         customs = cls.get_custom_fields(s_type) + optionals
         excludes = cls.get_excluded_fields(s_type)
 
-        # If no explicit fields but have optionals, use optional field names as fields
+        # If no explicit fields and no excludes specified
         if not fields and not excludes:
-            fields = [f[0] for f in optionals]
+            if optionals:
+                # Use optional field names as the fields to include
+                fields = [f[0] for f in optionals]
+            elif customs:
+                # Only customs defined - exclude all model fields to prevent auto-inclusion
+                excludes = [
+                    f.name
+                    for f in model._meta.get_fields()
+                    if getattr(f, "concrete", False)
+                ]
 
         # Only create schema if we have something to include
         if not any([fields, customs, excludes]):
@@ -1037,18 +1046,18 @@ class SchemaModelConfig(Schema):
     ----------
     fields : Optional[List[str]]
         Explicit model fields to include.
-    optionals : Optional[List[tuple[str, type]]]
-        Optional model fields.
+    optionals : Optional[List[tuple[str, Any]]]
+        Optional model fields. Type can be any valid type annotation including Union.
     exclude : Optional[List[str]]
         Model fields to exclude.
-    customs : Optional[List[tuple[str, type, Any]]]
-        Custom / synthetic fields.
+    customs : Optional[List[tuple[str, Any, Any]]]
+        Custom / synthetic fields. Type can be any valid type annotation including Union.
     """
 
     fields: Optional[List[str]] = None
-    optionals: Optional[List[tuple[str, type]]] = None
+    optionals: Optional[List[tuple[str, Any]]] = None
     exclude: Optional[List[str]] = None
-    customs: Optional[List[tuple[str, type, Any]]] = None
+    customs: Optional[List[tuple[str, Any, Any]]] = None
 
 
 class Serializer(BaseSerializer, metaclass=SerializerMeta):

{django_ninja_aio_crud-2.16.0 → django_ninja_aio_crud-2.16.2}/tests/test_serializers.py

@@ -1227,6 +1227,161 @@ class RelationsAsIdStringPKModelSerializerTestCase(TestCase):
         )
 
 
+@tag("serializers", "customs_only")
+class CustomsOnlySchemaTestCase(TestCase):
+    """Test cases for schemas with only customs/optionals defined (no fields/excludes)."""
+
+    def setUp(self):
+        warnings.simplefilter("ignore", UserWarning)
+
+    def test_serializer_create_schema_with_only_customs(self):
+        """Test that create schema with only customs does NOT include model fields."""
+
+        class CustomsOnlyCreateSerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_in = serializers.SchemaModelConfig(
+                    customs=[("custom_input", str, ...)]
+                )
+                schema_out = serializers.SchemaModelConfig(fields=["id", "name"])
+
+        schema = CustomsOnlyCreateSerializer.generate_create_s()
+        self.assertIsNotNone(schema)
+        # Should only have the custom field, not model fields
+        self.assertIn("custom_input", schema.model_fields)
+        # Should NOT have model fields auto-included
+        self.assertNotIn("name", schema.model_fields)
+        self.assertNotIn("description", schema.model_fields)
+        self.assertNotIn("test_model", schema.model_fields)
+        self.assertNotIn("id", schema.model_fields)
+
+    def test_serializer_update_schema_with_only_customs(self):
+        """Test that update schema with only customs does NOT include model fields."""
+
+        class CustomsOnlyUpdateSerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_update = serializers.SchemaModelConfig(
+                    customs=[("custom_patch_field", str, None)]
+                )
+                schema_out = serializers.SchemaModelConfig(fields=["id", "name"])
+
+        schema = CustomsOnlyUpdateSerializer.generate_update_s()
+        self.assertIsNotNone(schema)
+        # Should only have the custom field
+        self.assertIn("custom_patch_field", schema.model_fields)
+        # Should NOT have model fields auto-included
+        self.assertNotIn("name", schema.model_fields)
+        self.assertNotIn("description", schema.model_fields)
+        self.assertNotIn("test_model", schema.model_fields)
+        self.assertNotIn("id", schema.model_fields)
+
+    def test_serializer_create_schema_with_customs_and_optionals(self):
+        """Test create schema with customs + optionals includes only those fields."""
+
+        class CustomsAndOptionalsSerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_in = serializers.SchemaModelConfig(
+                    customs=[("custom_field", str, ...)],
+                    optionals=[("name", str)],  # name is a model field made optional
+                )
+                schema_out = serializers.SchemaModelConfig(fields=["id", "name"])
+
+        schema = CustomsAndOptionalsSerializer.generate_create_s()
+        self.assertIsNotNone(schema)
+        # Should have custom field
+        self.assertIn("custom_field", schema.model_fields)
+        # Should have the optional model field
+        self.assertIn("name", schema.model_fields)
+        # Should NOT have other model fields
+        self.assertNotIn("description", schema.model_fields)
+        self.assertNotIn("test_model", schema.model_fields)
+        self.assertNotIn("id", schema.model_fields)
+
+    def test_serializer_with_fields_still_works(self):
+        """Test that defining fields still works as expected."""
+
+        class FieldsDefinedSerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_in = serializers.SchemaModelConfig(
+                    fields=["name", "description"],
+                    customs=[("extra", int, 0)],
+                )
+                schema_out = serializers.SchemaModelConfig(fields=["id", "name"])
+
+        schema = FieldsDefinedSerializer.generate_create_s()
+        self.assertIsNotNone(schema)
+        # Should have specified fields
+        self.assertIn("name", schema.model_fields)
+        self.assertIn("description", schema.model_fields)
+        # Should have custom field
+        self.assertIn("extra", schema.model_fields)
+        # Should NOT have other model fields
+        self.assertNotIn("test_model", schema.model_fields)
+        self.assertNotIn("id", schema.model_fields)
+
+    def test_serializer_with_only_excludes_and_customs(self):
+        """Test schema with excludes and customs but no fields only has customs."""
+
+        class ExcludesOnlySerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_in = serializers.SchemaModelConfig(
+                    exclude=["id", "test_model"],
+                    customs=[("extra", int, 0)],
+                )
+                schema_out = serializers.SchemaModelConfig(fields=["id", "name"])
+
+        schema = ExcludesOnlySerializer.generate_create_s()
+        self.assertIsNotNone(schema)
+        # With excludes but no fields, only customs are included
+        # because fields=[] is passed to create_schema (no model fields)
+        self.assertIn("extra", schema.model_fields)
+        # This is expected behavior: without explicit fields, no model fields included
+        self.assertEqual(len(schema.model_fields), 1)
+
+    def test_serializer_empty_schema_returns_none(self):
+        """Test that schema with nothing defined returns None."""
+
+        class EmptySchemaSerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_in = serializers.SchemaModelConfig()
+                schema_out = serializers.SchemaModelConfig(fields=["id", "name"])
+
+        schema = EmptySchemaSerializer.generate_create_s()
+        self.assertIsNone(schema)
+
+    def test_serializer_multiple_customs_no_model_fields(self):
+        """Test schema with multiple customs but no model fields."""
+
+        class MultipleCustomsSerializer(serializers.Serializer):
+            class Meta:
+                model = TestModelForeignKey
+                schema_in = serializers.SchemaModelConfig(
+                    customs=[
+                        ("custom1", str, ...),
+                        ("custom2", int, 0),
+                        ("custom3", bool, False),
+                    ]
+                )
+                schema_out = serializers.SchemaModelConfig(fields=["id", "name"])
+
+        schema = MultipleCustomsSerializer.generate_create_s()
+        self.assertIsNotNone(schema)
+        # Should have all custom fields
+        self.assertIn("custom1", schema.model_fields)
+        self.assertIn("custom2", schema.model_fields)
+        self.assertIn("custom3", schema.model_fields)
+        # Should NOT have any model fields
+        self.assertNotIn("name", schema.model_fields)
+        self.assertNotIn("description", schema.model_fields)
+        self.assertNotIn("test_model", schema.model_fields)
+        self.assertNotIn("id", schema.model_fields)
+
+
 @tag("serializers", "relations_as_id", "string_pk", "integration")
 class RelationsAsIdStringPKIntegrationTestCase(TestCase):
     """Integration tests for relations_as_id with string primary keys and actual data serialization."""