django-ninja-aio-crud 2.1.0__py3-none-any.whl → 2.3.0__py3-none-any.whl

{django_ninja_aio_crud-2.1.0.dist-info → django_ninja_aio_crud-2.3.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 2.1.0
+Version: 2.3.0
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
-Requires-Python: >=3.10
+Requires-Python: >=3.10, <=3.14
 Description-Content-Type: text/markdown
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Internet
@@ -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.3.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+ninja_aio/__init__.py,sha256=E3q86wZJvkl9LIkWh-fNxr_uH_7pT-x4KJC-WMIjMY0,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.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-2.3.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-2.3.0.dist-info/METADATA,sha256=6NxeKxjsDeOO3Zp7E-keTspm6tEzzSvXlcpthS0OVYI,8790
+django_ninja_aio_crud-2.3.0.dist-info/RECORD,,

ninja_aio/__init__.py

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

ninja_aio/api.py

@@ -5,10 +5,13 @@ from ninja.throttling import BaseThrottle
 from ninja import NinjaAPI
 from ninja.openapi.docs import DocsBase, Swagger
 from ninja.constants import NOT_SET, NOT_SET_TYPE
+from django.db import models
 
 from .parsers import ORJSONParser
 from .renders import ORJSONRenderer
 from .exceptions import set_api_exception_handlers
+from .views import APIView, APIViewSet
+from .models import ModelSerializer
 
 
 class NinjaAIO(NinjaAPI):
@@ -49,3 +52,24 @@ class NinjaAIO(NinjaAPI):
     def set_default_exception_handlers(self):
         set_api_exception_handlers(self)
         super().set_default_exception_handlers()
+
+    def view(self, prefix: str, tags: list[str] = None) -> Any:
+        def wrapper(view: type[APIView]):
+            instance = view(api=self, prefix=prefix, tags=tags)
+            instance.add_views_to_route()
+            return instance
+
+        return wrapper
+
+    def viewset(
+        self,
+        model: models.Model | ModelSerializer,
+        prefix: str = None,
+        tags: list[str] = None,
+    ) -> None:
+        def wrapper(viewset: type[APIViewSet]):
+            instance = viewset(api=self, model=model, prefix=prefix, tags=tags)
+            instance.add_views_to_route()
+            return instance
+
+        return wrapper

ninja_aio/auth.py

@@ -124,7 +124,7 @@ def validate_key(key: Optional[JwtKeys], setting_name: str) -> JwtKeys:
         key = getattr(settings, setting_name, None)
     if key is None:
         raise ValueError(f"{setting_name} is required")
-    if not isinstance(key, (jwk.RSAKey, jwk.ECKey)):
+    if not isinstance(key, (jwk.RSAKey, jwk.ECKey, jwk.OctKey)):
         raise ValueError(
             f"{setting_name} must be an instance of jwk.RSAKey or jwk.ECKey"
         )
@@ -143,7 +143,7 @@ def validate_mandatory_claims(claims: dict) -> dict:
 
 
 def encode_jwt(
-    claims: dict, duration: int, private_key: jwk.RSAKey = None, algorithm: str = None
+    claims: dict, duration: int, private_key: JwtKeys = None, algorithm: str = None
 ) -> str:
     """
     Encode and sign a JWT.
@@ -192,7 +192,7 @@ def encode_jwt(
 
 def decode_jwt(
     token: str,
-    public_key: jwk.RSAKey | jwk.ECKey = None,
+    public_key: JwtKeys = None,
     algorithms: list[str] = None,
 ) -> jwt.Token:
     """

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/types.py

@@ -8,7 +8,7 @@ S_TYPES = Literal["read", "create", "update"]
 F_TYPES = Literal["fields", "customs", "optionals", "excludes"]
 SCHEMA_TYPES = Literal["In", "Out", "Patch", "Related"]
 VIEW_TYPES = Literal["list", "retrieve", "create", "update", "delete", "all"]
-JwtKeys: TypeAlias = jwk.RSAKey | jwk.ECKey
+JwtKeys: TypeAlias = jwk.RSAKey | jwk.ECKey | jwk.OctKey
 
 class ModelSerializerType(type):
     def __repr__(self):

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
@@ -18,18 +19,16 @@ from ninja_aio.helpers.api import ManyToManyAPI
 from ninja_aio.types import ModelSerializerMeta, VIEW_TYPES
 from ninja_aio.decorators import unique_view, decorate_view
 
-ERROR_CODES = frozenset({400, 401, 404, 428})
+ERROR_CODES = frozenset({400, 401, 404})
 
 
-class APIView:
-    api: NinjaAPI
-    router_tag: str
-    api_route_path: str
+class API:
+    api: NinjaAPI = None
+    router_tag: str = ""
+    router_tags: list[str] = []
+    api_route_path: str = ""
     auth: list | None = NOT_SET
-
-    def __init__(self) -> None:
-        self.router = Router(tags=[self.router_tag])
-        self.error_codes = ERROR_CODES
+    router: Router = None
 
     def views(self):
         """
@@ -38,7 +37,7 @@ class APIView:
         async def some_method(request, *args, **kwargs):
             pass
 
-        You can add multilple views just doing:
+        You can add views just doing:
 
         @self.router.get(some_path, response=some_schema)
         async def some_method(request, *args, **kwargs):
@@ -63,20 +62,85 @@ class APIView:
         async def some_method(request, *args, **kwargs):
             pass
         """
+        pass
 
     def _add_views(self):
-        self.views()
-        return self.router
+        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())
 
 
-class APIViewSet:
+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):
+            @api_get("/hello", response=SomeSchema)
+            async def hello(request):
+                return SomeSchema(...)
+
+        or
+
+        class CustomAPIView(APIView):
+            api = api
+            api_route_path = "/custom"
+            router_tags = ["Custom"]
+
+            def views(self):
+                @self.router.get("/hello", response=SomeSchema)
+                async def hello(request):
+                    return SomeSchema(...)
+
+
+        CustomAPIView().add_views_to_route()
+
+    Attributes:
+        api: NinjaAPI instance used to mount the router.
+        router_tag: Single tag used if router_tags is not provided.
+        router_tags: List of tags assigned to the router.
+        api_route_path: Base path where the router is mounted.
+        auth: Default auth list or NOT_SET for unauthenticated endpoints.
+        router: Router instance where views are registered.
+        error_codes: Common error codes returned by endpoints.
+
+    Overridable methods:
+        views(): Register your endpoints using self.router.get/post/patch/delete.
+    """
+
+    def __init__(
+        self, api: NinjaAPI = None, prefix: str = None, tags: list[str] = None
+    ) -> None:
+        self.api = api or self.api
+        self.api_route_path = prefix or self.api_route_path
+        self.router_tags = tags or self.router_tags or [self.router_tag]
+        self.router = Router(tags=self.router_tags)
+        self.error_codes = ERROR_CODES
+
+    def _add_views(self):
+        super()._add_views()
+        self.views()
+        return self.router
+
+
+class APIViewSet(API):
     """
     Base viewset generating async CRUD + optional M2M endpoints for a Django model.
 
     Usage:
+        @api.viewset(model=MyModel)
+        class MyModelViewSet(APIViewSet):
+            pass
+
+        or
+
         class MyModelViewSet(APIViewSet):
             model = MyModel
             api = api
@@ -109,8 +173,8 @@ class APIViewSet:
         dict, and must return the (optionally) filtered queryset.
 
         Example:
+            @api.viewset(model=models.User)
             class UserViewSet(APIViewSet):
-                model = models.User
                 m2m_relations = [
                     M2MRelationSchema(
                         model=models.Tag,
@@ -149,7 +213,7 @@ class APIViewSet:
         <related_name>_query_params_handler(queryset, filters): Async hook for per-M2M filtering.
 
     Error responses:
-        All endpoints may return GenericMessageSchema for codes in ERROR_CODES (400,401,404,428).
+        All endpoints may return GenericMessageSchema for codes in ERROR_CODES (400,401,404).
 
     Internal:
         Dynamic path/filter schemas built with pydantic.create_model.
@@ -157,12 +221,9 @@ class APIViewSet:
     """
 
     model: ModelSerializer | Model
-    api: NinjaAPI
-    router_tag: str = ""
     schema_in: Schema | None = None
     schema_out: Schema | None = None
     schema_update: Schema | None = None
-    auth: list | None = NOT_SET
     get_auth: list | None = NOT_SET
     post_auth: list | None = NOT_SET
     patch_auth: list | None = NOT_SET
@@ -170,7 +231,6 @@ class APIViewSet:
     pagination_class: type[AsyncPaginationBase] = PageNumberPagination
     query_params: dict[str, tuple[type, ...]] = {}
     disable: list[type[VIEW_TYPES]] = []
-    api_route_path: str = ""
     list_docs = "List all objects."
     create_docs = "Create a new object."
     retrieve_docs = "Retrieve a specific object by its primary key."
@@ -180,8 +240,16 @@ class APIViewSet:
     m2m_auth: list | None = NOT_SET
     extra_decorators: DecoratorsSchema = DecoratorsSchema()
 
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        api: NinjaAPI = None,
+        model: Model | ModelSerializer = None,
+        prefix: str = None,
+        tags: list[str] = None,
+    ) -> None:
+        self.api = api or self.api
         self.error_codes = ERROR_CODES
+        self.model = model or self.model
         self.model_util = (
             ModelUtil(self.model)
             if not isinstance(self.model, ModelSerializerMeta)
@@ -191,16 +259,22 @@ class APIViewSet:
         self.path_schema = self._generate_path_schema()
         self.filters_schema = self._generate_filters_schema()
         self.model_verbose_name = self.model._meta.verbose_name.capitalize()
-        self.router_tag = (
-            self.model_verbose_name if not self.router_tag else self.router_tag
-        )
-        self.router = Router(tags=[self.router_tag])
-        self.path = "/"
+        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.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 self.model_util.verbose_name_path_resolver()
+            self.api_route_path
+            or prefix
+            or self.model_util.verbose_name_path_resolver()
         )
         self.m2m_api = (
             None
@@ -439,6 +513,7 @@ class APIViewSet:
         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()
 
@@ -450,18 +525,18 @@ class APIViewSet:
 
         return self._set_additional_views()
 
-    def add_views_to_route(self):
-        """
-        Attach router with registered endpoints to the NinjaAPI instance.
-        """
-        return self.api.add_router(f"{self.api_route_path}", self._add_views())
-
 
 class ReadOnlyViewSet(APIViewSet):
     """
     ReadOnly viewset generating async List + Retrieve endpoints for a Django model.
 
     Usage:
+        @api.viewset(model=MyModel)
+        class MyModelReadOnlyViewSet(ReadOnlyViewSet):
+            pass
+
+        or
+
         class MyModelReadOnlyViewSet(ReadOnlyViewSet):
             model = MyModel
             api = api
@@ -476,10 +551,15 @@ class WriteOnlyViewSet(APIViewSet):
     WriteOnly viewset generating async Create + Update + Delete endpoints for a Django model.
 
     Usage:
+        @api.viewset(model=MyModel)
+        class MyModelWriteOnlyViewSet(WriteOnlyViewSet):
+            pass
+
+        or
+
         class MyModelWriteOnlyViewSet(WriteOnlyViewSet):
             model = MyModel
             api = api
-        MyModelWriteOnlyViewSet().add_views_to_route()
     """
 
     disable = ["list", "retrieve"]

django_ninja_aio_crud-2.1.0.dist-info/RECORD

@@ -1,23 +0,0 @@
-ninja_aio/__init__.py,sha256=YGWehZQ4d5yVFCd1ax-s61BSkND60Yh383YmUJq-LtY,119
-ninja_aio/api.py,sha256=SS1TYUiFkdYjfJLVy6GI90GOzvIHzPEeL-UcqWFRHkM,1684
-ninja_aio/auth.py,sha256=w9TXDQwJSZzCbncsSwemINTUe1IPZGHnLKiqWTeOoFA,9163
-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=_QV0DySZhCV1otuh1zhrlHgCaFnr5fd64GQrcA-qKoc,564
-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=ispbr5w6WCUdbXmn2LY94zDQ0qb2nDNeTLLNAUBFoDc,17736
-ninja_aio/views/mixins.py,sha256=Jh6BG8Cs823nurVlODlzCquTxKrLH7Pmo5udPqUGZek,11378
-django_ninja_aio_crud-2.1.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
-django_ninja_aio_crud-2.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-django_ninja_aio_crud-2.1.0.dist-info/METADATA,sha256=91kIanSvlN_aeRmhZuXZR2pIBXEzUUOuYLJkijzN7QI,8672
-django_ninja_aio_crud-2.1.0.dist-info/RECORD,,