django-ninja-aio-crud 2.3.2__tar.gz → 2.5.0__tar.gz

{django_ninja_aio_crud-2.3.2 → django_ninja_aio_crud-2.5.0}/.github/workflows/docs.yml

@@ -15,6 +15,7 @@ on:
           - "2.0"
           - "2.2"
           - "2.3"
+          - "2.4"
       make_latest:
         description: 'Set as "latest" and default?'
         type: boolean
@@ -33,6 +34,7 @@ on:
           - "2.0"
           - "2.2"
           - "2.3"
+          - "2.4"
       delete_confirm:
         description: 'Confirm deletion of the selected version'
         type: boolean

{django_ninja_aio_crud-2.3.2 → django_ninja_aio_crud-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 2.3.2
+Version: 2.5.0
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
 Requires-Python: >=3.10, <3.15
@@ -48,6 +48,7 @@ Provides-Extra: test
 
 ## ✨ Features
 
+- Serializer (Meta-driven) first-class: dynamic schemas for existing Django models without inheriting ModelSerializer
 - Async CRUD ViewSets (create, list, retrieve, update, delete)
 - Automatic Pydantic schemas from `ModelSerializer` (read/create/update)
 - Dynamic query params (runtime schema via `pydantic.create_model`)
@@ -61,17 +62,35 @@ Provides-Extra: test
 
 ---
 
-## 📦 Installation
+## 🚀 Quick Start (Serializer)
 
-```bash
-pip install django-ninja-aio-crud
+If you already have Django models, start with the Meta-driven Serializer for instant CRUD without changing model base classes.
+
+```python
+from ninja_aio.models import serializers
+from ninja_aio.views import APIViewSet
+from ninja_aio import NinjaAIO
+from . import models
+
+class BookSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Book
+        schema_in = serializers.SchemaModelConfig(fields=["title", "published"])
+        schema_out = serializers.SchemaModelConfig(fields=["id", "title", "published"])
+        schema_update = serializers.SchemaModelConfig(optionals=[("title", str), ("published", bool)])
+
+api = NinjaAIO()
+
+@api.viewset(models.Book)
+class BookViewSet(APIViewSet):
+    serializer_class = BookSerializer
 ```
 
-Add to your project’s dependencies and ensure Django Ninja is installed.
+Visit `/docs` → CRUD endpoints ready.
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Quick Start (ModelSerializer)
 
 models.py
 
@@ -262,6 +281,12 @@ class BookViewSet(APIViewSet):
 
 ---
 
+## Meta-driven Serializer (for vanilla Django models)
+
+Moved above as the primary quick start.
+
+---
+
 ## 🛠 Project Structure & Docs
 
 Documentation (MkDocs + Material):

{django_ninja_aio_crud-2.3.2 → django_ninja_aio_crud-2.5.0}/README.md

@@ -13,6 +13,7 @@
 
 ## ✨ Features
 
+- Serializer (Meta-driven) first-class: dynamic schemas for existing Django models without inheriting ModelSerializer
 - Async CRUD ViewSets (create, list, retrieve, update, delete)
 - Automatic Pydantic schemas from `ModelSerializer` (read/create/update)
 - Dynamic query params (runtime schema via `pydantic.create_model`)
@@ -26,17 +27,35 @@
 
 ---
 
-## 📦 Installation
+## 🚀 Quick Start (Serializer)
 
-```bash
-pip install django-ninja-aio-crud
+If you already have Django models, start with the Meta-driven Serializer for instant CRUD without changing model base classes.
+
+```python
+from ninja_aio.models import serializers
+from ninja_aio.views import APIViewSet
+from ninja_aio import NinjaAIO
+from . import models
+
+class BookSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Book
+        schema_in = serializers.SchemaModelConfig(fields=["title", "published"])
+        schema_out = serializers.SchemaModelConfig(fields=["id", "title", "published"])
+        schema_update = serializers.SchemaModelConfig(optionals=[("title", str), ("published", bool)])
+
+api = NinjaAIO()
+
+@api.viewset(models.Book)
+class BookViewSet(APIViewSet):
+    serializer_class = BookSerializer
 ```
 
-Add to your project’s dependencies and ensure Django Ninja is installed.
+Visit `/docs` → CRUD endpoints ready.
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Quick Start (ModelSerializer)
 
 models.py
 
@@ -227,6 +246,12 @@ class BookViewSet(APIViewSet):
 
 ---
 
+## Meta-driven Serializer (for vanilla Django models)
+
+Moved above as the primary quick start.
+
+---
+
 ## 🛠 Project Structure & Docs
 
 Documentation (MkDocs + Material):

{django_ninja_aio_crud-2.3.2 → django_ninja_aio_crud-2.5.0}/docs/api/models/model_util.md

@@ -17,15 +17,36 @@ ModelUtil acts as a bridge between Django Ninja schemas and Django ORM, handling
 ```python
 from ninja_aio.models import ModelUtil
 
-util = ModelUtil(model)
+util = ModelUtil(model, serializer_class=None)
 ```
 
 **Parameters:**
 
 - `model` (`type[ModelSerializer] | models.Model`): Django model or ModelSerializer subclass
+- `serializer_class` (`Serializer | None`): Optional Serializer class for plain Django models
 
 ## Properties
 
+### `with_serializer`
+
+Indicates if a serializer_class is associated.
+
+```python
+util = ModelUtil(User, serializer_class=UserSerializer)
+print(util.with_serializer)  # True
+```
+
+### `pk_field_type`
+
+Returns the Python type corresponding to the model's primary key field.
+
+```python
+util = ModelUtil(User)
+print(util.pk_field_type)  # <class 'int'>
+```
+
+Uses the Django field's internal type and `ninja.orm.fields.TYPES` mapping. Raises `ConfigError` if the internal type is not registered.
+
 ### `model_pk_name`
 
 Returns the primary key field name.
@@ -45,7 +66,7 @@ print(util.model_fields)
 # ["id", "username", "email", "created_at", "is_active"]
 ```
 
-### `schema_out_fields`
+### `serializable_fields`
 
 Returns serializable fields (ReadSerializer fields or all model fields).
 
@@ -59,10 +80,19 @@ class User(ModelSerializer):
         fields = ["id", "username", "email"]
 
 util = ModelUtil(User)
-print(util.schema_out_fields)
+print(util.serializable_fields)
 # ["id", "username", "email"]  (password excluded)
 ```
 
+### `model_name`
+
+Returns the Django internal model name.
+
+```python
+util = ModelUtil(User)
+print(util.model_name)  # "user"
+```
+
 ### `serializer_meta`
 
 Returns the ModelSerializerMeta instance if model uses ModelSerializer.
@@ -147,10 +177,20 @@ qs = await ModelUtil(Book).get_objects(
         select_related=["author"],
         prefetch_related=["tags"],
     ),
+    with_qs_request=True,  # Apply queryset_request hook
     is_for_read=True,  # union with auto-discovered relations
 )
 ```
 
+**Parameters:**
+
+- `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)
+
+**Returns:** Optimized `QuerySet`
+
 ### `get_object`
 
 Fetch a single object by pk or getters with optimizations:
@@ -163,6 +203,7 @@ obj = await ModelUtil(Book).get_object(
     request,
     pk=42,
     query_data=ObjectQuerySchema(select_related=["author"]),
+    with_qs_request=True,
     is_for_read=True,
 )
 
@@ -173,10 +214,20 @@ obj = await ModelUtil(Book).get_object(
 )
 ```
 
-Errors:
+**Parameters:**
 
-- ValueError if neither pk nor getters provided.
-- NotFoundError if no match.
+- `request` (`HttpRequest`): Current HTTP request
+- `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)
+
+**Returns:** Model instance
+
+**Errors:**
+
+- `ValueError` if neither pk nor getters provided
+- `NotFoundError` if no match found
 
 ### `read_s` and `list_read_s`
 
@@ -208,10 +259,27 @@ items = await ModelUtil(Book).list_read_s(
 )
 ```
 
-Behavior:
+**Parameters (read_s):**
+
+- `schema` (`Schema`): Output schema for serialization
+- `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)
+
+**Parameters (list_read_s):**
+
+- `schema` (`Schema`): Output schema for serialization
+- `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)
+
+**Behavior:**
 
-- When is_for_read=True, select_related and prefetch_related are merged with model-discovered relations.
-- Passing instances skips fetching; passing query_data fetches automatically.
+- When `is_for_read=True`, select_related and prefetch_related are merged with model-discovered relations
+- Passing `instance`/`instances` skips fetching; passing `query_data` fetches automatically
+- Either `instance`/`instances` OR `query_data` must be provided, not both
 
 ### `get_reverse_relations()`
 

django_ninja_aio_crud-2.5.0/docs/api/models/serializers.md

@@ -0,0 +1,349 @@
+# Serializer (Meta-driven)
+
+The `Serializer` class provides dynamic schema generation and relation handling for existing Django models without requiring you to adopt the ModelSerializer base class. Use it when:
+
+- You already have vanilla Django models in a project and want dynamic Ninja schemas.
+- You prefer to keep models unchanged and define serialization externally.
+- You need to keep your models lean and define API concerns separately.
+
+It mirrors the behavior of ModelSerializer but reads configuration from a nested Meta class.
+
+## Key Differences from ModelSerializer
+
+While both `ModelSerializer` and `Serializer` provide schema generation and CRUD operations, there are important differences:
+
+| Feature                  | ModelSerializer                     | Serializer                         |
+| ------------------------ | ----------------------------------- | ---------------------------------- |
+| Model class              | Custom base class                   | Plain Django model                 |
+| Configuration            | Nested classes (CreateSerializer)   | Meta class (schema_in/out/update)  |
+| Lifecycle hooks          | Instance methods (uses `self`)      | Receives `instance` parameter      |
+| Auto-binding             | Automatic via metaclass             | Manual via `__init_subclass__`     |
+| Usage                    | Inherit from ModelSerializer        | Separate serializer class          |
+| Query optimization       | QuerySet nested class               | QuerySet nested class (inherited)  |
+| Relation serializers     | Auto-resolved                       | Explicit via relations_serializers |
+
+## Key points
+
+- Works with any Django model (no inheritance required).
+- Generates read/create/update/related schemas on demand via ninja.orm.create_schema.
+- Supports explicit relation serializers for forward and reverse relations.
+- Plays nicely with APIViewSet to auto-wire schemas and queryset handling.
+
+## Configuration
+
+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_update: SchemaModelConfig for patch/update inputs.
+- relations_serializers: mapping of relation field name -> Serializer to include nested schemas for relations.
+
+SchemaModelConfig fields:
+
+- fields: list[str]
+- optionals: list[tuple[str, type]]
+- exclude: list[str]
+- customs: list[tuple[str, type, Any]]
+
+## Example: simple FK
+
+```python
+from ninja_aio.models import serializers
+from . import models
+
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_in = serializers.SchemaModelConfig(
+            fields=["title", "content", "author"]
+        )
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "content", "author"]
+        )
+        schema_update = serializers.SchemaModelConfig(
+            optionals=[("title", str), ("content", str)]
+        )
+```
+
+Schemas are auto-generated in `__init_subclass__` and available as class attributes:
+
+```python
+# Schemas are automatically generated
+ArticleSerializer.generate_read_s()    # Returns read schema
+ArticleSerializer.generate_create_s()  # Returns create schema
+ArticleSerializer.generate_update_s()  # Returns update schema
+ArticleSerializer.generate_related_s() # Returns related schema
+```
+
+## Lifecycle Hooks
+
+Serializer supports lifecycle hooks similar to ModelSerializer, but with a key difference: **all hooks receive an `instance` parameter** instead of using `self`:
+
+```python
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_in = serializers.SchemaModelConfig(
+            fields=["title", "content", "author"],
+            customs=[("notify_author", bool, True)]
+        )
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "content", "author"]
+        )
+
+    @classmethod
+    async def queryset_request(cls, request):
+        """Filter and optimize queryset per request."""
+        return cls._meta.model.objects.select_related("author")
+
+    async def custom_actions(self, payload, instance):
+        """Execute custom actions with access to the instance."""
+        if payload.get("notify_author"):
+            await send_email(instance.author.email, f"Article created: {instance.title}")
+
+    async def post_create(self, instance):
+        """Hook after instance creation."""
+        await AuditLog.objects.acreate(
+            action="article_created",
+            article_id=instance.id
+        )
+
+    def before_save(self, instance):
+        """Sync hook before save (receives instance)."""
+        instance.slug = slugify(instance.title)
+
+    def after_save(self, instance):
+        """Sync hook after save (receives instance)."""
+        cache.delete(f"article:{instance.id}")
+
+    def on_delete(self, instance):
+        """Sync hook after deletion (receives instance)."""
+        logger.info(f"Article {instance.id} deleted")
+```
+
+### Available Hooks
+
+| Hook                        | Type  | When Called               | Parameters              |
+| --------------------------- | ----- | ------------------------- | ----------------------- |
+| `queryset_request(request)` | async | Before queryset building  | `request`               |
+| `custom_actions(payload, i)`| async | After field assignment    | `payload`, `instance`   |
+| `post_create(instance)`     | async | After first save          | `instance`              |
+| `before_save(instance)`     | sync  | Before any save           | `instance`              |
+| `after_save(instance)`      | sync  | After any save            | `instance`              |
+| `on_create_before_save(i)`  | sync  | Before creation save only | `instance`              |
+| `on_create_after_save(i)`   | sync  | After creation save only  | `instance`              |
+| `on_delete(instance)`       | sync  | After deletion            | `instance`              |
+
+## Example: reverse relation with nested serialization
+
+```python
+class AuthorSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Author
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "name", "articles"]  # reverse related name
+        )
+        relations_serializers = {
+            "articles": ArticleSerializer,  # include nested article schema
+        }
+```
+
+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.
+
+## Using with APIViewSet
+
+You can attach a Serializer to an APIViewSet to auto-generate schemas and leverage queryset_request when present:
+
+```python
+from ninja_aio.views import APIViewSet
+from ninja_aio import NinjaAIO
+from . import models
+
+api = NinjaAIO()
+
+@api.viewset(model=models.Article)
+class ArticleViewSet(APIViewSet):
+    serializer_class = ArticleSerializer
+    # Optionally define query_params or custom handlers
+```
+
+Behavior:
+
+- If `model` is a ModelSerializer, APIViewSet uses the model to generate schemas directly
+- If `model` is a vanilla Django model and `serializer_class` is provided, APIViewSet uses the Serializer to generate missing schemas
+- ModelUtil creates a serializer instance and uses its `queryset_request()` hook if defined to build optimized querysets
+- Lifecycle hooks from the serializer are invoked during CRUD operations
+
+## CRUD Operations with Serializer
+
+When using a Serializer with APIViewSet, CRUD operations automatically invoke the appropriate lifecycle hooks:
+
+```python
+# Create operation flow:
+# 1. parse_input_data() - normalize payload
+# 2. create() - create instance
+# 3. custom_actions() - execute custom logic
+# 4. save() - persists with before/after hooks
+# 5. post_create() - post-creation hook
+# 6. read_s() - serialize response
+
+# Update operation flow:
+# 1. get_object() - fetch instance
+# 2. parse_input_data() - normalize payload
+# 3. update() - update instance fields
+# 4. custom_actions() - execute custom logic
+# 5. save() - persists with before/after hooks
+# 6. read_s() - serialize response
+
+# Delete operation flow:
+# 1. get_object() - fetch instance
+# 2. adelete() - delete instance
+# 3. on_delete() - deletion hook
+```
+
+## Advanced: customs and optionals
+
+Customs and optionals behave like ModelSerializer:
+
+- customs: synthetic fields included in schemas (with default or required when default is Ellipsis).
+- optionals: patch-like optional fields. In read schema, they are included with default None.
+
+```python
+class PublishSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_update = serializers.SchemaModelConfig(
+            optionals=[("is_published", bool)],
+            customs=[("notify_subscribers", bool, True)],
+        )
+```
+
+generate_update_s merges optionals and customs for the Patch schema.
+
+## Query Optimization with Serializer
+
+Like ModelSerializer, Serializer supports query optimization via a nested QuerySet class:
+
+```python
+from ninja_aio.schemas.helpers import ModelQuerySetSchema, ModelQuerySetExtraSchema
+
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_out = serializers.SchemaModelConfig(
+            fields=["id", "title", "content", "author", "category"]
+        )
+
+    class QuerySet:
+        read = ModelQuerySetSchema(
+            select_related=["author", "category"],
+            prefetch_related=["tags"],
+        )
+        queryset_request = ModelQuerySetSchema(
+            select_related=[],
+            prefetch_related=["comments"],
+        )
+        extras = [
+            ModelQuerySetExtraSchema(
+                scope="detail_view",
+                select_related=["author__profile"],
+                prefetch_related=["tags", "comments__author"],
+            )
+        ]
+```
+
+The QuerySet configuration is used by ModelUtil to automatically optimize database queries during read operations.
+
+## Complete Example
+
+```python
+from ninja_aio.models import serializers
+from ninja_aio import NinjaAIO
+from ninja_aio.views import APIViewSet
+from django.db import models as django_models
+
+# Plain Django models
+class Author(django_models.Model):
+    name = django_models.CharField(max_length=200)
+    email = django_models.EmailField()
+
+class Article(django_models.Model):
+    title = django_models.CharField(max_length=200)
+    content = django_models.TextField()
+    author = django_models.ForeignKey(Author, on_delete=django_models.CASCADE)
+    is_published = django_models.BooleanField(default=False)
+
+# Serializers
+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"]
+        )
+        schema_update = serializers.SchemaModelConfig(
+            optionals=[("title", str), ("content", str)],
+            customs=[("publish_now", bool, False)]
+        )
+        relations_serializers = {
+            "author": AuthorSerializer
+        }
+
+    class QuerySet:
+        read = serializers.ModelQuerySetSchema(
+            select_related=["author"]
+        )
+
+    async def custom_actions(self, payload, instance):
+        if payload.get("publish_now"):
+            instance.is_published = True
+            await sync_to_async(instance.save)()
+
+# ViewSets
+api = NinjaAIO()
+
+@api.viewset(model=Article)
+class ArticleViewSet(APIViewSet):
+    serializer_class = ArticleSerializer
+```
+
+## When to choose Serializer vs ModelSerializer
+
+**Choose Serializer when:**
+
+- You have existing Django models that you can't or don't want to modify
+- You want to keep models and API concerns separated
+- You're incrementally adding API functionality to an existing project
+- You prefer declarative configuration via Meta classes
+- Multiple teams work on models vs API layers
+
+**Choose ModelSerializer when:**
+
+- You're building a new project from scratch
+- You want to centralize all model and API concerns in one place
+- You prefer configuration via nested classes on the model
+- You want auto-binding and less boilerplate
+- Your models are specifically designed for API usage
+
+Both approaches support:
+
+- Nested relations and dynamic schema generation
+- Query optimization via QuerySet configuration
+- Lifecycle hooks for custom business logic
+- Integration with APIViewSet for auto-generated CRUD endpoints
+
+Choose the pattern that best fits your project architecture and team structure.