django-ninja-aio-crud 0.10.2__py3-none-any.whl → 2.4.0__py3-none-any.whl

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

@@ -0,0 +1,219 @@
+from functools import wraps
+
+from django.db.transaction import Atomic
+from asgiref.sync import sync_to_async
+
+
+class AsyncAtomicContextManager(Atomic):
+    def __init__(self, using=None, savepoint=True, durable=False):
+        super().__init__(using, savepoint, durable)
+
+    async def __aenter__(self):
+        await sync_to_async(super().__enter__)()
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+        await sync_to_async(super().__exit__)(exc_type, exc_value, traceback)
+
+
+def aatomic(func):
+    """
+    Decorator that executes the wrapped async function inside an asynchronous atomic
+    database transaction context.
+
+    This is useful when you want all ORM write operations performed by the coroutine
+    to either fully succeed or fully roll back on error, preserving data integrity.
+
+    Parameters:
+        func (Callable): The asynchronous function to wrap.
+
+    Returns:
+        Callable: A new async function that, when awaited, runs inside an
+        AsyncAtomicContextManager transaction.
+
+    Behavior:
+        - Opens an async atomic transaction before invoking the wrapped coroutine.
+        - Commits if the coroutine completes successfully.
+        - Rolls back if an exception is raised and propagates the original exception.
+
+    Example:
+        @aatomic
+        async def create_order(user_id: int, items: list[Item]):
+            # Perform multiple related DB writes atomically
+            ...
+
+    Notes:
+        - Ensure AsyncAtomicContextManager is properly implemented to integrate with
+          your async ORM / database backend.
+        - Only use on async functions.
+    """
+
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        async with AsyncAtomicContextManager():
+            return await func(*args, **kwargs)
+
+    return wrapper
+
+
+def unique_view(self: object | str, plural: bool = False):
+    """
+    Return a decorator that appends a model-specific suffix to a function's __name__ for uniqueness.
+
+    This is helpful when multiple view functions share a common base name but must be
+    distinct (e.g., for route registration, debugging, or introspection) per model context.
+
+    self : object | str
+        - If a string, it is used directly as the suffix.
+        - If an object, its `model_util` attribute is inspected for:
+            * model_util.model_name (when plural is False)
+            * model_util.verbose_name_view_resolver() (when plural is True)
+          Missing attributes or call failures result in no suffix being applied.
+    plural : bool, default False
+        If True and `self` is an object with `model_util.verbose_name_view_resolver`,
+        the resolved pluralized verbose name is used; otherwise the singular model name
+        (model_util.model_name) is used.
+
+    Callable[[Callable], Callable]
+        A decorator. When applied, it mutates the target function's __name__ in place to:
+        "<original_name>_<suffix>" if a suffix is resolved. If no suffix is found, the
+        function is returned unchanged.
+
+    - Does NOT wrap or alter the call signature or async/sync nature of the function.
+    - Performs a simple in-place mutation of func.__name__ before returning the original function.
+    - No metadata (e.g., __doc__, __qualname__) is altered besides __name__.
+
+    Suffix Resolution Logic
+    -----------------------
+    1. If `self` is a str: suffix = self
+    2. Else if `self` has `model_util`:
+       - plural == True: suffix = model_util.verbose_name_view_resolver()
+       - plural == False: suffix = model_util.model_name
+    3. If resolution fails or yields a falsy value, no mutation occurs.
+
+    Side Effects
+    ------------
+    - Modifies function.__name__, which can affect:
+      - Debugging output
+      - Route registration relying on function names
+      - Tools expecting the original name
+    - Because mutation is in place, reusing the original function object elsewhere
+      may produce unexpected naming.
+
+    Examples
+    # Using a string suffix directly
+    @unique_view("book")
+    def list_items():
+
+    # Using an object with model_util.model_name
+    @unique_view(viewset_instance)  # where viewset_instance.model_util.model_name == "author"
+    def retrieve():
+    # Resulting function name: "retrieve_author"
+
+    # Using plural form via verbose_name_view_resolver()
+    @unique_view(viewset_instance, plural=True)  # e.g., returns "authors"
+    def list():
+    # Resulting function name: "list_authors"
+
+    Caveats
+    - If the underlying attributes or resolver callable raise exceptions, they are not caught.
+    - Ensure that the modified name does not conflict with other functions after decoration.
+    - Use cautiously when decorators relying on original __name__ appear earlier in the chain.
+    """
+
+    def decorator(func):
+        # Allow usage as unique_view(self_instance) or unique_view("model_name")
+        if isinstance(self, str):
+            suffix = self
+        else:
+            suffix = (
+                getattr(
+                    getattr(self, "model_util", None),
+                    "verbose_name_view_resolver",
+                    None,
+                )()
+                if plural
+                else getattr(
+                    getattr(self, "model_util", None),
+                    "model_name",
+                    None,
+                )
+            )
+        if suffix:
+            func.__name__ = f"{func.__name__}_{suffix}"
+        return func  # Return original function (no wrapper)
+
+    return decorator
+
+
+def decorate_view(*decorators):
+    """
+    Compose and apply multiple decorators to a view (sync or async) without adding an extra wrapper.
+
+    This utility was introduced to support class-based patterns where Django Ninja’s
+    built-in `decorate_view` does not fit well. For APIs implemented with vanilla
+    Django Ninja (function-based style), you should continue using Django Ninja’s
+    native `decorate_view`.
+
+    Behavior:
+    - Applies decorators in the same order as Python’s stacking syntax:
+        @d1
+        @d2
+      is equivalent to: view = d1(d2(view))
+    - Supports both synchronous and asynchronous views.
+    - Ignores None values, enabling conditional decoration.
+    - Does not introduce an additional wrapper; composition depends on each
+      decorator for signature/metadata preservation (e.g., using functools.wraps).
+
+        *decorators: Decorator callables to apply to the target view. Any None values
+            are skipped.
+
+        Callable: A decorator that applies the provided decorators in Python stacking order.
+
+        Method usage in class-based patterns:
+
+    Args:
+        *decorators: Decorator callables to apply to the target view. Any None
+            values are skipped.
+
+    Returns:
+        A decorator that applies the provided decorators in Python stacking order.
+
+    Examples:
+        Basic usage:
+            class MyAPIViewSet(APIViewSet):
+                api = api
+                model = MyModel
+
+                def views(self):
+                    @self.router.get('some-endpoint/')
+                    @decorate_view(authenticate, log_request)
+                    async def some_view(request):
+                        ...
+
+        Conditional decoration (skips None):
+            class MyAPIViewSet(APIViewSet):
+                api = api
+                model = MyModel
+                cache_dec = cache_page(60) if settings.ENABLE_CACHE else None
+                def views(self):
+                    @self.router.get('data/')
+                    @decorate_view(self.cache_dec, authenticate)
+                    async def data_view(request):
+                        ...
+
+    Notes:
+        - Each decorator is applied in the order provided, with the first decorator
+          wrapping the result of the second, and so on.
+        - Ensure that each decorator is compatible with the view’s sync/async nature.
+    """
+
+    def _decorator(view):
+        wrapped = view
+        for dec in reversed(decorators):
+            if dec is None:
+                continue
+            wrapped = dec(wrapped)
+        return wrapped
+
+    return _decorator

ninja_aio/exceptions.py

@@ -1,12 +1,14 @@
 from functools import partial
-
 from joserfc.errors import JoseError
 from ninja import NinjaAPI
 from django.http import HttpRequest, HttpResponse
 from pydantic import ValidationError
+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
 
@@ -16,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):
@@ -24,31 +31,56 @@ 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,
+            details=details,
+        )
+
+
 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)
 
@@ -56,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(
@@ -69,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