django-ninja-aio-crud 2.0.0rc2__py3-none-any.whl → 2.0.0rc3__py3-none-any.whl

{django_ninja_aio_crud-2.0.0rc2.dist-info → django_ninja_aio_crud-2.0.0rc3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 2.0.0rc2
+Version: 2.0.0rc3
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
 Requires-Python: >=3.10

{django_ninja_aio_crud-2.0.0rc2.dist-info → django_ninja_aio_crud-2.0.0rc3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-ninja_aio/__init__.py,sha256=pbirtGjZYV3n781FGk4--FCsMr1fh04uGsANoHTYmmA,123
+ninja_aio/__init__.py,sha256=JcpcShlXZ4BnQ_O8zXApC5ZgzwxHrruInN3QK3tZgps,123
 ninja_aio/api.py,sha256=SS1TYUiFkdYjfJLVy6GI90GOzvIHzPEeL-UcqWFRHkM,1684
 ninja_aio/auth.py,sha256=8jaEp7oEJvUUB9EuyE2fOYk-khyAaekT3i80E7AbgOA,5101
 ninja_aio/decorators.py,sha256=gswkwl1zWSpW8VxGCe8MlgXcHMg6Y7V1f2ertey9Tjo,5522
@@ -9,13 +9,13 @@ ninja_aio/renders.py,sha256=5TdSQI8e4x3Gb2tAw1AaxrbU-asVjf2chWMr8x2Tt80,1485
 ninja_aio/types.py,sha256=TJSGlA7bt4g9fvPhJ7gzH5tKbLagPmZUzfgttEOp4xs,468
 ninja_aio/views.py,sha256=u6WVXvErF3DAOTONTH_EhSg-5qhFBhtR4L2lNrt00qo,16331
 ninja_aio/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ninja_aio/helpers/api.py,sha256=lkh8eA9OnFlFPpxhnVP_wMHWPKfueVB4AnsXxgzp-HI,17426
+ninja_aio/helpers/api.py,sha256=F6SlvNCEEAm-fzqpTB5r0O9gqhbP0dvyieNcG1JlKCw,20181
 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=al1G5-CdB9CF3eIPdZcUSE7vKRJiTU5g1ltoPhI2Onw,2622
-django_ninja_aio_crud-2.0.0rc2.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
-django_ninja_aio_crud-2.0.0rc2.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-django_ninja_aio_crud-2.0.0rc2.dist-info/METADATA,sha256=ZFWsNX5c4EFI2HITJpKttPOohErdMwTxhZ4qM2eHu2s,8675
-django_ninja_aio_crud-2.0.0rc2.dist-info/RECORD,,
+django_ninja_aio_crud-2.0.0rc3.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-2.0.0rc3.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-2.0.0rc3.dist-info/METADATA,sha256=_srbK-mfXF3zuPPmP1YK2zssec21f2W4CnowtGgHgR4,8675
+django_ninja_aio_crud-2.0.0rc3.dist-info/RECORD,,

ninja_aio/__init__.py

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

ninja_aio/helpers/api.py

@@ -38,27 +38,34 @@ class ManyToManyAPI:
     Core behaviors:
         - Dynamically generates per-relation filter schemas for query parameters.
         - Supports custom per-relation query filtering handlers on the parent view set
-            via a `{related_name}_query_params_handler` coroutine.
+          via a `{related_name}_query_params_handler` coroutine for GET list filters.
+        - Supports custom per-relation object resolution for add/remove validation via
+          `{related_name}_query_handler(request, pk, instance)` used during POST to
+          resolve a single related object before mutation.
         - Validates requested add/remove primary keys, producing granular success and
-            error feedback.
+          error feedback.
         - Performs add/remove operations concurrently using asyncio.gather when both
-            types of operations are requested in the same call.
+          types of operations are requested in the same call.
 
     Attributes established at initialization:
         relations: list of M2MRelationSchema defining each relation.
         view_set: The parent APIViewSet instance from which router, pagination, model util,
-                            and path schema are derived.
+                  and path schema are derived.
         router: Ninja router used to register generated endpoints.
         pagination_class: Pagination class used for GET related endpoints.
         path_schema: Pydantic schema used to validate path parameters (e.g., primary key).
         related_model_util: A ModelUtil instance cloned from the parent view set to access
-                                                base object retrieval helpers.
+                            base object retrieval helpers.
         relations_filters_schemas: Mapping of related_name -> generated Pydantic filter schema.
 
     Generated endpoint naming conventions:
         GET   -> get_{base_model_name}_{relation_path}
         POST  -> manage_{base_model_name}_{relation_path}
 
+    Endpoint registration details:
+        - GET: registered at `{retrieve_path}{relation_path}` with pagination; accepts Query filters.
+        - POST: registered at `{retrieve_path}{relation_path}/` (trailing slash) to manage add/remove.
+
     All responses standardize success and error reporting for POST as:
     {
         "results": {"count": int, "details": [str, ...]},
@@ -66,25 +73,29 @@ class ManyToManyAPI:
     }
 
     Concurrency note:
-        Add and remove operations are executed concurrently when both lists are non-empty,
-        minimizing round-trip latency for bulk mutations.
+        - Add and remove operations are executed concurrently when both lists are non-empty,
+          minimizing round-trip latency for bulk mutations.
+        - Uses related_manager.aadd(...) and related_manager.aremove(...) inside asyncio.gather.
 
     Error semantics:
         - Missing related objects: reported individually.
         - Invalid operation context (e.g., removing objects not currently related or adding
-            objects already related) reported per primary key.
+          objects already related) reported per primary key.
         - Successful operations yield a corresponding success detail string per PK.
 
     Security / auth:
         - Each relation may optionally override auth via its schema; otherwise falls back
-            to a default configured on the instance (self.default_auth).
+          to a default configured on the instance (self.default_auth).
 
     Pagination:
         - Applied only to GET related endpoints via @paginate(self.pagination_class).
 
     Extensibility:
         - Provide custom query param handling by defining an async method on the parent
-            view set: `<related_name>_query_params_handler(self, queryset, filters_dict)`.
+          view set: `<related_name>_query_params_handler(self, queryset, filters_dict)`.
+        - Provide custom per-PK resolution for POST validation by defining an async method:
+          `<related_name>_query_handler(self, request, pk, instance)` returning a queryset,
+          from which .afirst() is used to resolve the single target object.
         - Customize relation filtering schema via each relation's `filters` definition.
 
     -----------------------------------------------------------------------
@@ -114,9 +125,9 @@ class ManyToManyAPI:
 
     -----------------------------------------------------------------------
 
-    _get_query_handler(related_name)
-    Retrieve an optional per-relation query handler coroutine from the parent view set.
-    Naming convention: `<related_name>_query_params_handler`.
+    _get_query_params_handler(related_name)
+    Retrieve an optional per-relation query handler from the parent view set for GET list filters.
+    Naming convention: `<related_name}_query_params_handler`.
 
     Parameters:
         related_name (str): The relation's attribute name on the base model.
@@ -126,16 +137,32 @@ class ManyToManyAPI:
 
     -----------------------------------------------------------------------
 
-    _check_m2m_objs(request, objs_pks, model, related_manager, remove=False)
+    _get_query_handler(related_name)
+    Retrieve an optional per-relation single-object resolution handler from the parent view set
+    used during POST add/remove validation. If present, it receives `(request, pk, instance)` and
+    should return a queryset from which `.afirst()` will resolve the target object.
+
+    Parameters:
+        related_name (str): The relation's attribute name on the base model.
+
+    Returns:
+        Coroutine | None: Handler to resolve a single related object by pk.
+
+    -----------------------------------------------------------------------
+
+    _check_m2m_objs(request, objs_pks, related_model, related_manager, related_name, instance, remove=False)
     Validate requested primary keys for add/remove operations against the current
     relation state. Performs existence checks and logical consistency (e.g., prevents
-    adding already-related objects or removing non-related objects).
+    adding already-related objects or removing non-related objects). Uses `_get_query_handler`
+    when available; otherwise falls back to ModelUtil(...).get_objects(...) to resolve by pk.
 
     Parameters:
         request (HttpRequest): Incoming request context (passed to ModelUtil for access control).
         objs_pks (list): List of primary keys to add or remove.
-        model (ModelSerializer | Model): Model class or serializer used to resolve objects.
+        related_model (ModelSerializer | Model): Model class or serializer used to resolve objects.
         related_manager (QuerySet): Related manager for the base object's M2M field.
+        related_name (str): M2M field name on the base object.
+        instance (ModelSerializer | Model): Base object instance (owner of the relation).
         remove (bool): If True, treat operation as removal validation.
 
     Returns:
@@ -150,7 +177,7 @@ class ManyToManyAPI:
 
     -----------------------------------------------------------------------
 
-    _collect_m2m(request, pks, model, related_manager, remove=False)
+    _collect_m2m(request, pks, model, related_manager, related_name, instance, remove=False)
     Wrapper around _check_m2m_objs that short-circuits on empty PK lists.
 
     Parameters:
@@ -158,6 +185,8 @@ class ManyToManyAPI:
         pks (list): Primary keys proposed for mutation.
         model (ModelSerializer | Model)
         related_manager (QuerySet)
+        related_name (str)
+        instance (ModelSerializer | Model)
         remove (bool): Operation type flag.
 
     Returns:
@@ -165,38 +194,30 @@ class ManyToManyAPI:
 
     -----------------------------------------------------------------------
 
+    _register_get_relation_view(...)
+    Registers the GET endpoint for listing related objects. Applies optional
+    query params handler for filtering. Uses pagination and serializes via `list_read_s`.
+
+    -----------------------------------------------------------------------
+
+    _register_manage_relation_view(...)
+    Registers the POST endpoint for adding/removing related objects. Validates via
+    `_collect_m2m` and executes mutations concurrently using `aadd`/`aremove` with
+    `asyncio.gather`. Aggregates per-PK results and errors into a standardized payload.
+
+    -----------------------------------------------------------------------
+
     _build_views(relation)
     Dynamically define and register the GET and/or POST endpoints for a single M2M
     relation based on the relation's schema flags (get/add/remove). Builds filter
     schemas, resolves path fragments, and binds handlers to the router with unique
     operation IDs.
 
-    Parameters:
-        relation (M2MRelationSchema): Declarative specification for one M2M relation.
-
-    Side effects:
-        - Registers endpoints on self.router.
-        - Creates closures (get_related / manage_related) capturing relation context.
-
-    GET endpoint behavior:
-        - Retrieves base object via related_model_util.
-        - Fetches all related objects; applies optional query handler and filters.
-        - Serializes each related object with rel_util.read_s.
-
-    POST endpoint behavior:
-        - Parses add/remove PK lists.
-        - Validates objects via _collect_m2m.
-        - Performs asynchronous add/remove operations using aadd / aremove.
-        - Aggregates results and errors into standardized response payload.
-
     -----------------------------------------------------------------------
 
     _add_views()
     Iterates over all declared relations and invokes _build_views to attach endpoints.
 
-    Side effects:
-        - Populates router with all required M2M endpoints.
-
     -----------------------------------------------------------------------
 
     Usage Example (conceptual):
@@ -241,30 +262,45 @@ class ManyToManyAPI:
             for data in self.relations
         }
 
-    def _get_query_handler(self, related_name: str) -> Coroutine | None:
+    def _get_query_params_handler(self, related_name: str) -> Coroutine | None:
         return getattr(self.view_set, f"{related_name}_query_params_handler", None)
 
+    def _get_query_handler(self, related_name: str) -> Coroutine | None:
+        return getattr(self.view_set, f"{related_name}_query_handler", None)
+
     async def _check_m2m_objs(
         self,
         request: HttpRequest,
         objs_pks: list,
-        model: ModelSerializer | Model,
+        related_model: ModelSerializer | Model,
         related_manager: QuerySet,
+        related_name: str,
+        instance: ModelSerializer | Model,
         remove: bool = False,
     ):
         """
         Validate requested add/remove pk list for M2M operations.
         Returns (errors, details, objects_to_process).
+        Uses per-PK query handler if available, else falls back to ModelUtil lookup by pk.
         """
         errors, objs_detail, objs = [], [], []
         rel_objs = [rel_obj async for rel_obj in related_manager.select_related().all()]
-        rel_model_name = model._meta.verbose_name.capitalize()
+        rel_model_name = related_model._meta.verbose_name.capitalize()
         for obj_pk in objs_pks:
-            rel_obj = await (
-                await ModelUtil(model).get_objects(
-                    request, query_data=ObjectsQuerySchema(filters={"pk": obj_pk})
-                )
-            ).afirst()
+            if query_handler := self._get_query_handler(related_name):
+                rel_obj = await (
+                    await query_handler(
+                        request,
+                        obj_pk,
+                        instance,
+                    )
+                ).afirst()
+            else:
+                rel_obj = await (
+                    await ModelUtil(related_model).get_objects(
+                        request, query_data=ObjectsQuerySchema(filters={"pk": obj_pk})
+                    )
+                ).afirst()
             if rel_obj is None:
                 errors.append(f"{rel_model_name} with pk {obj_pk} not found.")
                 continue
@@ -283,14 +319,22 @@ class ManyToManyAPI:
         self,
         request: HttpRequest,
         pks: list,
-        model: ModelSerializer | Model,
+        reletad_model: ModelSerializer | Model,
         related_manager: QuerySet,
-        remove=False,
+        related_name: str,
+        instance: ModelSerializer | Model,
+        remove: bool = False,
     ):
         if not pks:
             return ([], [], [])
         return await self._check_m2m_objs(
-            request, pks, model, related_manager, remove=remove
+            request,
+            pks,
+            reletad_model,
+            related_manager,
+            related_name,
+            instance,
+            remove=remove,
         )
 
     def _register_get_relation_view(
@@ -326,16 +370,14 @@ class ManyToManyAPI:
             related_manager = getattr(obj, related_name)
             related_qs = related_manager.all()
 
-            query_handler = self._get_query_handler(related_name)
+            query_handler = self._get_query_params_handler(related_name)
             if filters is not None and query_handler:
                 if asyncio.iscoroutinefunction(query_handler):
                     related_qs = await query_handler(related_qs, filters.model_dump())
                 else:
                     related_qs = query_handler(related_qs, filters.model_dump())
 
-            return await rel_util.list_read_s(
-                related_schema, request, related_qs
-            )
+            return await rel_util.list_read_s(related_schema, request, related_qs)
 
     def _resolve_action_schema(self, add: bool, remove: bool):
         return self.views_action_map[(add, remove)]
@@ -343,7 +385,7 @@ class ManyToManyAPI:
     def _register_manage_relation_view(
         self,
         *,
-        model,
+        related_model: ModelSerializer | Model,
         related_name: str,
         m2m_auth,
         rel_util: ModelUtil,
@@ -380,10 +422,21 @@ class ManyToManyAPI:
             remove_pks = getattr(data, "remove", []) if m2m_remove else []
 
             add_errors, add_details, add_objs = await self._collect_m2m(
-                request, add_pks, model, related_manager
+                request,
+                add_pks,
+                related_model,
+                related_manager,
+                related_name,
+                obj,
             )
             remove_errors, remove_details, remove_objs = await self._collect_m2m(
-                request, remove_pks, model, related_manager, remove=True
+                request,
+                remove_pks,
+                related_model,
+                related_manager,
+                related_name,
+                obj,
+                remove=True,
             )
 
             tasks = []
@@ -423,7 +476,7 @@ class ManyToManyAPI:
 
         if m2m_add or m2m_remove:
             self._register_manage_relation_view(
-                model=model,
+                related_model=model,
                 related_name=related_name,
                 m2m_auth=m2m_auth,
                 rel_util=rel_util,