django-ninja-aio-crud 2.16.2__py3-none-any.whl → 2.18.0__py3-none-any.whl

django_ninja_aio_crud-2.18.0.dist-info/METADATA

@@ -0,0 +1,425 @@
+Metadata-Version: 2.4
+Name: django-ninja-aio-crud
+Version: 2.18.0
+Summary: Django Ninja AIO CRUD - Rest Framework
+Author: Giuseppe Casillo
+Requires-Python: >=3.10, <3.15
+Description-Content-Type: text/markdown
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Framework :: Django
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Internet :: WWW/HTTP
+License-File: LICENSE
+Requires-Dist: django-ninja >=1.3.0, <1.6
+Requires-Dist: joserfc >=1.0.0, <= 1.4.1
+Requires-Dist: orjson >= 3.10.7, <= 3.11.5
+Requires-Dist: coverage ; extra == "test"
+Project-URL: Documentation, https://django-ninja-aio.com
+Project-URL: Repository, https://github.com/caspel26/django-ninja-aio-crud
+Provides-Extra: test
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/caspel26/django-ninja-aio-crud/main/docs/images/logo.png" alt="django-ninja-aio-crud" width="120">
+</p>
+
+<h1 align="center">django-ninja-aio-crud</h1>
+
+<p align="center">
+  <strong>Async CRUD framework for Django Ninja</strong><br>
+  Automatic schema generation · Filtering · Pagination · Auth · M2M management
+</p>
+
+<p align="center">
+  <a href="https://github.com/caspel26/django-ninja-aio-crud/actions/workflows/coverage.yml"><img src="https://github.com/caspel26/django-ninja-aio-crud/actions/workflows/coverage.yml/badge.svg" alt="Tests"></a>
+  <a href="https://sonarcloud.io/summary/new_code?id=caspel26_django-ninja-aio-crud"><img src="https://sonarcloud.io/api/project_badges/measure?project=caspel26_django-ninja-aio-crud&metric=alert_status" alt="Quality Gate Status"></a>
+  <a href="https://codecov.io/gh/caspel26/django-ninja-aio-crud/"><img src="https://codecov.io/gh/caspel26/django-ninja-aio-crud/graph/badge.svg?token=DZ5WDT3S20" alt="codecov"></a>
+  <a href="https://pypi.org/project/django-ninja-aio-crud/"><img src="https://img.shields.io/pypi/v/django-ninja-aio-crud?color=g&logo=pypi&logoColor=white" alt="PyPI - Version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/pypi/l/django-ninja-aio-crud" alt="PyPI - License"></a>
+  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
+</p>
+
+<p align="center">
+  <a href="https://django-ninja-aio.com">Documentation</a> ·
+  <a href="https://pypi.org/project/django-ninja-aio-crud/">PyPI</a> ·
+  <a href="https://github.com/caspel26/ninja-aio-blog-example">Example Project</a> ·
+  <a href="https://github.com/caspel26/django-ninja-aio-crud/issues">Issues</a>
+</p>
+
+---
+
+## Features
+
+| | Feature | Description |
+|---|---|---|
+| **Meta-driven Serializer** | Dynamic schemas | Generate CRUD schemas for existing Django models without changing base classes |
+| **Async CRUD ViewSets** | Full operations | Create, list, retrieve, update, delete — all async |
+| **Auto Schemas** | Pydantic generation | Automatic read/create/update schemas from `ModelSerializer` |
+| **Dynamic Query Params** | Runtime schemas | Built with `pydantic.create_model` for flexible filtering |
+| **Per-method Auth** | Granular control | `auth`, `get_auth`, `post_auth`, etc. |
+| **Async Pagination** | Customizable | Fully async, pluggable pagination classes |
+| **M2M Relations** | Add/remove/list | Endpoints via `M2MRelationSchema` with filtering support |
+| **Reverse Relations** | Nested serialization | Automatic handling of reverse FK and M2M |
+| **Lifecycle Hooks** | Extensible | `before_save`, `after_save`, `custom_actions`, `on_delete`, and more |
+| **Schema Validators** | Pydantic validators | `@field_validator` and `@model_validator` on serializer classes |
+| **ORJSON Renderer** | Performance | Built-in fast JSON rendering via `NinjaAIO` |
+
+---
+
+## Quick Start
+
+### Option A: Meta-driven Serializer (existing models)
+
+Use this if you already have Django models and don't want to change their base class.
+
+```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
+```
+
+### Option B: ModelSerializer (new projects)
+
+Define models with built-in serialization for minimal boilerplate.
+
+**models.py**
+
+```python
+from django.db import models
+from ninja_aio.models import ModelSerializer
+
+class Book(ModelSerializer):
+    title = models.CharField(max_length=120)
+    published = models.BooleanField(default=True)
+
+    class ReadSerializer:
+        fields = ["id", "title", "published"]
+
+    class CreateSerializer:
+        fields = ["title", "published"]
+
+    class UpdateSerializer:
+        optionals = [("title", str), ("published", bool)]
+```
+
+**views.py**
+
+```python
+from ninja_aio import NinjaAIO
+from ninja_aio.views import APIViewSet
+from .models import Book
+
+api = NinjaAIO()
+
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
+    pass
+```
+
+> Visit `/docs` — CRUD endpoints ready.
+
+---
+
+## Query Filtering
+
+```python
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
+    query_params = {"published": (bool, None), "title": (str, None)}
+
+    async def query_params_handler(self, queryset, filters):
+        if filters.get("published") is not None:
+            queryset = queryset.filter(published=filters["published"])
+        if filters.get("title"):
+            queryset = queryset.filter(title__icontains=filters["title"])
+        return queryset
+```
+
+```
+GET /book/?published=true&title=python
+```
+
+---
+
+## Many-to-Many Relations
+
+```python
+from ninja_aio.schemas import M2MRelationSchema
+
+class Tag(ModelSerializer):
+    name = models.CharField(max_length=50)
+    class ReadSerializer:
+        fields = ["id", "name"]
+
+class Article(ModelSerializer):
+    title = models.CharField(max_length=120)
+    tags = models.ManyToManyField(Tag, related_name="articles")
+    class ReadSerializer:
+        fields = ["id", "title", "tags"]
+
+@api.viewset(Article)
+class ArticleViewSet(APIViewSet):
+    m2m_relations = [
+        M2MRelationSchema(
+            model=Tag,
+            related_name="tags",
+            filters={"name": (str, "")}
+        )
+    ]
+
+    async def tags_query_params_handler(self, queryset, filters):
+        n = filters.get("name")
+        if n:
+            queryset = queryset.filter(name__icontains=n)
+        return queryset
+```
+
+**Endpoints:**
+
+```
+GET  /article/{pk}/tag?name=dev
+POST /article/{pk}/tag/    body: {"add": [1, 2], "remove": [3]}
+```
+
+---
+
+## Authentication (JWT)
+
+```python
+from ninja_aio.auth import AsyncJwtBearer
+from joserfc import jwk
+
+class JWTAuth(AsyncJwtBearer):
+    jwt_public = jwk.RSAKey.import_key("-----BEGIN PUBLIC KEY----- ...")
+    jwt_alg = "RS256"
+    claims = {"sub": {"essential": True}}
+
+    async def auth_handler(self, request):
+        book_id = self.dcd.claims.get("sub")
+        return await Book.objects.aget(id=book_id)
+
+@api.viewset(Book)
+class SecureBookViewSet(APIViewSet):
+    auth = [JWTAuth()]
+    get_auth = None  # list/retrieve remain public
+```
+
+---
+
+## Lifecycle Hooks
+
+Available on every save/delete cycle:
+
+| Hook | When |
+|---|---|
+| `on_create_before_save` | Before first save |
+| `on_create_after_save` | After first save |
+| `before_save` | Before any save |
+| `after_save` | After any save |
+| `on_delete` | After deletion |
+| `custom_actions(payload)` | Create/update custom field logic |
+| `post_create()` | After create commit |
+
+---
+
+## Custom Endpoints
+
+```python
+from ninja_aio.decorators import api_get
+
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
+    @api_get("/stats/")
+    async def stats(self, request):
+        total = await Book.objects.acount()
+        return {"total": total}
+```
+
+---
+
+## Pagination
+
+Default: `PageNumberPagination`. Override per ViewSet:
+
+```python
+from ninja.pagination import PageNumberPagination
+
+class LargePagination(PageNumberPagination):
+    page_size = 50
+    max_page_size = 200
+
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
+    pagination_class = LargePagination
+```
+
+---
+
+## Schema Validators
+
+Add Pydantic `@field_validator` and `@model_validator` directly on serializer classes for input validation.
+
+### ModelSerializer
+
+Declare validators on inner serializer classes:
+
+```python
+from django.db import models
+from pydantic import field_validator, model_validator
+from ninja_aio.models import ModelSerializer
+
+class Book(ModelSerializer):
+    title = models.CharField(max_length=120)
+    description = models.TextField(blank=True)
+
+    class CreateSerializer:
+        fields = ["title", "description"]
+
+        @field_validator("title")
+        @classmethod
+        def validate_title_min_length(cls, v):
+            if len(v) < 3:
+                raise ValueError("Title must be at least 3 characters")
+            return v
+
+    class UpdateSerializer:
+        optionals = [("title", str), ("description", str)]
+
+        @field_validator("title")
+        @classmethod
+        def validate_title_not_empty(cls, v):
+            if v is not None and len(v.strip()) == 0:
+                raise ValueError("Title cannot be blank")
+            return v
+
+    class ReadSerializer:
+        fields = ["id", "title", "description"]
+
+        @model_validator(mode="after")
+        def enrich_output(self):
+            # Transform or enrich the output schema
+            return self
+```
+
+### Meta-driven Serializer
+
+Use dedicated `{Type}Validators` inner classes:
+
+```python
+from pydantic import field_validator, model_validator
+from ninja_aio.models import serializers
+from . import models
+
+class BookSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Book
+        schema_in = serializers.SchemaModelConfig(fields=["title", "description"])
+        schema_out = serializers.SchemaModelConfig(fields=["id", "title", "description"])
+        schema_update = serializers.SchemaModelConfig(
+            optionals=[("title", str), ("description", str)]
+        )
+
+    class CreateValidators:
+        @field_validator("title")
+        @classmethod
+        def validate_title_min_length(cls, v):
+            if len(v) < 3:
+                raise ValueError("Title must be at least 3 characters")
+            return v
+
+    class UpdateValidators:
+        @field_validator("title")
+        @classmethod
+        def validate_title_not_empty(cls, v):
+            if v is not None and len(v.strip()) == 0:
+                raise ValueError("Title cannot be blank")
+            return v
+
+    class ReadValidators:
+        @model_validator(mode="after")
+        def enrich_output(self):
+            return self
+```
+
+**Validator class mapping:**
+
+| Schema type | ModelSerializer | Serializer (Meta-driven) |
+|---|---|---|
+| Create | `CreateSerializer` | `CreateValidators` |
+| Update | `UpdateSerializer` | `UpdateValidators` |
+| Read | `ReadSerializer` | `ReadValidators` |
+| Detail | `DetailSerializer` | `DetailValidators` |
+
+---
+
+## Disable Operations
+
+```python
+@api.viewset(Book)
+class ReadOnlyBookViewSet(APIViewSet):
+    disable = ["update", "delete"]
+```
+
+---
+
+## Performance Tips
+
+- Use `queryset_request` classmethod to `select_related` / `prefetch_related`
+- Index frequently filtered fields
+- Keep pagination enabled for large datasets
+- Limit slices (`queryset = queryset[:1000]`) for heavy searches
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for your changes
+4. Run lint: `ruff check .`
+5. Open a Pull Request
+
+---
+
+## Support
+
+If you find this project useful, consider giving it a star or supporting development:
+
+<a href="https://buymeacoffee.com/caspel26"><img src="https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy me a coffee"></a>
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+

{django_ninja_aio_crud-2.16.2.dist-info → django_ninja_aio_crud-2.18.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-ninja_aio/__init__.py,sha256=T_ERynU6iChK83VokT16riNn-rjWDvI9TKAOwaEpy68,120
+ninja_aio/__init__.py,sha256=CezrF0WOFMCLNAybIgP0uAtNTsUMEiOezULFLq3iluY,120
 ninja_aio/api.py,sha256=tuC7vdvn7s1GkCnSFy9Kn1zv0glZfYptRQVvo8ZRtGQ,2429
 ninja_aio/auth.py,sha256=f4yk45fLi36Qctu0A0zgHTFedb9yk3ewq5rOMpoPYIE,9035
 ninja_aio/exceptions.py,sha256=w8QWmVlg88iJvBrNODSDBHSsy8nNpwngaCGWRnkXoPo,3899
@@ -14,7 +14,7 @@ ninja_aio/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU
 ninja_aio/helpers/api.py,sha256=va_HvZVBFm1KxwQhH4u09U4F1JS5JrQuRpRmPTHJt7w,21326
 ninja_aio/helpers/query.py,sha256=Lqv4nrWYr543tC5K-SEcBottLID8cb83aDc26i2Wxj4,5053
 ninja_aio/models/__init__.py,sha256=L3UQnQAlKoI3F7jinadL-Nn55hkPvnSRPYW0JtnbWFo,114
-ninja_aio/models/serializers.py,sha256=yUMfVu-95EuT5wet2nwFnQlxJYSm8CFGLwKlGr6QBao,43297
+ninja_aio/models/serializers.py,sha256=Obw6HCLMU9iTvAtuoGFXB2gtRELtR3g1nhn23U9McrM,60376
 ninja_aio/models/utils.py,sha256=lAXtc3YY7_n4f0jIacX4DSXhUOzMy7y5MsBnInNxtfk,32874
 ninja_aio/schemas/__init__.py,sha256=dHILiYBKMb51lDcyQdiXRw_0nzqM7Lu81UX2hv7kEfo,837
 ninja_aio/schemas/api.py,sha256=dGUpJXR1iAf93QNR4kYj1uqIkTjiMfXultCotY6GtaQ,361
@@ -24,7 +24,7 @@ ninja_aio/schemas/helpers.py,sha256=CpubwNXsZHtu8jddliyQybF1epwZ-GO60vHIuF5AR1Y,
 ninja_aio/views/__init__.py,sha256=DEzjWA6y3WF0V10nNF8eEurLNEodgxKzyFd09AqVp3s,148
 ninja_aio/views/api.py,sha256=AAqkj0xT8J3PmJvsbluZ33cfrmrXJHiV9ARe2BqnfQ8,22492
 ninja_aio/views/mixins.py,sha256=Zl6J8gbVagwT85bzDuKyJTk3iFxxFgX0YgYkjiUxZGg,17040
-django_ninja_aio_crud-2.16.2.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
-django_ninja_aio_crud-2.16.2.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-django_ninja_aio_crud-2.16.2.dist-info/METADATA,sha256=k17Ia6_VlPDH92UIsN0OQjOrj_IYOfZyffyFMbrP-xw,9964
-django_ninja_aio_crud-2.16.2.dist-info/RECORD,,
+django_ninja_aio_crud-2.18.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-2.18.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-2.18.0.dist-info/METADATA,sha256=2R1JT9MbqKfuAb05If2Ic1U-Cx6l_uTcXLPKHIyod5Q,12911
+django_ninja_aio_crud-2.18.0.dist-info/RECORD,,

ninja_aio/__init__.py

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