django-ninja-aio-crud 2.2.0__py3-none-any.whl → 2.3.1__py3-none-any.whl

{django_ninja_aio_crud-2.2.0.dist-info → django_ninja_aio_crud-2.3.1.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 2.2.0
+Version: 2.3.1
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
-Requires-Python: >=3.10, <=3.14
+Requires-Python: >=3.10, <3.15
 Description-Content-Type: text/markdown
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Internet
@@ -74,6 +74,7 @@ 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
@@ -93,6 +94,7 @@ class Book(ModelSerializer):
 ```
 
 views.py
+
 ```python
 from ninja_aio import NinjaAIO
 from ninja_aio.views import APIViewSet
@@ -100,11 +102,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 +115,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):
@@ -128,6 +128,7 @@ class BookViewSet(APIViewSet):
 ```
 
 Request:
+
 ```
 GET /book/?published=true&title=python
 ```
@@ -151,9 +152,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,10 +168,10 @@ class ArticleViewSet(APIViewSet):
             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]}`
 
@@ -195,9 +195,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
 ```
@@ -207,6 +206,7 @@ class SecureBookViewSet(APIViewSet):
 ## 📑 Lifecycle Hooks (ModelSerializer)
 
 Available on every save/delete:
+
 - `on_create_before_save`
 - `on_create_after_save`
 - `before_save`
@@ -220,10 +220,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):
@@ -244,9 +255,8 @@ class LargePagination(PageNumberPagination):
     page_size = 50
     max_page_size = 200
 
+@api.viewset(Book)
 class BookViewSet(APIViewSet):
-    model = Book
-    api = api
     pagination_class = LargePagination
 ```
 
@@ -255,6 +265,7 @@ class BookViewSet(APIViewSet):
 ## 🛠 Project Structure & Docs
 
 Documentation (MkDocs + Material):
+
 ```
 docs/
   getting_started/
@@ -267,17 +278,19 @@ docs/
 ```
 
 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`
+- Example repository: https://github.com/caspel26/ninja-aio-blog-example
 
 ---
 
 ## 🧪 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()
@@ -288,9 +301,8 @@ count = await Book.objects.acount()
 ## 🚫 Disable Operations
 
 ```python
+@api.viewset(Book)
 class ReadOnlyBookViewSet(APIViewSet):
-    model = Book
-    api = api
     disable = ["update", "delete"]
 ```
 
@@ -318,6 +330,7 @@ class ReadOnlyBookViewSet(APIViewSet):
 ## ⭐ Support
 
 Star the repo or donate:
+
 - [Buy me a coffee](https://buymeacoffee.com/caspel26)
 
 ---
@@ -330,11 +343,12 @@ 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 |
+| 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 |
+| Example | https://github.com/caspel26/ninja-aio-blog-example       |
 
 ---
 

django_ninja_aio_crud-2.3.1.dist-info/RECORD

@@ -0,0 +1,27 @@
+ninja_aio/__init__.py,sha256=gBYKYp-SDpKV643SKBBLVlAZrsk3j6ndnV-oOP-Z56U,119
+ninja_aio/api.py,sha256=tuC7vdvn7s1GkCnSFy9Kn1zv0glZfYptRQVvo8ZRtGQ,2429
+ninja_aio/auth.py,sha256=4sWdFPjKiQgUL1d_CSGDblVjnY5ptP6LQha6XXdluJA,9157
+ninja_aio/exceptions.py,sha256=_3xFqfFCOfrrMhSA0xbMqgXy8R0UQjhXaExrFvaDAjY,3891
+ninja_aio/models.py,sha256=aJlo5a64O4o-fB8QESLMUJpoA5kcjRJxPBiAIMxg46k,47652
+ninja_aio/parsers.py,sha256=e_4lGCPV7zs-HTqtdJTc8yQD2KPAn9njbL8nF_Mmgkc,153
+ninja_aio/renders.py,sha256=VtmSliRJyZ6gjyoib8AXMVUBYF1jPNsiceCHujI_mAs,1699
+ninja_aio/types.py,sha256=nFqWEopm7eoEaHRzbi6EyA9WZ5Cneyd602ilFKypeQI,577
+ninja_aio/decorators/__init__.py,sha256=cDDHD_9EI4CP7c5eL1m2mGNl9bR24i8FAkQsT3_RNGM,371
+ninja_aio/decorators/operations.py,sha256=L9yt2ku5oo4CpOLixCADmkcFjLGsWAn-cg-sDcjFhMA,343
+ninja_aio/decorators/views.py,sha256=0RVU4XaM1HvTQ-BOt_NwUtbhwfHau06lh-O8El1LqQk,8139
+ninja_aio/factory/__init__.py,sha256=IdH2z1ZZpv_IqonaDfVo7IsMzkgop6lHqz42RphUYBU,72
+ninja_aio/factory/operations.py,sha256=OgWGqq4WJ4arSQrH9FGAby9kx-HTdS7MOITxHdYMk18,12051
+ninja_aio/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ninja_aio/helpers/api.py,sha256=YMzuZ4-ZpUrJBQIabE26gb_GYwsH2rVosWRE95YfdPQ,20775
+ninja_aio/helpers/query.py,sha256=YJMdEonCuqx1XjmszCK74mg5hcUPh84ynXrsuoSQdNA,4519
+ninja_aio/schemas/__init__.py,sha256=iLBwHg0pmL9k_UkIui5Q8QIl_gO4fgxSv2JHxDzqnSI,549
+ninja_aio/schemas/api.py,sha256=-VwXhBRhmMsZLIAmWJ-P7tB5klxXS75eukjabeKKYsc,360
+ninja_aio/schemas/generics.py,sha256=frjJsKJMAdM_NdNKv-9ddZNGxYy5PNzjIRGtuycgr-w,112
+ninja_aio/schemas/helpers.py,sha256=W6IeHi5Tmbjh3FXwDYqjqlLBTVj5uTYq3_JVkNUWayo,7355
+ninja_aio/views/__init__.py,sha256=DEzjWA6y3WF0V10nNF8eEurLNEodgxKzyFd09AqVp3s,148
+ninja_aio/views/api.py,sha256=jJ0Awl9ynuvM6rWetgp9KHTKlnwREyjl2cxCobY4I_4,20158
+ninja_aio/views/mixins.py,sha256=Jh6BG8Cs823nurVlODlzCquTxKrLH7Pmo5udPqUGZek,11378
+django_ninja_aio_crud-2.3.1.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-2.3.1.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-2.3.1.dist-info/METADATA,sha256=74hdMdbaOSFTfpFXJVgZ_0bydVBGNsO8rnZHOBDTvZg,9047
+django_ninja_aio_crud-2.3.1.dist-info/RECORD,,

ninja_aio/__init__.py

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

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",
+]

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")

ninja_aio/{decorators.py → 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

ninja_aio/exceptions.py

@@ -1,5 +1,4 @@
 from functools import partial
-
 from joserfc.errors import JoseError
 from ninja import NinjaAPI
 from django.http import HttpRequest, HttpResponse
@@ -8,6 +7,8 @@ from django.db.models import Model
 
 
 class BaseException(Exception):
+    """Base application exception carrying a serializable error payload and status code."""
+
     error: str | dict = ""
     status_code: int = 400
 
@@ -17,6 +18,11 @@ class BaseException(Exception):
         status_code: int | None = None,
         details: str | None = None,
     ) -> None:
+        """Initialize the exception with error content, optional HTTP status, and details.
+
+        If `error` is a string, it is wrapped into a dict under the `error` key.
+        If `error` is a dict, it is used directly. Optional `details` are merged.
+        """
         if isinstance(error, str):
             self.error = {"error": error}
         if isinstance(error, dict):
@@ -25,22 +31,30 @@ class BaseException(Exception):
         self.status_code = status_code or self.status_code
 
     def get_error(self):
+        """Return the error body and HTTP status code tuple for response creation."""
         return self.error, self.status_code
 
 
 class SerializeError(BaseException):
+    """Raised when serialization to or from request/response payloads fails."""
+
     pass
 
 
 class AuthError(BaseException):
+    """Raised when authentication or authorization fails."""
+
     pass
 
 
 class NotFoundError(BaseException):
+    """Raised when a requested model instance cannot be found."""
+
     status_code = 404
     error = "not found"
 
     def __init__(self, model: Model, details=None):
+        """Build a not-found error referencing the model's verbose name."""
         super().__init__(
             error={model._meta.verbose_name.replace(" ", "_"): self.error},
             status_code=self.status_code,
@@ -49,19 +63,24 @@ class NotFoundError(BaseException):
 
 
 class PydanticValidationError(BaseException):
+    """Wrapper for pydantic ValidationError to normalize the API error response."""
+
     def __init__(self, details=None):
+        """Create a validation error with 400 status and provided details list."""
         super().__init__("Validation Error", 400, details)
 
 
 def _default_error(
     request: HttpRequest, exc: BaseException, api: type[NinjaAPI]
 ) -> HttpResponse:
+    """Default handler: convert BaseException to an API response."""
     return api.create_response(request, exc.error, status=exc.status_code)
 
 
 def _pydantic_validation_error(
     request: HttpRequest, exc: ValidationError, api: type[NinjaAPI]
 ) -> HttpResponse:
+    """Translate a pydantic ValidationError into a normalized API error response."""
     error = PydanticValidationError(exc.errors(include_input=False))
     return api.create_response(request, error.error, status=error.status_code)
 
@@ -69,11 +88,13 @@ def _pydantic_validation_error(
 def _jose_error(
     request: HttpRequest, exc: JoseError, api: type[NinjaAPI]
 ) -> HttpResponse:
+    """Translate a JOSE library error into an unauthorized API response."""
     error = BaseException(**parse_jose_error(exc), status_code=401)
     return api.create_response(request, error.error, status=error.status_code)
 
 
 def set_api_exception_handlers(api: type[NinjaAPI]) -> None:
+    """Register exception handlers for common error types on the NinjaAPI instance."""
     api.add_exception_handler(BaseException, partial(_default_error, api=api))
     api.add_exception_handler(JoseError, partial(_jose_error, api=api))
     api.add_exception_handler(
@@ -82,6 +103,7 @@ def set_api_exception_handlers(api: type[NinjaAPI]) -> None:
 
 
 def parse_jose_error(jose_exc: JoseError) -> dict:
+    """Extract error and optional description from a JoseError into a dict."""
     error_msg = {"error": jose_exc.error}
     return (
         error_msg | {"details": jose_exc.description}

ninja_aio/factory/__init__.py

@@ -0,0 +1,3 @@
+from .operations import ApiMethodFactory
+
+__all__ = ["ApiMethodFactory"]

ninja_aio/factory/operations.py

@@ -0,0 +1,296 @@
+import asyncio
+from typing import (
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Union,
+    Any,
+)
+import inspect
+
+from ninja.constants import NOT_SET, NOT_SET_TYPE
+from ninja.throttling import BaseThrottle
+from ninja import Router
+
+
+class ApiMethodFactory:
+    """
+    Factory for creating class-bound API method decorators that register endpoints
+    on a Ninja Router from instance methods.
+
+    This class enables defining API handlers as instance methods while ensuring
+    the resulting callables exposed to Ninja are free of `self`/`cls` in their
+    OpenAPI signatures, preventing them from being interpreted as query params.
+
+    Typical usage:
+    - Use ApiMethodFactory.make("get" | "post" | "put" | "delete" | ...) to produce
+        a decorator that can be applied to an instance method on a view class.
+    - When the owning instance (e.g., a subclass of ninja_aio.views.api.API) is
+        created, the method is lazily registered on its `router` with the provided
+        configuration (path, auth, response, tags, etc.).
+
+    The factory supports both sync and async methods. It wraps the original method
+    with a handler whose first argument is `request` (as expected by Ninja),
+    internally binding `self` from the instance so you can still write methods
+    naturally.
+
+    Attributes:
+    - method_name: The HTTP method name used to select the corresponding Router
+        adder (e.g., "get", "post", etc.).
+
+    __init__(method_name: str)
+            Initialize the factory for a specific HTTP method.
+
+            Parameters:
+            - method_name: The name of the Router method to call (e.g., "get", "post").
+                This determines which endpoint registration function is used on the router.
+
+    _build_handler(view_instance, original)
+            Build a callable that Ninja can use as the endpoint handler, correctly
+            binding `self` and presenting a `request`-first signature.
+
+            Behavior:
+            - If the original method is async, return an async wrapper that awaits it.
+            - If the original method is sync, return a sync wrapper that calls it.
+            - The wrapper passes (view_instance, request, *args, **kwargs) to the
+                original method, ensuring instance binding while exposing a clean handler
+                to Ninja.
+
+            Parameters:
+            - view_instance: The object instance that owns the router and the method.
+            - original: The original instance method to be wrapped.
+
+            Returns:
+            - A callable suitable for Ninja route registration (sync or async).
+
+    _apply_metadata(clean_handler, original)
+            Copy relevant metadata from the original method to the wrapped handler to
+            improve OpenAPI generation and introspection.
+
+            Behavior:
+            - Preserve the function name where possible.
+            - Replace the __signature__ to exclude the first parameter if it is
+                `self` or `cls`, ensuring Ninja does not treat them as parameters.
+            - Copy annotations while removing `self` to avoid unwanted schema entries.
+
+            Parameters:
+            - clean_handler: The wrapped function produced by _build_handler.
+            - original: The original method from which metadata will be copied.
+
+    build_decorator(
+            auth=NOT_SET,
+            throttle=NOT_SET,
+            response=NOT_SET,
+            Create and return a decorator that can be applied to an instance method to
+            lazily register it as an endpoint when the instance is initialized.
+
+            How it works:
+            - The decorator attaches an `_api_register` callable to the method.
+            - When invoked with an API view instance, `_api_register` resolves the
+                instance’s `router`, wraps the method via _build_handler, applies metadata
+                via _apply_metadata, and registers the handler using the router’s method
+                corresponding to `method_name` (e.g., router.get).
+
+            Parameters mirror Ninja Router endpoint registration and control OpenAPI
+            generation and request handling:
+            - path: Route path for the endpoint.
+            - auth: Authentication configuration or NOT_SET.
+            - throttle: Throttle configuration(s) or NOT_SET.
+            - response: Response schema/model or NOT_SET.
+            - operation_id: Optional OpenAPI operation identifier.
+            - summary: Short summary for OpenAPI.
+            - description: Detailed description for OpenAPI.
+            - tags: Grouping tags for OpenAPI.
+            - deprecated: Mark endpoint as deprecated in OpenAPI.
+            - by_alias, exclude_unset, exclude_defaults, exclude_none: Pydantic-related
+                serialization options for response models.
+            - url_name: Optional Django URL name.
+            - include_in_schema: Whether to include this endpoint in OpenAPI schema.
+            - openapi_extra: Additional raw OpenAPI metadata.
+
+            Returns:
+            - A decorator to apply to sync/async instance methods.
+
+    make(method_name: str)
+            Class method that returns a ready-to-use decorator function for the given
+            HTTP method, suitable for direct use on instance methods.
+
+            Example:
+                    api_get = ApiMethodFactory.make("get")
+
+                    class MyView(API):
+                            router = Router()
+
+                            @api_get("/items")
+                            async def list_items(self, request):
+                                    ...
+
+            Parameters:
+            - method_name: The HTTP method name to bind (e.g., "get", "post", "put").
+
+            Returns:
+            - A function that mirrors build_decorator’s signature, named
+                "api_{method_name}", with a docstring indicating it registers the
+                corresponding HTTP endpoint on the instance router.
+    """
+
+    def __init__(self, method_name: str):
+        self.method_name = method_name
+
+    def _build_handler(self, view_instance, original):
+        is_async = asyncio.iscoroutinefunction(original)
+
+        if is_async:
+
+            async def clean_handler(request, *args, **kwargs):
+                return await original(view_instance, request, *args, **kwargs)
+        else:
+
+            def clean_handler(request, *args, **kwargs):
+                return original(view_instance, request, *args, **kwargs)
+
+        return clean_handler
+
+    def _apply_metadata(self, clean_handler, original):
+        # name
+        try:
+            clean_handler.__name__ = getattr(
+                original, "__name__", clean_handler.__name__
+            )
+        except Exception:
+            pass
+
+        # signature and annotations without self/cls
+        try:
+            sig = inspect.signature(original)
+            params = sig.parameters
+            params_list = list(params.values())
+            if params_list and params_list[0].name in {"self", "cls"}:
+                params_list = params_list[1:]
+            clean_handler.__signature__ = sig.replace(parameters=params_list)  # type: ignore[attr-defined]
+
+            anns = dict(getattr(original, "__annotations__", {}))
+            anns.pop("self", None)
+            clean_handler.__annotations__ = anns
+        except Exception:
+            pass
+
+    def build_decorator(
+        self,
+        path: str,
+        *,
+        auth: Any = NOT_SET,
+        throttle: Union[BaseThrottle, List[BaseThrottle], NOT_SET_TYPE] = NOT_SET,
+        response: Any = NOT_SET,
+        operation_id: Optional[str] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        deprecated: Optional[bool] = None,
+        by_alias: Optional[bool] = None,
+        exclude_unset: Optional[bool] = None,
+        exclude_defaults: Optional[bool] = None,
+        exclude_none: Optional[bool] = None,
+        url_name: Optional[str] = None,
+        include_in_schema: bool = True,
+        openapi_extra: Optional[Dict[str, Any]] = None,
+        decorators: Optional[List[Callable]] = None,  # es. [paginate(...)]
+    ):
+        """
+        Returns a decorator that can be applied to an async or sync instance method.
+        When the instance is created and owns a `router`, the wrapped method is
+        registered on that router using the provided configuration.
+        """
+
+        def decorator(func):
+            from ninja_aio.views.api import API
+
+            def register_on_instance(view_instance: API):
+                router: Router = getattr(view_instance, "router", None)
+                if router is None:
+                    raise RuntimeError("The view instance does not have a router")
+
+                clean_handler = self._build_handler(view_instance, func)
+                self._apply_metadata(clean_handler, func)
+
+                # Apply additional decorators if any
+                if decorators:
+                    for dec in reversed(decorators):
+                        clean_handler = dec(clean_handler)
+
+                route_adder = getattr(router, self.method_name)
+                route_adder(
+                    path=path,
+                    auth=auth,
+                    throttle=throttle,
+                    response=response,
+                    operation_id=operation_id,
+                    summary=summary,
+                    description=description,
+                    tags=tags,
+                    deprecated=deprecated,
+                    by_alias=by_alias,
+                    exclude_unset=exclude_unset,
+                    exclude_defaults=exclude_defaults,
+                    exclude_none=exclude_none,
+                    url_name=url_name,
+                    include_in_schema=include_in_schema,
+                    openapi_extra=openapi_extra,
+                )(clean_handler)
+
+            setattr(func, "_api_register", register_on_instance)
+            return func
+
+        return decorator
+
+    @classmethod
+    def make(cls, method_name: str):
+        """Factory returning a decorator function for the given HTTP method."""
+
+        def wrapper(
+            path: str,
+            *,
+            auth: Any = NOT_SET,
+            throttle: Union[BaseThrottle, List[BaseThrottle], NOT_SET_TYPE] = NOT_SET,
+            response: Any = NOT_SET,
+            operation_id: Optional[str] = None,
+            summary: Optional[str] = None,
+            description: Optional[str] = None,
+            tags: Optional[List[str]] = None,
+            deprecated: Optional[bool] = None,
+            by_alias: Optional[bool] = None,
+            exclude_unset: Optional[bool] = None,
+            exclude_defaults: Optional[bool] = None,
+            exclude_none: Optional[bool] = None,
+            url_name: Optional[str] = None,
+            include_in_schema: bool = True,
+            openapi_extra: Optional[Dict[str, Any]] = None,
+            decorators: Optional[List[Callable]] = None,  # es. [paginate(...)]
+        ):
+            return cls(method_name).build_decorator(
+                path,
+                auth=auth,
+                throttle=throttle,
+                response=response,
+                operation_id=operation_id,
+                summary=summary,
+                description=description,
+                tags=tags,
+                deprecated=deprecated,
+                by_alias=by_alias,
+                exclude_unset=exclude_unset,
+                exclude_defaults=exclude_defaults,
+                exclude_none=exclude_none,
+                url_name=url_name,
+                include_in_schema=include_in_schema,
+                openapi_extra=openapi_extra,
+                decorators=decorators,
+            )
+
+        wrapper.__name__ = f"api_{method_name}"
+        wrapper.__doc__ = (
+            f"Class method decorator that lazily registers a {method_name.upper()} endpoint on the instance router.\n\n"
+            f"Parameters mirror api_get."
+        )
+        return wrapper

ninja_aio/helpers/api.py

@@ -337,6 +337,17 @@ class ManyToManyAPI:
             remove=remove,
         )
 
+    def _get_api_path(self, rel_path: str, append_slash: bool = None) -> str:
+        append_slash = append_slash if append_slash is not None else True
+        path = (
+            f"{self.view_set.path_retrieve}{rel_path}/"
+            if rel_path.startswith("/")
+            else f"{self.view_set.path_retrieve}/{rel_path}/"
+        )
+        if not append_slash:
+            path = path.rstrip("/")
+        return path
+
     def _register_get_relation_view(
         self,
         *,
@@ -346,9 +357,10 @@ class ManyToManyAPI:
         rel_path: str,
         related_schema,
         filters_schema,
+        append_slash: bool,
     ):
         @self.router.get(
-            f"{self.view_set.path_retrieve}{rel_path}",
+            self._get_api_path(rel_path, append_slash=append_slash),
             response={
                 200: list[related_schema],
                 self.view_set.error_codes: GenericMessageSchema,
@@ -400,7 +412,7 @@ class ManyToManyAPI:
         summary = f"{action} {plural}"
 
         @self.router.post(
-            f"{self.view_set.path_retrieve}{rel_path}/",
+            self._get_api_path(rel_path),
             response={
                 200: M2MSchemaOut,
                 self.view_set.error_codes: GenericMessageSchema,
@@ -465,6 +477,7 @@ class ManyToManyAPI:
         related_schema = relation.related_schema
         m2m_add, m2m_remove, m2m_get = relation.add, relation.remove, relation.get
         filters_schema = self.relations_filters_schemas.get(related_name)
+        append_slash = relation.append_slash
 
         if m2m_get:
             self._register_get_relation_view(
@@ -474,6 +487,7 @@ class ManyToManyAPI:
                 rel_path=rel_path,
                 related_schema=related_schema,
                 filters_schema=filters_schema,
+                append_slash=append_slash,
             )
 
         if m2m_add or m2m_remove:

ninja_aio/helpers/query.py

@@ -8,10 +8,12 @@ from ninja_aio.schemas.helpers import (
 
 class ScopeNamespace:
     def __init__(self, **scopes):
+        """Create a simple namespace where each provided scope becomes an attribute."""
         for key, value in scopes.items():
             setattr(self, key, value)
 
     def __iter__(self):
+        """Iterate over the stored scope values."""
         return iter(self.__dict__.values())
 
 
@@ -51,6 +53,7 @@ class QueryUtil:
     SCOPES: QueryUtilBaseScopesSchema
 
     def __init__(self, model: ModelSerializerMeta):
+        """Initialize QueryUtil, resolving base and extra scope configurations for a model."""
         self.model = model
         self._configuration = getattr(self.model, "QuerySet", None)
         self._extra_configuration: list[ModelQuerySetExtraSchema] = getattr(
@@ -66,7 +69,9 @@ class QueryUtil:
             **{scope: self._get_config(scope) for scope in self._BASE_SCOPES.values()},
             **self.extra_configs,
         }
-        self.read_config: ModelQuerySetSchema = self._configs.get(self.SCOPES.READ, ModelQuerySetSchema())
+        self.read_config: ModelQuerySetSchema = self._configs.get(
+            self.SCOPES.READ, ModelQuerySetSchema()
+        )
         self.queryset_request_config: ModelQuerySetSchema = self._configs.get(
             self.SCOPES.QUERYSET_REQUEST, ModelQuerySetSchema()
         )

ninja_aio/schemas/helpers.py

@@ -8,24 +8,50 @@ from pydantic import BaseModel, ConfigDict, model_validator
 
 class M2MRelationSchema(BaseModel):
     """
-    Configuration schema for declaring a Many-to-Many relation in the API.
-
-    Attributes:
-        model (Type[ModelSerializer] | Type[Model]): Target model class or its serializer.
-        related_name (str): Name of the relationship field on the Django model.
-        add (bool): Enable adding related objects (default True).
-        remove (bool): Enable removing related objects (default True).
-        get (bool): Enable retrieving related objects (default True).
-        path (str | None): Optional custom URL path segment (None/"" => auto-generated).
-        auth (list | None): Optional list of authentication backends for the endpoints.
-        filters (dict[str, tuple] | None): Field name -> (type, default) pairs for query filtering.
-
-    Example:
-        M2MRelationSchema(
-            model=BookSerializer,
-            related_name="authors",
-            filters={"country": ("str", '')}
-        )
+    Configuration schema for declaring and controlling a Many-to-Many (M2M) relation in the API.
+
+    This schema is used to describe an M2M relationship between a primary resource and its related
+    objects, and to automatically provision CRUD-like endpoints for managing that relation
+    (add, remove, and get). It supports both direct Django model classes and model serializers,
+    and can optionally expose a custom schema for the related output.
+
+        model (ModelSerializerMeta | Type[Model]):
+            The target related entity, provided either as a ModelSerializer (preferred) or a Django model.
+            If a plain model is supplied, you must also provide `related_schema`.
+        related_name (str):
+            The name of the M2M field on the Django model that links to the related objects.
+        add (bool):
+            Whether to enable an endpoint for adding related objects. Defaults to True.
+        remove (bool):
+            Whether to enable an endpoint for removing related objects. Defaults to True.
+        get (bool):
+            Whether to enable an endpoint for listing/retrieving related objects. Defaults to True.
+        path (str | None):
+            Optional custom URL path segment for the relation endpoints. If empty or None, a path
+            is auto-generated based on `related_name`.
+        auth (list | None):
+            Optional list of authentication backends to protect the relation endpoints.
+        filters (dict[str, tuple] | None):
+            Optional mapping of queryable filter fields for the GET endpoint, defined as:
+            field_name -> (type, default). Example: {"country": ("str", "")}.
+        related_schema (Type[Schema] | None):
+            Optional explicit schema to represent related objects in responses.
+            If `model` is a ModelSerializerMeta, this is auto-derived via `model.generate_related_s()`.
+            If `model` is a plain Django model, this must be provided.
+        append_slash (bool):
+            Whether to append a trailing slash to the generated GET endpoint path. Defaults to False for backward compatibility.
+
+    Validation:
+        - If `model` is not a ModelSerializerMeta, `related_schema` is required.
+        - When `model` is a ModelSerializerMeta and `related_schema` is not provided, it will be
+          automatically generated.
+
+    Usage example:
+            filters={"country": ("str", "")},
+            auth=[AuthBackend],
+            add=True,
+            remove=True,
+            get=True,
     """
 
     model: ModelSerializerMeta | Type[Model]
@@ -37,6 +63,7 @@ class M2MRelationSchema(BaseModel):
     auth: Optional[list] = None
     filters: Optional[dict[str, tuple]] = None
     related_schema: Optional[Type[Schema]] = None
+    append_slash: bool = False
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
@@ -61,28 +88,81 @@ class ModelQuerySetSchema(BaseModel):
 
 
 class ModelQuerySetExtraSchema(ModelQuerySetSchema):
+    """
+    Schema defining extra query parameters for model queryset operations in API endpoints.
+    Attributes:
+        scope (str): The scope defining the level of access for the queryset operation.
+        select_related (Optional[list[str]]): List of related fields for select_related optimization.
+        prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
+    """
     scope: str
 
 
 class ObjectQuerySchema(ModelQuerySetSchema):
+    """
+    Schema defining query parameters for single object retrieval in API endpoints.
+    Attributes:
+        getters (Optional[dict]): A dictionary of getters to apply to the query.
+        select_related (Optional[list[str]]): List of related fields for select_related optimization.
+        prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
+    """
     getters: Optional[dict] = {}
 
 
 class ObjectsQuerySchema(ModelQuerySetSchema):
+    """
+    Schema defining query parameters for multiple object retrieval in API endpoints.
+    Attributes:
+        filters (Optional[dict]): A dictionary of filters to apply to the query.
+        select_related (Optional[list[str]]): List of related fields for select_related optimization.
+        prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
+    """
     filters: Optional[dict] = {}
 
 
 class QuerySchema(ModelQuerySetSchema):
+    """
+    Schema defining query parameters for API endpoints.
+    Attributes:
+        filters (Optional[dict]): A dictionary of filters to apply to the query.
+        getters (Optional[dict]): A dictionary of getters to apply to the query.
+        select_related (Optional[list[str]]): List of related fields for select_related optimization.
+        prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
+    """
     filters: Optional[dict] = {}
     getters: Optional[dict] = {}
 
 
 class QueryUtilBaseScopesSchema(BaseModel):
+    """
+    Schema defining base scopes for query utilities.
+    Attributes:
+        READ (str): Scope for read operations.
+        QUERYSET_REQUEST (str): Scope for queryset request operations.
+    """
     READ: str = "read"
     QUERYSET_REQUEST: str = "queryset_request"
 
 
 class DecoratorsSchema(Schema):
+    """
+    Schema defining optional decorator lists for CRUD operations.
+
+    Attributes:
+        list (Optional[List]): Decorators applied to the list endpoint.
+        retrieve (Optional[List]): Decorators applied to the retrieve endpoint.
+        create (Optional[List]): Decorators applied to the create endpoint.
+        update (Optional[List]): Decorators applied to the update endpoint.
+        delete (Optional[List]): Decorators applied to the delete endpoint.
+
+    Notes:
+        - Each attribute holds an ordered collection of decorators (callables or decorator references)
+          to be applied to the corresponding endpoint.
+        - Defaults are empty lists, meaning no decorators are applied unless explicitly provided.
+        - Using mutable defaults (empty lists) at the class level may lead to shared state between instances.
+          Consider initializing these in __init__ or using default_factory (if using pydantic/dataclasses)
+          to avoid unintended side effects.
+    """
     list: Optional[List] = []
     retrieve: Optional[List] = []
     create: Optional[List] = []

ninja_aio/views/api.py

@@ -5,6 +5,7 @@ from ninja.constants import NOT_SET
 from ninja.pagination import paginate, AsyncPaginationBase, PageNumberPagination
 from django.http import HttpRequest
 from django.db.models import Model, QuerySet
+from django.conf import settings
 from pydantic import create_model
 
 from ninja_aio.schemas.helpers import ModelQuerySetSchema, QuerySchema, DecoratorsSchema
@@ -27,6 +28,7 @@ class API:
     router_tags: list[str] = []
     api_route_path: str = ""
     auth: list | None = NOT_SET
+    router: Router = None
 
     def views(self):
         """
@@ -63,7 +65,10 @@ class API:
         pass
 
     def _add_views(self):
-        raise NotImplementedError("_add_views must be implemented in subclasses")
+        for name in dir(self.__class__):
+            method = getattr(self.__class__, name)
+            if hasattr(method, "_api_register"):
+                method._api_register(self)
 
     def add_views_to_route(self):
         return self.api.add_router(f"{self.api_route_path}", self._add_views())
@@ -74,12 +79,13 @@ class APIView(API):
     Base class to register custom, non-CRUD endpoints on a Ninja Router.
 
     Usage:
+        from ninja_aio.decorations import api_get
+
         @api.view(prefix="/custom", tags=["Custom"])
         class CustomAPIView(APIView):
-            def views(self):
-                @self.router.get("/hello", response=SomeSchema)
-                async def hello(request):
-                    return SomeSchema(...)
+            @api_get("/hello", response=SomeSchema)
+            async def hello(request):
+                return SomeSchema(...)
 
         or
 
@@ -119,6 +125,7 @@ class APIView(API):
         self.error_codes = ERROR_CODES
 
     def _add_views(self):
+        super()._add_views()
         self.views()
         return self.router
 
@@ -255,10 +262,15 @@ class APIViewSet(API):
         self.router_tag = self.router_tag or self.model_verbose_name
         self.router_tags = self.router_tags or tags or [self.router_tag]
         self.router = Router(tags=self.router_tags)
-        self.path = "/"
+        self.append_slash = getattr(settings, "NINJA_AIO_APPEND_SLASH", True)
+        self.path = "/" if self.append_slash else ""
         self.get_path = ""
-        self.path_retrieve = f"{{{self.model_util.model_pk_name}}}/"
         self.get_path_retrieve = f"{{{self.model_util.model_pk_name}}}"
+        self.path_retrieve = (
+            f"{self.get_path_retrieve}/"
+            if self.append_slash
+            else self.get_path_retrieve
+        )
         self.api_route_path = (
             self.api_route_path
             or prefix
@@ -501,6 +513,7 @@ class APIViewSet(API):
         Register CRUD (unless disabled), custom views, and M2M endpoints.
         If 'all' in disable only CRUD is skipped; M2M + custom still added.
         """
+        super()._add_views()
         if "all" in self.disable:
             return self._set_additional_views()
 

django_ninja_aio_crud-2.2.0.dist-info/RECORD

@@ -1,23 +0,0 @@
-ninja_aio/__init__.py,sha256=Jgj89rpJ3n4pkGfoSYm9NYrwBjGzwhiOeU5c6mr-J8Q,119
-ninja_aio/api.py,sha256=tuC7vdvn7s1GkCnSFy9Kn1zv0glZfYptRQVvo8ZRtGQ,2429
-ninja_aio/auth.py,sha256=4sWdFPjKiQgUL1d_CSGDblVjnY5ptP6LQha6XXdluJA,9157
-ninja_aio/decorators.py,sha256=BHoFIiqdIVMFqSxGh-F6WeZFo1xZK4ieDw3dzKfxZIM,8147
-ninja_aio/exceptions.py,sha256=1-iRbrloIyi0CR6Tcrn5YR4_LloA7PPohKIBaxXJ0-8,2596
-ninja_aio/models.py,sha256=aJlo5a64O4o-fB8QESLMUJpoA5kcjRJxPBiAIMxg46k,47652
-ninja_aio/parsers.py,sha256=e_4lGCPV7zs-HTqtdJTc8yQD2KPAn9njbL8nF_Mmgkc,153
-ninja_aio/renders.py,sha256=VtmSliRJyZ6gjyoib8AXMVUBYF1jPNsiceCHujI_mAs,1699
-ninja_aio/types.py,sha256=nFqWEopm7eoEaHRzbi6EyA9WZ5Cneyd602ilFKypeQI,577
-ninja_aio/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ninja_aio/helpers/api.py,sha256=BTe7OL-X7YgWYeXmka8TmN4-gA43FVZhtH7q0dRjYX0,20238
-ninja_aio/helpers/query.py,sha256=tE8RjXvSig-WB_0LRQ0LqoE4G_HMHsu0Na5QzTNIm6U,4262
-ninja_aio/schemas/__init__.py,sha256=iLBwHg0pmL9k_UkIui5Q8QIl_gO4fgxSv2JHxDzqnSI,549
-ninja_aio/schemas/api.py,sha256=-VwXhBRhmMsZLIAmWJ-P7tB5klxXS75eukjabeKKYsc,360
-ninja_aio/schemas/generics.py,sha256=frjJsKJMAdM_NdNKv-9ddZNGxYy5PNzjIRGtuycgr-w,112
-ninja_aio/schemas/helpers.py,sha256=rmE0D15lJg95Unv8PU44Hbf0VDTcErMCZZFG3D_znTo,2823
-ninja_aio/views/__init__.py,sha256=DEzjWA6y3WF0V10nNF8eEurLNEodgxKzyFd09AqVp3s,148
-ninja_aio/views/api.py,sha256=O_QQBxk-MltU-bPjxOSu5fFpHaDNP5J3Wk6E5rSBgi4,19744
-ninja_aio/views/mixins.py,sha256=Jh6BG8Cs823nurVlODlzCquTxKrLH7Pmo5udPqUGZek,11378
-django_ninja_aio_crud-2.2.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
-django_ninja_aio_crud-2.2.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-django_ninja_aio_crud-2.2.0.dist-info/METADATA,sha256=lJiJIHnNMaKXAM-aOwuKlcAmaJt8oV_wtiDGSFvjjJE,8680
-django_ninja_aio_crud-2.2.0.dist-info/RECORD,,