django-ninja-aio-crud 1.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

django_ninja_aio_crud-1.0.1.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.4
+Name: django-ninja-aio-crud
+Version: 1.0.1
+Summary: Django Ninja AIO CRUD - Rest Framework
+Author: Giuseppe Casillo
+Requires-Python: >=3.10
+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 :: 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
+Requires-Dist: joserfc >=1.0.0
+Requires-Dist: orjson >= 3.10.7
+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
+
+# 🥷 django-ninja-aio-crud
+
+![Tests](https://github.com/caspel26/django-ninja-aio-crud/actions/workflows/coverage.yml/badge.svg)
+[![codecov](https://codecov.io/gh/caspel26/django-ninja-aio-crud/graph/badge.svg?token=DZ5WDT3S20)](https://codecov.io/gh/caspel26/django-ninja-aio-crud/)
+[![PyPI - Version](https://img.shields.io/pypi/v/django-ninja-aio-crud?color=g&logo=pypi&logoColor=white)](https://pypi.org/project/django-ninja-aio-crud/)
+[![PyPI - License](https://img.shields.io/pypi/l/django-ninja-aio-crud)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+> Lightweight async CRUD layer on top of **[Django Ninja](https://django-ninja.dev/)** with automatic schema generation, filtering, pagination, auth & Many‑to‑Many management.
+
+---
+
+## ✨ Features
+
+- 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`)
+- Per-method authentication (`auth`, `get_auth`, `post_auth`, etc.)
+- Async pagination (customizable)
+- M2M relation endpoints via `M2MRelationSchema` (add/remove/get + filters)
+- Reverse relation serialization
+- Hook methods (`query_params_handler`, `<related>_query_params_handler`, `custom_actions`, lifecycle hooks)
+- ORJSON renderer through `NinjaAIO`
+- Clean, minimal integration
+
+---
+
+## 📦 Installation
+
+```bash
+pip install django-ninja-aio-crud
+```
+
+Add to your project’s dependencies and ensure Django Ninja is installed.
+
+---
+
+## 🚀 Quick Start
+
+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()
+
+class BookViewSet(APIViewSet):
+    model = Book
+    api = api
+
+BookViewSet().add_views_to_route()
+```
+
+Visit `/docs` → CRUD endpoints ready.
+
+---
+
+## 🔄 Query Filtering
+
+```python
+class BookViewSet(APIViewSet):
+    model = Book
+    api = api
+    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
+```
+
+Request:
+```
+GET /book/?published=true&title=python
+```
+
+---
+
+## 🤝 Many-to-Many Example (with filters)
+
+```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"]
+
+class ArticleViewSet(APIViewSet):
+    model = Article
+    api = api
+    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
+
+ArticleViewSet().add_views_to_route()
+```
+
+Endpoints:
+- `GET /article/{pk}/tag?name=dev`
+- `POST /article/{pk}/tag/` body: `{"add":[1,2],"remove":[3]}`
+
+---
+
+## 🔐 Authentication (JWT example)
+
+```python
+from ninja_aio.auth import AsyncJwtBearer
+from joserfc import jwk
+from .models import Book
+
+PUBLIC_KEY = "-----BEGIN PUBLIC KEY----- ..."
+
+class JWTAuth(AsyncJwtBearer):
+    jwt_public = jwk.RSAKey.import_key(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)
+
+class SecureBookViewSet(APIViewSet):
+    model = Book
+    api = api
+    auth = [JWTAuth()]
+    get_auth = None  # list/retrieve public
+```
+
+---
+
+## 📑 Lifecycle Hooks (ModelSerializer)
+
+Available on every save/delete:
+- `on_create_before_save`
+- `on_create_after_save`
+- `before_save`
+- `after_save`
+- `on_delete`
+- `custom_actions(payload)` (create/update custom field logic)
+- `post_create()` (after create commit)
+
+---
+
+## 🧩 Adding Custom Endpoints
+
+```python
+class BookViewSet(APIViewSet):
+    model = Book
+    api = api
+
+    def views(self):
+        @self.router.get("/stats/")
+        async def stats(request):
+            total = await Book.objects.acount()
+            return {"total": total}
+```
+
+---
+
+## 📄 Pagination
+
+Default: `PageNumberPagination`. Override:
+
+```python
+from ninja.pagination import PageNumberPagination
+
+class LargePagination(PageNumberPagination):
+    page_size = 50
+    max_page_size = 200
+
+class BookViewSet(APIViewSet):
+    model = Book
+    api = api
+    pagination_class = LargePagination
+```
+
+---
+
+## 🛠 Project Structure & Docs
+
+Documentation (MkDocs + Material):
+```
+docs/
+  getting_started/
+  tutorial/
+  api/
+    views/
+    models/
+    authentication.md
+    pagination.md
+```
+
+Browse full reference:
+- APIViewSet: `docs/api/views/api_view_set.md`
+- APIView: `docs/api/views/api_view.md`
+- ModelSerializer: `docs/api/models/model_serializer.md`
+- Authentication: `docs/api/authentication.md`
+- Pagination: `docs/api/pagination.md`
+
+---
+
+## 🧪 Tests
+
+Use Django test runner + async ORM patterns. Example async pattern:
+```python
+obj = await Book.objects.acreate(title="T1", published=True)
+count = await Book.objects.acount()
+```
+
+---
+
+## 🚫 Disable Operations
+
+```python
+class ReadOnlyBookViewSet(APIViewSet):
+    model = Book
+    api = api
+    disable = ["update", "delete"]
+```
+
+---
+
+## 📌 Performance Tips
+
+- Use `queryset_request` classmethod to prefetch
+- Index frequently filtered fields
+- Keep pagination enabled
+- Limit slices (`queryset = queryset[:1000]`) for heavy searches
+
+---
+
+## 🤲 Contributing
+
+1. Fork
+2. Create branch
+3. Add tests
+4. Run lint (`ruff check .`)
+5. Open PR
+
+---
+
+## ⭐ Support
+
+Star the repo or donate:
+- [Buy me a coffee](https://buymeacoffee.com/caspel26)
+
+---
+
+## 📜 License
+
+MIT License. See [LICENSE](LICENSE).
+
+---
+
+## 🔗 Quick Links
+
+| Item | Link |
+|------|------|
+| PyPI | https://pypi.org/project/django-ninja-aio-crud/ |
+| Docs | https://django-ninja-aio.com
+| Issues | https://github.com/caspel26/django-ninja-aio-crud/issues |
+
+---

{django_ninja_aio_crud-1.0.0.dist-info → django_ninja_aio_crud-1.0.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-ninja_aio/__init__.py,sha256=0C1TJ30_2xcqtKhHchk1gb1IzGrxY2u1ufIO-lIRgRM,119
+ninja_aio/__init__.py,sha256=hC9T2fsBJwd5QxeaoghQNrIN1i5mJfBAnK_Ky4lD7zs,119
 ninja_aio/api.py,sha256=Fe6l3YCy7MW5TY4-Lbl80CFuK2NT2Y7tHfmqPk6Mqak,1735
 ninja_aio/auth.py,sha256=zUwruKcz7MXuOnWp5k1CCSwEc8s2Lyqqk7Qm9kPbJ3o,5149
 ninja_aio/decorators.py,sha256=LsvHbMxmw_So8NV0ey5NRRvSbfYkOZLeLQ4Fix7rQAY,5519
@@ -8,8 +8,8 @@ ninja_aio/parsers.py,sha256=e_4lGCPV7zs-HTqtdJTc8yQD2KPAn9njbL8nF_Mmgkc,153
 ninja_aio/renders.py,sha256=0eYklRKd59aV4cZDom5vLZyA99Ob17OwkpMybsRXvyg,1970
 ninja_aio/schemas.py,sha256=iv3VHCMlzez6Qs70zITYIwEz0EFOOaMPDVGRcTZCygA,1875
 ninja_aio/types.py,sha256=TJSGlA7bt4g9fvPhJ7gzH5tKbLagPmZUzfgttEOp4xs,468
-ninja_aio/views.py,sha256=7sv8tpRp8CJC2sxQr-jmbjyjcJe7DabYPf8F7nieZ4Y,23518
-django_ninja_aio_crud-1.0.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
-django_ninja_aio_crud-1.0.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-django_ninja_aio_crud-1.0.0.dist-info/METADATA,sha256=aV0vq6ijySGbggzrwNJ1mCC7HG_6fo1jeF9Ybb_j9Mk,14216
-django_ninja_aio_crud-1.0.0.dist-info/RECORD,,
+ninja_aio/views.py,sha256=EGOqybYR0Y0k7DVlMUwaruyEwF1LTJcM1EeFBU69EL0,23113
+django_ninja_aio_crud-1.0.1.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-1.0.1.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-1.0.1.dist-info/METADATA,sha256=jIF-L1BHlBtCp8n7mTH1IK388J2FP_73567_ppirNUQ,8331
+django_ninja_aio_crud-1.0.1.dist-info/RECORD,,

ninja_aio/__init__.py

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

ninja_aio/views.py

@@ -294,6 +294,7 @@ class APIViewSet:
         """
         Register create endpoint.
         """
+
         @self.router.post(
             self.path,
             auth=self.post_view_auth(),
@@ -311,6 +312,7 @@ class APIViewSet:
         """
         Register list endpoint with pagination and optional filters.
         """
+
         @self.router.get(
             self.get_path,
             auth=self.get_view_auth(),
@@ -347,6 +349,7 @@ class APIViewSet:
         """
         Register retrieve endpoint.
         """
+
         @self.router.get(
             self.get_path_retrieve,
             auth=self.get_view_auth(),
@@ -365,6 +368,7 @@ class APIViewSet:
         """
         Register update endpoint.
         """
+
         @self.router.patch(
             self.path_retrieve,
             auth=self.patch_view_auth(),
@@ -388,6 +392,7 @@ class APIViewSet:
         """
         Register delete endpoint.
         """
+
         @self.router.delete(
             self.path_retrieve,
             auth=self.delete_view_auth(),
@@ -440,140 +445,134 @@ class APIViewSet:
             )
         return errors, objs_detail, objs
 
-    def _m2m_views(self):
+    def _m2m_views(self, m2m_relation: M2MRelationSchema):
         """
         Register M2M get/manage endpoints for each relation in m2m_relations.
         Supports optional per-relation filters and custom query handler:
         <related_name>_query_params_handler.
         """
-        for m2m_data in self.m2m_relations:
-            model = m2m_data.model
-            related_name = m2m_data.related_name
-            m2m_auth = m2m_data.auth or self.m2m_auth
-            rel_util = ModelUtil(model)
-            rel_path = (
-                rel_util.verbose_name_path_resolver()
-                if not m2m_data.path
-                else m2m_data.path
+        model = m2m_relation.model
+        related_name = m2m_relation.related_name
+        m2m_auth = m2m_relation.auth or self.m2m_auth
+        rel_util = ModelUtil(model)
+        rel_path = (
+            rel_util.verbose_name_path_resolver()
+            if not m2m_relation.path
+            else m2m_relation.path
+        )
+        m2m_add = m2m_relation.add
+        m2m_remove = m2m_relation.remove
+        m2m_get = m2m_relation.get
+        filters_schema = self.m2m_filters_schemas.get(related_name)
+        if m2m_get:
+
+            @self.router.get(
+                f"{self.path_retrieve}{rel_path}",
+                response={
+                    200: List[model.generate_related_s(),],
+                    self.error_codes: GenericMessageSchema,
+                },
+                auth=m2m_auth,
+                summary=f"Get {rel_util.model._meta.verbose_name_plural.capitalize()}",
+                description=f"Get all related {rel_util.model._meta.verbose_name_plural.capitalize()}",
             )
-            m2m_add = m2m_data.add
-            m2m_remove = m2m_data.remove
-            m2m_get = m2m_data.get
-            filters_schema = self.m2m_filters_schemas.get(related_name)
-            if m2m_get:
-
-                @self.router.get(
-                    f"{self.path_retrieve}{rel_path}",
-                    response={
-                        200: List[model.generate_related_s(),],
-                        self.error_codes: GenericMessageSchema,
-                    },
-                    auth=m2m_auth,
-                    summary=f"Get {rel_util.model._meta.verbose_name_plural.capitalize()}",
-                    description=f"Get all related {rel_util.model._meta.verbose_name_plural.capitalize()}",
-                )
-                @unique_view(f"get_{self.model_util.model_name}_{rel_path}")
-                @paginate(self.pagination_class)
-                async def get_related(
-                    request: HttpRequest,
-                    pk: Path[self.path_schema],  # type: ignore
-                    filters: Query[filters_schema] = None # type: ignore
-                ):
-                    obj = await self.model_util.get_object(request, self._get_pk(pk))
-                    related_manager = getattr(obj, related_name)
-                    related_qs = related_manager.all()
-                    if (
-                        filters is not None
-                        and (
-                            query_handler := getattr(
-                                self,
-                                f"{m2m_data.related_name}_query_params_handler",
-                                None,
-                            )
-                        )
-                        is not None
-                    ):
-                        related_qs = await query_handler(
-                            related_qs, filters.model_dump()
-                        )
-                    related_objs = [
-                        await rel_util.read_s(
-                            request, rel_obj, model.generate_related_s()
+            @unique_view(f"get_{self.model_util.model_name}_{rel_path}")
+            @paginate(self.pagination_class)
+            async def get_related(
+                request: HttpRequest,
+                pk: Path[self.path_schema],  # type: ignore
+                filters: Query[filters_schema] = None,  # type: ignore
+            ):
+                obj = await self.model_util.get_object(request, self._get_pk(pk))
+                related_manager = getattr(obj, related_name)
+                related_qs = related_manager.all()
+                if (
+                    filters is not None
+                    and (
+                        query_handler := getattr(
+                            self,
+                            f"{m2m_relation.related_name}_query_params_handler",
+                            None,
                         )
-                        async for rel_obj in related_qs
-                    ]
-                    return related_objs
-
-            if m2m_add or m2m_remove:
-                summary = f"{'Add or Remove' if m2m_add and m2m_remove else 'Add' if m2m_add else 'Remove'} {rel_util.model._meta.verbose_name_plural.capitalize()}"
-                description = f"{'Add or remove' if m2m_add and m2m_remove else 'Add' if m2m_add else 'Remove'} {rel_util.model._meta.verbose_name_plural.capitalize()}"
-                schema_in = (
-                    M2MSchemaIn
-                    if m2m_add and m2m_remove
-                    else M2MAddSchemaIn
-                    if m2m_add
-                    else M2MRemoveSchemaIn
-                )
-
-                @self.router.post(
-                    f"{self.path_retrieve}{rel_path}/",
-                    response={
-                        200: M2MSchemaOut,
-                        self.error_codes: GenericMessageSchema,
-                    },
-                    auth=m2m_auth,
-                    summary=summary,
-                    description=description,
-                )
-                @unique_view(f"manage_{self.model_util.model_name}_{rel_path}")
-                async def manage_related(
-                    request: HttpRequest,
-                    pk: Path[self.path_schema],  # type: ignore
-                    data: schema_in,  # type: ignore
+                    )
+                    is not None
                 ):
-                    obj = await self.model_util.get_object(request, self._get_pk(pk))
-                    related_manager: QuerySet = getattr(obj, related_name)
-                    add_errors, add_details, add_objs = [], [], []
-                    remove_errors, remove_details, remove_objs = [], [], []
-
-                    if m2m_add and hasattr(data, "add"):
-                        (
-                            add_errors,
-                            add_details,
-                            add_objs,
-                        ) = await self._check_m2m_objs(
-                            request, data.add, model, related_manager
-                        )
-                    if m2m_remove and hasattr(data, "remove"):
-                        (
-                            remove_errors,
-                            remove_details,
-                            remove_objs,
-                        ) = await self._check_m2m_objs(
-                            request,
-                            data.remove,
-                            model,
-                            related_manager,
-                            remove=True,
-                        )
+                    related_qs = await query_handler(related_qs, filters.model_dump())
+                related_objs = [
+                    await rel_util.read_s(request, rel_obj, model.generate_related_s())
+                    async for rel_obj in related_qs
+                ]
+                return related_objs
+
+        if m2m_add or m2m_remove:
+            summary = f"{'Add or Remove' if m2m_add and m2m_remove else 'Add' if m2m_add else 'Remove'} {rel_util.model._meta.verbose_name_plural.capitalize()}"
+            description = f"{'Add or remove' if m2m_add and m2m_remove else 'Add' if m2m_add else 'Remove'} {rel_util.model._meta.verbose_name_plural.capitalize()}"
+            schema_in = (
+                M2MSchemaIn
+                if m2m_add and m2m_remove
+                else M2MAddSchemaIn
+                if m2m_add
+                else M2MRemoveSchemaIn
+            )
 
-                    await asyncio.gather(
-                        related_manager.aadd(*add_objs),
-                        related_manager.aremove(*remove_objs),
+            @self.router.post(
+                f"{self.path_retrieve}{rel_path}/",
+                response={
+                    200: M2MSchemaOut,
+                    self.error_codes: GenericMessageSchema,
+                },
+                auth=m2m_auth,
+                summary=summary,
+                description=description,
+            )
+            @unique_view(f"manage_{self.model_util.model_name}_{rel_path}")
+            async def manage_related(
+                request: HttpRequest,
+                pk: Path[self.path_schema],  # type: ignore
+                data: schema_in,  # type: ignore
+            ):
+                obj = await self.model_util.get_object(request, self._get_pk(pk))
+                related_manager: QuerySet = getattr(obj, related_name)
+                add_errors, add_details, add_objs = [], [], []
+                remove_errors, remove_details, remove_objs = [], [], []
+
+                if m2m_add and hasattr(data, "add"):
+                    (
+                        add_errors,
+                        add_details,
+                        add_objs,
+                    ) = await self._check_m2m_objs(
+                        request, data.add, model, related_manager
                     )
-                    results = add_details + remove_details
-                    errors = add_errors + remove_errors
-
-                    return {
-                        "results": {
-                            "count": len(results),
-                            "details": results,
-                        },
-                        "errors": {
-                            "count": len(errors),
-                            "details": errors,
-                        },
-                    }
+                if m2m_remove and hasattr(data, "remove"):
+                    (
+                        remove_errors,
+                        remove_details,
+                        remove_objs,
+                    ) = await self._check_m2m_objs(
+                        request,
+                        data.remove,
+                        model,
+                        related_manager,
+                        remove=True,
+                    )
+                await asyncio.gather(
+                    related_manager.aadd(*add_objs),
+                    related_manager.aremove(*remove_objs),
+                )
+                results = add_details + remove_details
+                errors = add_errors + remove_errors
+
+                return {
+                    "results": {
+                        "count": len(results),
+                        "details": results,
+                    },
+                    "errors": {
+                        "count": len(errors),
+                        "details": errors,
+                    },
+                }
 
     def _add_views(self):
         """
@@ -582,7 +581,8 @@ class APIViewSet:
         """
         if "all" in self.disable:
             if self.m2m_relations:
-                self._m2m_views()
+                for m2m_relation in self.m2m_relations:
+                    self._m2m_views(m2m_relation)
             self.views()
             return self.router
 
@@ -594,7 +594,8 @@ class APIViewSet:
 
         self.views()
         if self.m2m_relations:
-            self._m2m_views()
+            for m2m_relation in self.m2m_relations:
+                self._m2m_views(m2m_relation)
         return self.router
 
     def add_views_to_route(self):

django_ninja_aio_crud-1.0.0.dist-info/METADATA

@@ -1,527 +0,0 @@
-Metadata-Version: 2.4
-Name: django-ninja-aio-crud
-Version: 1.0.0
-Summary: Django Ninja AIO CRUD - Rest Framework
-Author: Giuseppe Casillo
-Requires-Python: >=3.10
-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 :: 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
-Requires-Dist: joserfc >=1.0.0
-Requires-Dist: orjson >= 3.10.7
-Requires-Dist: coverage ; extra == "test"
-Project-URL: Documentation, https://caspel26.github.io/django-ninja-aio-crud/
-Project-URL: Repository, https://github.com/caspel26/django-ninja-aio-crud
-Provides-Extra: test
-
-# 🥷 django-ninja-aio-crud
-![Test](https://github.com/caspel26/django-ninja-aio-crud/actions/workflows/coverage.yml/badge.svg)
-[![codecov](https://codecov.io/gh/caspel26/django-ninja-aio-crud/graph/badge.svg?token=DZ5WDT3S20)](https://codecov.io/gh/caspel26/django-ninja-aio-crud)
-[![PyPI - Version](https://img.shields.io/pypi/v/django-ninja-aio-crud?color=g&logo=pypi&logoColor=white)](https://pypi.org/project/django-ninja-aio-crud/)
-[![PyPI - License](https://img.shields.io/pypi/l/django-ninja-aio-crud)](https://github.com/caspel26/django-ninja-aio-crud/blob/main/LICENSE)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-> [!NOTE]
-> Django ninja aio crud framework is based on **<a href="https://django-ninja.dev/">Django Ninja framework</a>**. It comes out with built-in views and models which are able to make automatic async CRUD operations and codes views class based making the developers' life easier and the code cleaner.
-
-## 📝 Instructions
-
-### 📚 Prerequisites
-
-- Install Python from the [official website](https://www.python.org/) (latest version) and ensure it is added to the system Path and environment variables.
-
-### 💻 Setup your environment
-
-- Create a virtual environment
-```bash
-python -m venv .venv
-```
-
-### ✅ Activate it
-
-- If you are from linux activate it with
-
-```bash
-. .venv/bin/activate
-```
-
-- If you are from windows activate it with
-
-```bash
-. .venv/Scripts/activate
-```
-
-### 📥 Install package
-
-```bash
-pip install django-ninja-aio-crud
-```
-
-## 🚀 Usage
-
-> [!TIP]
-> If you find **django ninja aio crud** useful, consider :star: this project
-> and why not ... [Buy me a coffee](https://buymeacoffee.com/caspel26)
-
-### ModelSerializer
-
-- You can serialize your models using ModelSerializer and made them inherit from it. In your models.py import ModelSerializer
-```python
-# models.py
-from django.db import models
-from ninja_aio.models import ModelSerializer
-
-
-class Foo(ModelSerializer):
-  name = models.CharField(max_length=30)
-  bar = models.CharField(max_length=30)
-
-  class ReadSerializer:
-    fields = ["id", "name", "bar"]
-
-  class CreateSerializer:
-    fields = ["name", "bar"]
-
-  class UpdateSerializer:
-    fields = ["name", "bar"]
-```
-
-- ReadSerializer, CreateSerializer, UpdateSerializer are used to define which fields would be included in runtime schemas creation. You can also specify custom fields and handle their function by overriding custom_actions ModelSerializer's method.
-
-```python
-# models.py
-from django.db import models
-from ninja_aio.models import ModelSerializer
-
-
-class Foo(ModelSerializer):
-  name = models.CharField(max_length=30)
-  bar = models.CharField(max_length=30)
-  active = models.BooleanField(default=False)
-
-  class ReadSerializer:
-    fields = ["id", "name", "bar"]
-
-  class CreateSerializer:
-    customs = [("force_activation", bool, False)]
-    fields = ["name", "bar"]
-
-  class UpdateSerializer:
-    fields = ["name", "bar"]
-
-  async def custom_actions(self, payload: dict[str, Any]):
-      if not payload.get("force_activation"):
-          return
-      setattr(self, "force_activation", True)
-
-  async def post_create(self) -> None:
-      if not hasattr(self, "force_activation") or not getattr(self, "force_activation"):
-          return
-      self.active = True
-      await self.asave()
-```
-
-- post create method is a custom method that comes out to handle actions which will be excuted after that the object is created. It can be used, indeed, for example to handle custom fields' actions.
-
-- You can also define optional fields for you Create and Update serializers. To declare an optional fields you have to give the field type too.
-```python
-# models.py
-from django.db import models
-from ninja_aio.models import ModelSerializer
-
-
-class Foo(ModelSerializer):
-  name = models.CharField(max_length=30)
-  bar = models.CharField(max_length=30, default="")
-  active = models.BooleanField(default=False)
-
-  class ReadSerializer:
-    fields = ["id", "name", "bar"]
-
-  class CreateSerializer:
-    fields = ["name"]
-    optionals = [("bar", str), ("active", bool)]
-
-  class UpdateSerializer:
-    optionals = [("bar", str), ("active", bool)]
-```
-
-- Instead of declaring your fields maybe you want to exclude some of them. Declaring "excludes" attribute into serializers will exclude the given fields. (You can declare only one between "fields" and "excludes").
-
-```python
-# models.py
-from django.db import models
-from ninja_aio.models import ModelSerializer
-
-
-class Foo(ModelSerializer):
-  name = models.CharField(max_length=30)
-  bar = models.CharField(max_length=30, default="")
-  active = models.BooleanField(default=False)
-
-  class ReadSerializer:
-    excludes = ["bar"]
-
-  class CreateSerializer:
-    fields = ["name"]
-    optionals = [("bar", str), ("active", bool)]
-
-  class UpdateSerializer:
-    excludes = ["id", "name"]
-    optionals = [("bar", str), ("active", bool)]
-```
-- If you want to add into ReadSerializer model properties you must define them as customs.
-```python
-# models.py
-from django.db import models
-from ninja_aio.models import ModelSerializer
-
-
-class Foo(ModelSerializer):
-  name = models.CharField(max_length=30)
-  bar = models.CharField(max_length=30, default="")
-  active = models.BooleanField(default=False)
-
-  @property
-  def full_name(self):
-    return f"{self.name} example_full_name"
-
-  class ReadSerializer:
-    excludes = ["bar"]
-    customs = [("full_name", str, "")]
-
-  class CreateSerializer:
-    fields = ["name"]
-    optionals = [("bar", str), ("active", bool)]
-
-  class UpdateSerializer:
-    excludes = ["id", "name"]
-    optionals = [("bar", str), ("active", bool)]
-```
-- ModelSerializer comes out also with methods executed on object save and delete, them are:
-
-  1. on_create_before_save: code executed on object creation but before saving;
-  1. on_create_after_save: code executed on object creation but after saving;
-  1. before_save: code executed on every save but before saving;
-  1. after_save: code executed on every save but after saving;
-  1. on_delete: code executed after object delete;
-
-
-### APIViewSet
-
-- View class used to automatically generate CRUD views. in your views.py import APIViewSet and define your api using NinjaAIO class. NinjaAIO class uses built-in parser and renderer which use orjson for data serialization.
-
-```python
-# views.py
-from ninja_aio import NinjaAIO
-from ninja_aio.views import APIViewSet
-
-from .models import Foo
-
-api = NinjaAIO()
-
-
-class FooAPI(APIViewSet):
-  model = Foo
-  api = api
-
-
-FooAPI().add_views_to_route()
-```
-
-- and that's it, your model CRUD will be automatically created. You can also add custom views to CRUD overriding the built-in method "views".
-
-```python
-# views.py
-from ninja import Schema
-from ninja_aio import NinjaAIO
-from ninja_aio.views import APIViewSet
-
-from .models import Foo
-
-api = NinjaAIO()
-
-
-class ExampleSchemaOut(Schema):
-  sum: float
-
-
-class ExampleSchemaIn(Schema):
-  n1: float
-  n2: float
-
-
-class FooAPI(APIViewSet):
-  model = Foo
-  api = api
-
-  def views(self):
-    @self.router.post("numbers-sum/", response={200: ExampleSchemaOut})
-    async def sum(request: HttpRequest, data: ExampleSchemaIn):
-        return 200, {sum: data.n1 + data.n2}
-
-
-FooAPI().add_views_to_route()
-```
-
-- You can also choose to disable any operation from crud by declaring "disbale" attribute. You can give "all" to disable every crud operation except for additional views.
-
-> [!TIP]
-> You can exclude by default an endpoint without declaring the serializer.
-> For example if you don't want to give update method to a CRUD just do not declare UpdateSerializer into model.
-
-```python
-# views.py
-from ninja_aio import NinjaAIO
-from ninja_aio.views import APIViewSet
-
-from .models import Foo
-
-api = NinjaAIO()
-
-
-class FooAPI(APIViewSet):
-  model = Foo
-  api = api
-  disable = ["retrieve", "update"]
-
-
-FooAPI().add_views_to_route()
-```
-For the list endpoint you can also set query params and handle them. They will be also visible into swagger.
-
-```python
-# views.py
-from ninja_aio import NinjaAIO
-from ninja_aio.views import APIViewSet
-
-from .models import Foo
-
-api = NinjaAIO()
-
-
-class FooAPI(APIViewSet):
-  model = Foo
-  api = api
-  query_params = {"name": (str, None), "active": (bool, None)}
-
-  async def query_params_handler(self, queryset, filters):
-      return queryset.filter(**{k: v for k, v in filters.items() if v is not None})
-
-
-FooAPI().add_views_to_route()
-```
-
-### APIView
-
-- View class to code generic views class based. In your views.py import APIView class.
-
-```python
-# views.py
-from ninja import Schema
-from ninja_aio import NinjaAIO
-from ninja_aio.views import APIView
-
-api = NinjaAIO()
-
-
-class ExampleSchemaOut(Schema):
-  sum: float
-
-
-class ExampleSchemaIn(Schema):
-  n1: float
-  n2: float
-
-
-class SumView(APIView):
-  api = api
-  api_router_path = "numbers-sum/"
-  router_tag = "Sum"
-
-  def views(self):
-    @self.router.post("/", response={200: ExampleSchemaOut})
-    async def sum(request: HttpRequest, data: ExampleSchemaIn):
-        return 200, {sum: data.n1 + data.n2}
-
-
-SumView().add_views_to_route()
-```
-
-### Relations
-- You can also set ForeignKey, OneToOne and ManyToMany relations into serialization(reverse relations are supported too). Django ninja aio crud will serialize every of these relation automatically.
-
-- Define models:
-
-```python
-# models.py
-class Bar(ModelSerializer):
-    name = models.CharField(max_length=30)
-    description = models.TextField(max_length=30)
-
-    # ReadSerializer with reverse OneToMany relation (foos)
-    class ReadSerializer:
-        fields = ["id", "name", "description", "foos"]
-
-    class CreateSerializer:
-        fields = ["name", "description"]
-
-    class UpdateSerializer:
-        fields = ["name", "description"]
-
-
-class Foo(ModelSerializer):
-    name = models.CharField(max_length=30)
-    bar = models.ForeignKey(Bar, on_delete=models.CASCADE, related_name="foos")
-
-    class ReadSerializer:
-        fields = ["id", "name", "bar"]
-
-    class CreateSerializer:
-        fields = ["name", "bar"]
-
-    class UpdateSerializer:
-        fields = ["name"]
-```
-
-- Define views:
-
-```python
-# views.py
-from ninja_aio import NinjaAIO
-from ninja_aio.views import APIViewSet
-
-from .models import Foo, Bar
-
-api = NinjaAIO()
-
-
-class FooAPI(APIViewSet):
-  model = Foo
-  api = api
-
-
-class BarAPI(APIViewSet):
-  model = Bar
-  api = api
-
-
-FooAPI().add_views_to_route()
-BarAPI().add_views_to_route()
-```
-
-- Now run your server and go to /docs url:
-
-### Docs
-
-- Foo Schemas
-
-![Swagger UI](docs/images/foo-swagger.png)
-
-- Bar Schemas with reverse relation
-
-![Swagger UI](docs/images/bar-swagger.png)
-
-## 🔒 Authentication
-
-### Jwt
-
-- AsyncJWTBearer built-in class is an authenticator class which use joserfc module. It cames out with authenticate method which validate given claims. Override auth handler method to write your own authentication method. Default algorithms used is RS256. a jwt Token istance is set as class atribute so you can use it by self.dcd.
-
-```python
-from ninja_aio.auth import AsyncJWTBearer
-from django.conf import settings
-from django.http import HttpRequest
-
-from .models import Foo
-
-
-class CustomJWTBearer(AsyncJWTBearer):
-    jwt_public = settings.JWT_PUBLIC
-    claims = {"foo_id": {"essential": True}}
-
-    async def auth_handler(self, request: HttpRequest):
-      try:
-        request.user = await Foo.objects.aget(id=self.dcd.claims["foo_id"])
-      except Foo.DoesNotExist:
-        return None
-      return request.user
-```
-
-- Then add it to views.
-
-```python
-# views.py
-from ninja import Schema
-from ninja_aio import NinjaAIO
-from ninja_aio.views import APIViewSet, APIView
-
-from .models import Foo
-
-api = NinjaAIO()
-
-
-class FooAPI(APIViewSet):
-  model = Foo
-  api = api
-  auth = CustomJWTBearer()
-
-
-class ExampleSchemaOut(Schema):
-  sum: float
-
-
-class ExampleSchemaIn(Schema):
-  n1: float
-  n2: float
-
-
-class SumView(APIView):
-  api = api
-  api_router_path = "numbers-sum/"
-  router_tag = "Sum"
-  auth = CustomJWTBearer()
-
-  def views(self):
-    @self.router.post("/", response={200: ExampleSchemaOut}, auth=self.auth)
-    async def sum(request: HttpRequest, data: ExampleSchemaIn):
-        return 200, {sum: data.n1 + data.n2}
-
-
-FooAPI().add_views_to_route()
-SumView().add_views_to_route()
-```
-
-## 📝 Pagination
-
-- By default APIViewSet list view uses Django Ninja built-in AsyncPagination class "PageNumberPagination". You can customize and assign it to APIViewSet class. To make your custom pagination consult **<a href="https://django-ninja.dev/guides/response/pagination/#async-pagination">Django Ninja pagination documentation</a>**.
-
-```python
-# views.py
-
-class FooAPI(APIViewSet):
-  model = Foo
-  api = api
-  pagination_class = CustomPaginationClass
-
-```
-
-## 📌 Notes
-- Feel free to contribute and improve the program. 🛠️
-