django-ninja-aio-crud 2.2.0__tar.gz → 2.3.0__tar.gz

{django_ninja_aio_crud-2.2.0 → django_ninja_aio_crud-2.3.0}/.github/workflows/docs.yml

@@ -13,6 +13,7 @@ on:
           - stable
           - "1.0"
           - "2.0"
+          - "2.2"
       make_latest:
         description: 'Set as "latest" and default?'
         type: boolean
@@ -29,6 +30,7 @@ on:
           - stable
           - "1.0"
           - "2.0"
+          - "2.2"
       delete_confirm:
         description: 'Confirm deletion of the selected version'
         type: boolean

{django_ninja_aio_crud-2.2.0 → django_ninja_aio_crud-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 2.2.0
+Version: 2.3.0
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
 Requires-Python: >=3.10, <=3.14
@@ -100,11 +100,10 @@ from .models import Book
 
 api = NinjaAIO()
 
+@api.viewset(Book)
 class BookViewSet(APIViewSet):
-    model = Book
-    api = api
+    pass
 
-BookViewSet().add_views_to_route()
 ```
 
 Visit `/docs` → CRUD endpoints ready.
@@ -114,9 +113,8 @@ Visit `/docs` → CRUD endpoints ready.
 ## 🔄 Query Filtering
 
 ```python
+@api.viewset(Book)
 class BookViewSet(APIViewSet):
-    model = Book
-    api = api
     query_params = {"published": (bool, None), "title": (str, None)}
 
     async def query_params_handler(self, queryset, filters):
@@ -151,9 +149,8 @@ class Article(ModelSerializer):
     class ReadSerializer:
         fields = ["id", "title", "tags"]
 
+@api.viewset(Article)
 class ArticleViewSet(APIViewSet):
-    model = Article
-    api = api
     m2m_relations = [
         M2MRelationSchema(
             model=Tag,
@@ -168,7 +165,6 @@ class ArticleViewSet(APIViewSet):
             queryset = queryset.filter(name__icontains=n)
         return queryset
 
-ArticleViewSet().add_views_to_route()
 ```
 
 Endpoints:
@@ -195,9 +191,8 @@ class JWTAuth(AsyncJwtBearer):
         book_id = self.dcd.claims.get("sub")
         return await Book.objects.aget(id=book_id)
 
+@api.viewset(Book)
 class SecureBookViewSet(APIViewSet):
-    model = Book
-    api = api
     auth = [JWTAuth()]
     get_auth = None  # list/retrieve public
 ```
@@ -220,10 +215,21 @@ Available on every save/delete:
 ## 🧩 Adding Custom Endpoints
 
 ```python
+from ninja_aio.decorators import api_get
+
+@api.viewset(Book)
 class BookViewSet(APIViewSet):
-    model = Book
-    api = api
+    @api_get("/stats/")
+    async def stats(self, request):
+        total = await Book.objects.acount()
+        return {"total": total}
+```
+
+Or
 
+```python
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
     def views(self):
         @self.router.get("/stats/")
         async def stats(request):
@@ -288,9 +294,8 @@ count = await Book.objects.acount()
 ## 🚫 Disable Operations
 
 ```python
+@api.viewset(Book)
 class ReadOnlyBookViewSet(APIViewSet):
-    model = Book
-    api = api
     disable = ["update", "delete"]
 ```
 

{django_ninja_aio_crud-2.2.0 → django_ninja_aio_crud-2.3.0}/README.md

@@ -65,11 +65,10 @@ from .models import Book
 
 api = NinjaAIO()
 
+@api.viewset(Book)
 class BookViewSet(APIViewSet):
-    model = Book
-    api = api
+    pass
 
-BookViewSet().add_views_to_route()
 ```
 
 Visit `/docs` → CRUD endpoints ready.
@@ -79,9 +78,8 @@ Visit `/docs` → CRUD endpoints ready.
 ## 🔄 Query Filtering
 
 ```python
+@api.viewset(Book)
 class BookViewSet(APIViewSet):
-    model = Book
-    api = api
     query_params = {"published": (bool, None), "title": (str, None)}
 
     async def query_params_handler(self, queryset, filters):
@@ -116,9 +114,8 @@ class Article(ModelSerializer):
     class ReadSerializer:
         fields = ["id", "title", "tags"]
 
+@api.viewset(Article)
 class ArticleViewSet(APIViewSet):
-    model = Article
-    api = api
     m2m_relations = [
         M2MRelationSchema(
             model=Tag,
@@ -133,7 +130,6 @@ class ArticleViewSet(APIViewSet):
             queryset = queryset.filter(name__icontains=n)
         return queryset
 
-ArticleViewSet().add_views_to_route()
 ```
 
 Endpoints:
@@ -160,9 +156,8 @@ class JWTAuth(AsyncJwtBearer):
         book_id = self.dcd.claims.get("sub")
         return await Book.objects.aget(id=book_id)
 
+@api.viewset(Book)
 class SecureBookViewSet(APIViewSet):
-    model = Book
-    api = api
     auth = [JWTAuth()]
     get_auth = None  # list/retrieve public
 ```
@@ -185,10 +180,21 @@ Available on every save/delete:
 ## 🧩 Adding Custom Endpoints
 
 ```python
+from ninja_aio.decorators import api_get
+
+@api.viewset(Book)
 class BookViewSet(APIViewSet):
-    model = Book
-    api = api
+    @api_get("/stats/")
+    async def stats(self, request):
+        total = await Book.objects.acount()
+        return {"total": total}
+```
+
+Or
 
+```python
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
     def views(self):
         @self.router.get("/stats/")
         async def stats(request):
@@ -253,9 +259,8 @@ count = await Book.objects.acount()
 ## 🚫 Disable Operations
 
 ```python
+@api.viewset(Book)
 class ReadOnlyBookViewSet(APIViewSet):
-    model = Book
-    api = api
     disable = ["update", "delete"]
 ```
 

{django_ninja_aio_crud-2.2.0 → django_ninja_aio_crud-2.3.0}/docs/api/views/api_view.md

@@ -31,9 +31,54 @@ class APIView:
 
 ## Methods
 
-### `views()`
+### Recommended: decorator-based endpoints
 
-Override this method to define your custom endpoints.
+Prefer class method decorators to define non-CRUD endpoints. Decorators lazily bind instance methods to the router and automatically remove `self` from the OpenAPI signature while preserving type hints.
+
+Available decorators (from `ninja_aio.decorators`):
+
+- `@api_get(path, ...)`
+- `@api_post(path, ...)`
+- `@api_put(path, ...)`
+- `@api_patch(path, ...)`
+- `@api_delete(path, ...)`
+- `@api_options(path, ...)`
+- `@api_head(path, ...)`
+
+Example:
+
+```python
+from ninja_aio import NinjaAIO
+from ninja_aio.views import APIView
+from ninja_aio.decorators import api_get, api_post
+from ninja import Schema
+
+api = NinjaAIO(title="My API")
+
+class StatsSchema(Schema):
+    total: int
+    active: int
+
+@api.view(prefix="/analytics", tags=["Analytics"])
+class AnalyticsView(APIView):
+    @api_get("/dashboard", response=StatsSchema)
+    async def dashboard(self, request):
+        return {"total": 1000, "active": 750}
+
+    @api_post("/track")
+    async def track_event(self, request, event: str):
+        return {"tracked": event}
+```
+
+Notes:
+
+- Decorators support per-endpoint `auth`, `response`, `tags`, `summary`, `description`, throttling, and OpenAPI extras.
+- Sync methods run via `sync_to_async` automatically.
+- `self` is excluded from the exposed signature; parameter type hints are preserved.
+
+### Legacy: `views()` (still supported)
+
+You can still override `views()` to define endpoints imperatively.
 
 **Example - Basic Views:**
 
@@ -81,7 +126,7 @@ Registers all defined views to the API instance.
 
 **Returns:** The router instance
 
-**Note:** When using `@api.view(prefix="/path", tags=[...])`, manual registration via `add_views_to_route()` is not required; the router is mounted automatically.
+**Note:** When using `@api.view(prefix="/path", tags=[...])`, the router is mounted automatically and decorator-based endpoints are registered lazily on instantiation; manual registration via `add_views_to_route()` is not required.
 
 ## Complete Example
 
@@ -90,6 +135,7 @@ Registers all defined views to the API instance.
 ```python
 from ninja_aio import NinjaAIO
 from ninja_aio.views import APIView
+from ninja_aio.decorators import api_get, api_post
 from ninja import Schema
 
 api = NinjaAIO(title="My API")
@@ -100,14 +146,13 @@ class StatsSchema(Schema):
 
 @api.view(prefix="/analytics", tags=["Analytics"])
 class AnalyticsView(APIView):
-    def views(self):
-        @self.router.get("/dashboard", response=StatsSchema)
-        async def dashboard(request):
-            return {"total": 1000, "active": 750}
+    @api_get("/dashboard", response=StatsSchema)
+    async def dashboard(self, request):
+        return {"total": 1000, "active": 750}
 
-        @self.router.post("/track")
-        async def track_event(request, event: str):
-            return {"tracked": event}
+    @api_post("/track")
+    async def track_event(self, request, event: str):
+        return {"tracked": event}
 ```
 
 **Alternative implementation:**
@@ -138,6 +183,7 @@ AnalyticsView().add_views_to_route()
 - For CRUD operations, use [`APIViewSet`](api_view_set.md)
 - All views are async-compatible
 - Standard error codes are available via `self.error_codes`
+- Decorator-based endpoints are preferred for clarity and better OpenAPI signatures.
 
 Note:
 

{django_ninja_aio_crud-2.2.0 → django_ninja_aio_crud-2.3.0}/docs/api/views/api_view_set.md

@@ -14,10 +14,84 @@
 
 Notes:
 
-- Retrieve path has no trailing slash; update/delete include a trailing slash.
+- Retrieve path typically includes a trailing slash by default (see settings below); update/delete include a trailing slash.
 - `{base}` auto-resolves from model verbose name plural (lowercase) unless `api_route_path` is provided.
 - Error responses may use a unified generic schema for codes: 400, 401, 404.
 
+### Settings: trailing slash behavior
+
+- NINJA_AIO_APPEND_SLASH (default: True)
+  - When True (default, for backward compatibility), retrieve and POST paths includes a trailing slash into CRUD: `/{base}/{pk}/`.
+  - When False, retrieve and post paths is generated without a trailing slash: `/{base}/{pk}`.
+
+## Recommended: Decorator-based extra endpoints
+
+Use class method decorators to add non-CRUD endpoints to your ViewSet. This is the preferred way to extend a ViewSet with custom routes. The decorators lazily bind instance methods to the router and ensure correct OpenAPI signatures (no `self` in parameters).
+
+Available decorators (from `ninja_aio.decorators`):
+
+- `@api_get(path, ...)`
+- `@api_post(path, ...)`
+- `@api_put(path, ...)`
+- `@api_patch(path, ...)`
+- `@api_delete(path, ...)`
+- `@api_options(path, ...)`
+- `@api_head(path, ...)`
+
+Example:
+
+```python
+from ninja_aio import NinjaAIO
+from ninja_aio.views import APIViewSet
+from ninja_aio.decorators import api_get, api_post
+from .models import Article
+
+api = NinjaAIO(title="Blog API")
+
+@api.viewset(model=Article)
+class ArticleViewSet(APIViewSet):
+    @api_get("/stats/")
+    async def stats(self, request):
+        total = await self.model.objects.acount()
+        return {"total": total}
+
+    @api_post("/{pk}/publish/")
+    async def publish(self, request, pk: int):
+        obj = await self.model.objects.aget(pk=pk)
+        obj.is_published = True
+        await obj.asave()
+        return {"message": "published"}
+```
+
+Notes:
+
+- Decorators support per-endpoint `auth`, `response`, `tags`, `summary`, `description`, and more.
+- Sync methods are executed via `sync_to_async` automatically.
+- Signatures and type hints are preserved for OpenAPI (excluding `self`).
+
+## Legacy: views() method (still supported)
+
+The previous pattern of injecting endpoints inside `views()` is still supported, but the decorator-based approach above is now recommended.
+
+```python
+class ArticleViewSet(APIViewSet):
+    model = Article
+    api = api
+
+    def views(self):
+        @self.router.get("/stats/")
+        async def stats(request):
+            total = await self.model.objects.acount()
+            return {"total": total}
+
+        @self.router.post("/{pk}/publish/")
+        async def publish(request, pk: int):
+            obj = await self.model.objects.aget(pk=pk)
+            obj.is_published = True
+            await obj.asave()
+            return {"message": "published"}
+```
+
 ## Core Attributes
 
 | Attribute          | Type                          | Default                                            | Description                                                             |
@@ -144,6 +218,7 @@ Relations are declared via `M2MRelationSchema` objects (not tuples). Each schema
 - `get`: enable GET listing (bool)
 - `filters`: dict of `{param_name: (type, default)}` for relation-level filtering
 - `related_schema`: optional pre-built schema for the related model (auto-generated if the `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.
 
 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:
@@ -242,12 +317,14 @@ class MyViewSet(APIViewSet):
 
 ### Endpoint paths and operation naming
 
-- GET relation: `/{base}/{pk}/{rel_path}` (no trailing slash)
+- GET relation: `/{base}/{pk}/{rel_path}` by default (no trailing slash). You can enable a trailing slash per relation with `append_slash=True`, resulting in `/{base}/{pk}/{rel_path}/`.
+- POST relation: `/{base}/{pk}/{rel_path}/` (always with trailing slash).
 
-  - OperationId: `get_{base_model_name}_{rel_path}`
+Path normalization rules:
 
-- POST relation: `/{base}/{pk}/{rel_path}/` (trailing slash)
-  - OperationId: `manage_{base_model_name}_{rel_path}`
+- Relation `path` is normalized internally; providing `path` with or without a leading slash produces the same final URL.
+  - Example: `path="tags"` or `path="/tags"` both yield `GET /{base}/{pk}/tags` (or `GET /{base}/{pk}/tags/` when `append_slash=True`) and `POST /{base}/{pk}/tags/`.
+- If `path` is empty, it falls back to the related model verbose name.
 
 ### Request/Response and concurrency
 
@@ -291,9 +368,22 @@ class ArticleViewSet(APIViewSet):
     m2m_auth = [JWTAuth()]  # fallback for relations without custom auth
 ```
 
+Example with trailing slash on GET relation:
+
+```python
+M2MRelationSchema(
+    model=Tag,
+    related_name="tags",
+    filters={"name": (str, "")},
+    append_slash=True,  # GET /{base}/{pk}/tags/
+)
+```
+
 ## Custom Views
 
-Override `views()` to register extra endpoints:
+Preferred (decorators): see the section above.
+
+Legacy (still supported):
 
 ```python
 def views(self):
@@ -329,37 +419,45 @@ All CRUD and M2M endpoints may respond with `GenericMessageSchema` for error cod
 
 ## Minimal Usage
 
-Recommended:
+=== "Recommended"
+    ````python
+    from ninja_aio import NinjaAIO
+    from ninja_aio.views import APIViewSet
+    from .models import User
+    from ninja_aio.decorators import api_get
 
-```python
-from ninja_aio import NinjaAIO
-from ninja_aio.views import APIViewSet
-from .models import User
+    api = NinjaAIO(title="My API")
 
-api = NinjaAIO(title="My API")
-
-@api.viewset(model=User)
-class UserViewSet(APIViewSet):
-    pass
-```
+    @api.viewset(model=User)
+    class UserViewSet(APIViewSet):
+        @api_get("/stats/")
+        async def stats(self, request):
+            total = await self.model.objects.acount()
+            return {"total": total}
+    ```
 
-Note: prefix and tags are optional. If omitted, the base path is inferred from the model verbose name plural and tags default to the model verbose name.
+=== "Alternative implementation"
+    ```python
+    from ninja_aio import NinjaAIO
+    from ninja_aio.views import APIViewSet
+    from .models import User
 
-Alternative implementation:
+    api = NinjaAIO(title="My API")
 
-```python
-from ninja_aio import NinjaAIO
-from ninja_aio.views import APIViewSet
-from .models import User
+    class UserViewSet(APIViewSet):
+        model = User
+        api = api
 
-api = NinjaAIO(title="My API")
+        def views(self):
+            @self.router.get("/stats/")
+            async def stats(request):
+                total = await self.model.objects.acount()
+                return {"total": total}
 
-class UserViewSet(APIViewSet):
-    model = User
-    api = api
+    UserViewSet().add_views_to_route()
+    ```
 
-UserViewSet().add_views_to_route()
-```
+Note: prefix and tags are optional. If omitted, the base path is inferred from the model verbose name plural and tags default to the model verbose name.
 
 ## Disable Selected Views
 
@@ -387,6 +485,7 @@ Recommended:
 from ninja_aio import NinjaAIO
 from ninja_aio.views import APIViewSet
 from ninja_aio.models import ModelSerializer
+from ninja_aio.decorators import api_get
 from django.db import models
 
 api = NinjaAIO(title="My API")

{django_ninja_aio_crud-2.2.0 → django_ninja_aio_crud-2.3.0}/docs/api/views/decorators.md

@@ -63,3 +63,41 @@ class MyViewSet(APIViewSet):
 ```
 
 These are applied in combination with built-ins (e.g., unique_view, paginate) using decorate_view in the implementation.
+
+## ApiMethodFactory.decorators
+
+Example: use api_get within a ViewSet with extra decorators:
+
+```python
+from ninja.pagination import PageNumberPagination
+from ninja_aio.decorators.operations import api_get
+from ninja_aio.views import APIViewSet
+from ninja_aio.models import ModelSerializer
+from ninja_aio.decorators import unique_view
+from ninja.pagination import paginate
+
+from . import models
+
+api = NinjaAIO()
+
+@api.viewset(models.Book)
+class BookAPI(APIViewSet):
+    query_params = {
+        "title": (str, None),
+    }
+
+    @api_get(
+        "/custom-get",
+        response={200: list[GenericMessageSchema]},
+        decorators=[paginate(PageNumberPagination), unique_view("test-unique-view")],
+    )
+    async def get_test(self, request):
+        return [{"message": "This is a custom GET method in BookAPI"}]
+```
+
+Notes:
+
+- Provide decorators as a list; they are applied in reverse order internally.
+- paginate(PageNumberPagination) enables async pagination on the handler.
+- unique_view(name) marks the route as unique to avoid duplicate registration.
+- Works with @api.viewset(Model) classes extending APIViewSet.

{django_ninja_aio_crud-2.2.0 → django_ninja_aio_crud-2.3.0}/ninja_aio/__init__.py

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

django_ninja_aio_crud-2.3.0/ninja_aio/decorators/__init__.py

@@ -0,0 +1,23 @@
+from .views import decorate_view, aatomic, unique_view
+from .operations import (
+    api_get,
+    api_post,
+    api_put,
+    api_delete,
+    api_patch,
+    api_options,
+    api_head,
+)
+
+__all__ = [
+    "decorate_view",
+    "aatomic",
+    "unique_view",
+    "api_get",
+    "api_post",
+    "api_put",
+    "api_delete",
+    "api_patch",
+    "api_options",
+    "api_head",
+]

django_ninja_aio_crud-2.3.0/ninja_aio/decorators/operations.py

@@ -0,0 +1,9 @@
+from ninja_aio.factory import ApiMethodFactory
+
+api_get = ApiMethodFactory.make("get")
+api_post = ApiMethodFactory.make("post")
+api_put = ApiMethodFactory.make("put")
+api_patch = ApiMethodFactory.make("patch")
+api_delete = ApiMethodFactory.make("delete")
+api_options = ApiMethodFactory.make("options")
+api_head = ApiMethodFactory.make("head")

django_ninja_aio_crud-2.2.0/ninja_aio/decorators.py → django_ninja_aio_crud-2.3.0/ninja_aio/decorators/views.py

@@ -1,5 +1,6 @@
-from django.db.transaction import Atomic
 from functools import wraps
+
+from django.db.transaction import Atomic
 from asgiref.sync import sync_to_async
 
 
@@ -189,7 +190,7 @@ def decorate_view(*decorators):
                     @decorate_view(authenticate, log_request)
                     async def some_view(request):
                         ...
-        
+
         Conditional decoration (skips None):
             class MyAPIViewSet(APIViewSet):
                 api = api
@@ -215,4 +216,4 @@ def decorate_view(*decorators):
             wrapped = dec(wrapped)
         return wrapped
 
-    return _decorator
+    return _decorator