django-ninja-aio-crud 1.0.5__tar.gz → 2.0.0rc1__tar.gz

{django_ninja_aio_crud-1.0.5 → django_ninja_aio_crud-2.0.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 1.0.5
+Version: 2.0.0rc1
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
 Requires-Python: >=3.10
@@ -23,7 +23,7 @@ Classifier: Framework :: AsyncIO
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Topic :: Internet :: WWW/HTTP
 License-File: LICENSE
-Requires-Dist: django-ninja >=1.3.0, <=1.4.5
+Requires-Dist: django-ninja >=1.3.0, <=1.5.0
 Requires-Dist: joserfc >=1.0.0, <= 1.4.1
 Requires-Dist: orjson >= 3.10.7, <= 3.11.4
 Requires-Dist: coverage ; extra == "test"

{django_ninja_aio_crud-1.0.5 → django_ninja_aio_crud-2.0.0rc1}/ninja_aio/__init__.py

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

{django_ninja_aio_crud-1.0.5 → django_ninja_aio_crud-2.0.0rc1}/ninja_aio/api.py

@@ -23,7 +23,6 @@ class NinjaAIO(NinjaAPI):
         docs_decorator=None,
         servers: list[dict[str, Any]] | None = None,
         urls_namespace: str | None = None,
-        csrf: bool = False,
         auth: Sequence[Any] | NOT_SET_TYPE = NOT_SET,
         throttle: BaseThrottle | list[BaseThrottle] | NOT_SET_TYPE = NOT_SET,
         default_router: Router | None = None,
@@ -39,7 +38,6 @@ class NinjaAIO(NinjaAPI):
             docs_decorator=docs_decorator,
             servers=servers,
             urls_namespace=urls_namespace,
-            csrf=csrf,
             auth=auth,
             throttle=throttle,
             default_router=default_router,

{django_ninja_aio_crud-1.0.5 → django_ninja_aio_crud-2.0.0rc1}/ninja_aio/auth.py

@@ -2,8 +2,6 @@ from joserfc import jwt, jwk, errors
 from django.http.request import HttpRequest
 from ninja.security.http import HttpBearer
 
-from .exceptions import AuthError
-
 
 class AsyncJwtBearer(HttpBearer):
     """
@@ -71,6 +69,7 @@ class AsyncJwtBearer(HttpBearer):
     Return Semantics:
         - authenticate -> user object (success) | False (failure)
     """
+
     jwt_public: jwk.RSAKey
     claims: dict[str, dict]
     algorithms: list[str] = ["RS256"]
@@ -96,13 +95,13 @@ class AsyncJwtBearer(HttpBearer):
         """
         try:
             self.dcd = jwt.decode(token, self.jwt_public, algorithms=self.algorithms)
-        except ValueError as exc:
+        except ValueError:
             # raise AuthError(", ".join(exc.args), 401)
             return False
 
         try:
             self.validate_claims(self.dcd.claims)
-        except errors.JoseError as exc:
+        except errors.JoseError:
             return False
 
         return await self.auth_handler(request)

{django_ninja_aio_crud-1.0.5 → django_ninja_aio_crud-2.0.0rc1}/ninja_aio/decorators.py

@@ -46,10 +46,12 @@ def aatomic(func):
           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
 
 
@@ -117,6 +119,7 @@ def unique_view(self: object | str, plural: bool = False):
     - 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):

{django_ninja_aio_crud-1.0.5 → django_ninja_aio_crud-2.0.0rc1}/ninja_aio/helpers/api.py

@@ -6,6 +6,7 @@ from ninja import Path, Query
 from ninja.pagination import paginate
 from ninja_aio.decorators import unique_view
 from ninja_aio.models import ModelSerializer, ModelUtil
+from ninja_aio.schemas.helpers import ObjectsQuerySchema
 from ninja_aio.schemas import (
     GenericMessageSchema,
     M2MRelationSchema,
@@ -260,7 +261,9 @@ class ManyToManyAPI:
         rel_model_name = model._meta.verbose_name.capitalize()
         for obj_pk in objs_pks:
             rel_obj = await (
-                await ModelUtil(model).get_object(request, filters={"pk": obj_pk})
+                await ModelUtil(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.")
@@ -325,12 +328,14 @@ class ManyToManyAPI:
 
             query_handler = self._get_query_handler(related_name)
             if filters is not None and query_handler:
-                related_qs = await query_handler(related_qs, filters.model_dump())
+                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.read_s(request, rel_obj, related_schema)
-                async for rel_obj in 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)]

django_ninja_aio_crud-2.0.0rc1/ninja_aio/helpers/query.py

@@ -0,0 +1,103 @@
+from ninja_aio.types import ModelSerializerMeta
+from ninja_aio.schemas.helpers import (
+    ModelQuerySetSchema,
+    QueryUtilBaseScopesSchema,
+    ModelQuerySetExtraSchema,
+)
+
+
+class ScopeNamespace:
+    def __init__(self, **scopes):
+        for key, value in scopes.items():
+            setattr(self, key, value)
+
+    def __iter__(self):
+        return iter(self.__dict__.values())
+
+
+class QueryUtil:
+    """
+    Helper class to manage queryset optimizations based on predefined scopes.
+    Attributes:
+        model (ModelSerializerMeta): The model serializer meta to which this utility is attached.
+        SCOPES (ScopeNamespace): An enumeration-like object containing available scopes.
+        read_config (ModelQuerySetSchema): Configuration for the 'read' scope.
+        queryset_request_config (ModelQuerySetSchema): Configuration for the 'queryset_request' scope
+        extra_configs (dict): Additional configurations for custom scopes.
+    Methods:
+        apply_queryset_optimizations(queryset, scope): Applies select_related and prefetch_related
+            optimizations to the given queryset based on the specified scope.
+
+    Example:
+        query_util = QueryUtil(MyModelSerializer) or MyModel.query_util
+        qs = MyModel.objects.all()
+        optimized_qs = query_util.apply_queryset_optimizations(qs, query_util.SCOPES.READ)
+
+        # Applying optimizations for a custom scope
+        class MyModelSerializer(ModelSerializer):
+            class QuerySet:
+                extras = [
+                    ModelQuerySetExtraSchema(
+                        scope="custom_scope",
+                        select_related=["custom_fk_field"],
+                        prefetch_related=["custom_m2m_field"],
+                    )
+                ]
+        query_util = MyModelSerializer.query_util
+        qs = MyModelSerializer.objects.all()
+        optimized_qs_custom = query_util.apply_queryset_optimizations(qs, "custom_scope")
+    """
+
+    SCOPES: QueryUtilBaseScopesSchema
+
+    def __init__(self, model: ModelSerializerMeta):
+        self.model = model
+        self._configuration = getattr(self.model, "QuerySet", None)
+        self._extra_configuration: list[ModelQuerySetExtraSchema] = getattr(
+            self._configuration, "extras", []
+        )
+        self._BASE_SCOPES = QueryUtilBaseScopesSchema().model_dump()
+        self.SCOPES = ScopeNamespace(
+            **self._BASE_SCOPES,
+            **{extra.scope: extra.scope for extra in self._extra_configuration},
+        )
+        self.extra_configs = {extra.scope: extra for extra in self._extra_configuration}
+        self._configs = {
+            **{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.queryset_request_config: ModelQuerySetSchema = self._configs.get(
+            self.SCOPES.QUERYSET_REQUEST, ModelQuerySetSchema()
+        )
+
+    def _get_config(self, conf_name: str) -> ModelQuerySetSchema:
+        """Helper method to retrieve configuration attributes."""
+        return getattr(self._configuration, conf_name, ModelQuerySetSchema())
+
+    def apply_queryset_optimizations(self, queryset, scope: str):
+        """
+        Apply select_related and prefetch_related optimizations to the queryset
+        according to the specified scope.
+
+        Args:
+            queryset (QuerySet): The Django queryset to optimize.
+            scope (str): The scope to apply. Must be in self.SCOPES.
+
+        Returns:
+            QuerySet: The optimized queryset.
+
+        Raises:
+            ValueError: If the given scope is not supported.
+        """
+        if scope not in self._configs:
+            valid_scopes = list(self._configs.keys())
+            raise ValueError(
+                f"Invalid scope '{scope}' for QueryUtil. Supported scopes: {valid_scopes}"
+            )
+        config = self._configs.get(scope, ModelQuerySetSchema())
+        if config.select_related:
+            queryset = queryset.select_related(*config.select_related)
+        if config.prefetch_related:
+            queryset = queryset.prefetch_related(*config.prefetch_related)
+        return queryset

{django_ninja_aio_crud-1.0.5 → django_ninja_aio_crud-2.0.0rc1}/ninja_aio/models.py

@@ -1,9 +1,10 @@
 import asyncio
 import base64
-from typing import Any
+from typing import Any, ClassVar
 
 from ninja import Schema
-from ninja.orm import create_schema
+from ninja.orm import create_schema, fields
+from ninja.errors import ConfigError
 
 from django.db import models
 from django.http import HttpRequest
@@ -17,8 +18,16 @@ from django.db.models.fields.related_descriptors import (
     ForwardOneToOneDescriptor,
 )
 
-from .exceptions import SerializeError, NotFoundError
-from .types import S_TYPES, F_TYPES, SCHEMA_TYPES, ModelSerializerMeta
+from ninja_aio.exceptions import SerializeError, NotFoundError
+from ninja_aio.types import S_TYPES, F_TYPES, SCHEMA_TYPES, ModelSerializerMeta
+from ninja_aio.schemas.helpers import (
+    ModelQuerySetSchema,
+    ModelQuerySetExtraSchema,
+    QuerySchema,
+    ObjectQuerySchema,
+    ObjectsQuerySchema,
+)
+from ninja_aio.helpers.query import QueryUtil
 
 
 async def agetattr(obj, name: str, default=None):
@@ -97,6 +106,37 @@ class ModelUtil:
         """
         self.model = model
 
+    @property
+    def pk_field_type(self):
+        """
+        Python type corresponding to the model's primary key field.
+
+        Resolution
+        ----------
+        Uses the Django field's internal type and ninja.orm.fields.TYPES mapping.
+        If the internal type is unknown, instructs how to register a custom mapping.
+
+        Returns
+        -------
+        type
+            Native Python type for the PK suitable for schema generation.
+
+        Raises
+        ------
+        ConfigError
+            If the internal type is not registered in ninja.orm.fields.TYPES.
+        """
+        try:
+            internal_type = self.model._meta.pk.get_internal_type()
+            return fields.TYPES[internal_type]
+        except KeyError as e:
+            msg = [
+                f"Do not know how to convert django field '{internal_type}'.",
+                "Try: from ninja.orm import register_field",
+                "register_field('{internal_type}', <your-python-type>)",
+            ]
+            raise ConfigError("\n".join(msg)) from e
+
     @property
     def serializable_fields(self):
         """
@@ -175,61 +215,156 @@ class ModelUtil:
         """
         return self.model_verbose_name_plural.replace(" ", "")
 
+    async def _get_base_queryset(
+        self,
+        request: HttpRequest,
+        query_data: QuerySchema,
+        with_qs_request: bool,
+        is_for_read: bool,
+    ) -> models.QuerySet[type["ModelSerializer"] | models.Model]:
+        """
+        Build base queryset with optimizations and filters.
+
+        Parameters
+        ----------
+        request : HttpRequest
+            The HTTP request object.
+        query_data : QuerySchema
+            Query configuration with filters and optimizations.
+        with_qs_request : bool
+            Whether to apply queryset_request hook.
+        is_for_read : bool
+            Whether this is a read operation.
+
+        Returns
+        -------
+        models.QuerySet
+            Optimized and filtered queryset.
+        """
+        # Start with base queryset
+        obj_qs = self.model.objects.all()
+
+        # Apply query optimizations
+        obj_qs = self._apply_query_optimizations(obj_qs, query_data, is_for_read)
+
+        # Apply queryset_request hook if available
+        if isinstance(self.model, ModelSerializerMeta) and with_qs_request:
+            obj_qs = await self.model.queryset_request(request)
+
+        # Apply filters if present
+        if hasattr(query_data, "filters") and query_data.filters:
+            obj_qs = obj_qs.filter(**query_data.filters)
+
+        return obj_qs
+
+    async def get_objects(
+        self,
+        request: HttpRequest,
+        query_data: ObjectsQuerySchema = None,
+        with_qs_request=True,
+        is_for_read: bool = False,
+    ) -> models.QuerySet[type["ModelSerializer"] | models.Model]:
+        """
+        Retrieve a queryset with optimized database queries.
+
+        This method fetches a queryset applying query optimizations including
+        select_related and prefetch_related based on the model's relationships
+        and the query parameters.
+
+        Parameters
+        ----------
+        request : HttpRequest
+            The HTTP request object, used for queryset_request hooks.
+        query_data : ObjectsQuerySchema, optional
+            Schema containing filters and query optimization parameters.
+            Defaults to an empty ObjectsQuerySchema instance.
+        with_qs_request : bool, optional
+            Whether to apply the model's queryset_request hook if available.
+            Defaults to True.
+        is_for_read : bool, optional
+            Flag indicating if the query is for read operations, which may affect
+            query optimization strategies. Defaults to False.
+
+        Returns
+        -------
+        models.QuerySet[type["ModelSerializer"] | models.Model]
+            A QuerySet of model instances.
+
+        Notes
+        -----
+        - Query optimizations are automatically applied based on discovered relationships
+        - The queryset_request hook is called if the model implements ModelSerializerMeta
+        """
+        if query_data is None:
+            query_data = ObjectsQuerySchema()
+
+        return await self._get_base_queryset(
+            request, query_data, with_qs_request, is_for_read
+        )
+
     async def get_object(
         self,
         request: HttpRequest,
         pk: int | str = None,
-        filters: dict = None,
-        getters: dict = None,
+        query_data: ObjectQuerySchema = None,
         with_qs_request=True,
-    ) -> (
-        type["ModelSerializer"]
-        | models.Model
-        | models.QuerySet[type["ModelSerializer"] | models.Model]
-    ):
+        is_for_read: bool = False,
+    ) -> type["ModelSerializer"] | models.Model:
         """
-        Retrieve a single instance (by pk/getters) or a queryset if no lookup criteria.
+        Retrieve a single object with optimized database queries.
 
-        Applies queryset_request (if ModelSerializerMeta), select_related, and
-        prefetch_related on discovered reverse relations.
+        This method handles single-object retrieval with automatic query optimizations
+        including select_related and prefetch_related based on the model's relationships
+        and the query parameters.
 
         Parameters
         ----------
         request : HttpRequest
+            The HTTP request object, used for queryset_request hooks.
         pk : int | str, optional
-            Primary key lookup.
-        filters : dict, optional
-            Additional filter kwargs.
-        getters : dict, optional
-            Field lookups combined with pk lookup.
-        with_qs_request : bool
-            Whether to apply model-level queryset_request hook.
+            Primary key value for single object lookup. Defaults to None.
+        query_data : ObjectQuerySchema, optional
+            Schema containing getters and query optimization parameters.
+            Defaults to an empty ObjectQuerySchema instance.
+        with_qs_request : bool, optional
+            Whether to apply the model's queryset_request hook if available.
+            Defaults to True.
+        is_for_read : bool, optional
+            Flag indicating if the query is for read operations, which may affect
+            query optimization strategies. Defaults to False.
 
         Returns
         -------
-        Model | QuerySet
-            Instance if lookup provided; otherwise queryset.
+        type["ModelSerializer"] | models.Model
+            A single model instance.
 
         Raises
         ------
+        ValueError
+            If neither pk nor getters are provided.
         NotFoundError
-            If instance not found by lookup criteria.
-        """
-        get_q = {self.model_pk_name: pk} if pk is not None else {}
-        if getters:
-            get_q |= getters
+            If no matching object exists in the database.
 
-        obj_qs = self.model.objects.select_related()
-        if isinstance(self.model, ModelSerializerMeta) and with_qs_request:
-            obj_qs = await self.model.queryset_request(request)
+        Notes
+        -----
+        - Query optimizations are automatically applied based on discovered relationships
+        - The queryset_request hook is called if the model implements ModelSerializerMeta
+        """
+        if query_data is None:
+            query_data = ObjectQuerySchema()
 
-        obj_qs = obj_qs.prefetch_related(*self.get_reverse_relations())
-        if filters:
-            obj_qs = obj_qs.filter(**filters)
+        if not query_data.getters and pk is None:
+            raise ValueError(
+                "Either pk or getters must be provided for single object retrieval."
+            )
 
-        if not get_q:
-            return obj_qs
+        # Build lookup query and get optimized queryset
+        get_q = self._build_lookup_query(pk, query_data.getters)
+        obj_qs = await self._get_base_queryset(
+            request, query_data, with_qs_request, is_for_read
+        )
 
+        # Perform lookup
         try:
             obj = await obj_qs.aget(**get_q)
         except ObjectDoesNotExist:
@@ -237,6 +372,68 @@ class ModelUtil:
 
         return obj
 
+    def _build_lookup_query(self, pk: int | str = None, getters: dict = None) -> dict:
+        """
+        Build lookup query dict from pk and additional getters.
+
+        Parameters
+        ----------
+        pk : int | str, optional
+            Primary key value.
+        getters : dict, optional
+            Additional field lookups.
+
+        Returns
+        -------
+        dict
+            Combined lookup criteria.
+        """
+        get_q = {self.model_pk_name: pk} if pk is not None else {}
+        if getters:
+            get_q |= getters
+        return get_q
+
+    def _apply_query_optimizations(
+        self,
+        queryset: models.QuerySet,
+        query_data: QuerySchema,
+        is_for_read: bool,
+    ) -> models.QuerySet:
+        """
+        Apply select_related and prefetch_related optimizations to queryset.
+
+        Parameters
+        ----------
+        queryset : QuerySet
+            Base queryset to optimize.
+        query_data : ModelQuerySchema
+            Query configuration with select_related/prefetch_related lists.
+        is_for_read : bool
+            Whether to include model-level relation discovery.
+
+        Returns
+        -------
+        QuerySet
+            Optimized queryset.
+        """
+        select_related = (
+            query_data.select_related + self.get_select_relateds()
+            if is_for_read
+            else query_data.select_related
+        )
+        prefetch_related = (
+            query_data.prefetch_related + self.get_reverse_relations()
+            if is_for_read
+            else query_data.prefetch_related
+        )
+
+        if select_related:
+            queryset = queryset.select_related(*select_related)
+        if prefetch_related:
+            queryset = queryset.prefetch_related(*prefetch_related)
+
+        return queryset
+
     def get_reverse_relations(self) -> list[str]:
         """
         Discover reverse relation names for safe prefetching.
@@ -259,6 +456,25 @@ class ModelUtil:
                 reverse_rels.append(field_obj.related.name)
         return reverse_rels
 
+    def get_select_relateds(self) -> list[str]:
+        """
+        Discover forward relation names for safe select_related.
+
+        Returns
+        -------
+        list[str]
+            Relation attribute names.
+        """
+        select_rels = []
+        for f in self.serializable_fields:
+            field_obj = getattr(self.model, f)
+            if isinstance(field_obj, ForwardManyToOneDescriptor):
+                select_rels.append(f)
+                continue
+            if isinstance(field_obj, ForwardOneToOneDescriptor):
+                select_rels.append(f)
+        return select_rels
+
     async def _get_field(self, k: str):
         return (await agetattr(self.model, k)).field
 
@@ -284,49 +500,80 @@ class ModelUtil:
         rel = await rel_util.get_object(request, v, with_qs_request=False)
         payload[k] = rel
 
-    async def _extract_field_obj(self, field_name: str):
-        """
-        Return the underlying Django Field (if any) for a given attribute name.
-        """
-        descriptor = await agetattr(self.model, field_name, None)
-        if descriptor is None:
-            return None
-        return await agetattr(descriptor, "field", None) or await agetattr(
-            descriptor, "related", None
-        )
+    async def _bump_object_from_schema(
+        self, obj: type["ModelSerializer"] | models.Model, schema: Schema
+    ):
+        return (await sync_to_async(schema.from_orm)(obj)).model_dump(mode="json")
 
-    def _should_process_nested(self, value: Any, field_obj: Any) -> bool:
-        """
-        Determine if a payload entry represents a nested FK / O2O relation dict.
-        """
-        if not isinstance(value, dict):
-            return False
-        return isinstance(field_obj, (models.ForeignKey, models.OneToOneField))
+    def _validate_read_params(self, request: HttpRequest, query_data: QuerySchema):
+        """Validate required parameters for read operations."""
+        if request is None:
+            raise SerializeError(
+                {"request": "must be provided when object is not given"}, 400
+            )
+
+        if query_data is None:
+            raise SerializeError(
+                {"query_data": "must be provided when object is not given"}, 400
+            )
 
-    async def _fetch_related_instance(
-        self, request, field_obj: models.Field, nested_dict: dict
+        if (
+            hasattr(query_data, "filters")
+            and hasattr(query_data, "getters")
+            and query_data.filters
+            and query_data.getters
+        ):
+            raise SerializeError(
+                {"query_data": "cannot contain both filters and getters"}, 400
+            )
+
+    async def _handle_query_mode(
+        self,
+        request: HttpRequest,
+        query_data: QuerySchema,
+        schema: Schema,
+        is_for_read: bool,
     ):
-        """
-        Resolve the related instance from its primary key inside the nested dict.
-        """
-        rel_util = ModelUtil(field_obj.related_model)
-        rel_pk = nested_dict.get(rel_util.model_pk_name)
-        return await rel_util.get_object(request, rel_pk)
+        """Handle different query modes (filters vs getters)."""
+        if hasattr(query_data, "filters") and query_data.filters:
+            return await self._serialize_queryset(
+                request, query_data, schema, is_for_read
+            )
 
-    async def _rewrite_nested_foreign_keys(self, rel_obj, nested_dict: dict):
-        """
-        Rewrite foreign key keys inside a nested dict from <key> to <key>_id.
-        """
-        keys_to_rewrite: list[str] = []
-        new_nested = nested_dict
-        for rel_k in nested_dict.keys():
-            attr = await agetattr(rel_obj, rel_k)
-            if isinstance(attr, models.ForeignKey):
-                keys_to_rewrite.append(rel_k)
-        for old_k in keys_to_rewrite:
-            new_nested[f"{old_k}_id"] = new_nested.pop(old_k)
-        return new_nested
+        if hasattr(query_data, "getters") and query_data.getters:
+            return await self._serialize_single_object(
+                request, query_data, schema, is_for_read
+            )
 
+        raise SerializeError(
+            {"query_data": "must contain either filters or getters"}, 400
+        )
+
+    async def _serialize_queryset(
+        self,
+        request: HttpRequest,
+        query_data: QuerySchema,
+        schema: Schema,
+        is_for_read: bool,
+    ):
+        """Serialize a queryset of objects."""
+        objs = await self.get_objects(
+            request, query_data=query_data, is_for_read=is_for_read
+        )
+        return [await self._bump_object_from_schema(obj, schema) async for obj in objs]
+
+    async def _serialize_single_object(
+        self,
+        request: HttpRequest,
+        query_data: QuerySchema,
+        obj_schema: Schema,
+        is_for_read: bool,
+    ):
+        """Serialize a single object."""
+        obj = await self.get_object(
+            request, query_data=query_data, is_for_read=is_for_read
+        )
+        return await self._bump_object_from_schema(obj, obj_schema)
 
     async def parse_input_data(self, request: HttpRequest, data: Schema):
         """
@@ -396,37 +643,6 @@ class ModelUtil:
 
         return new_payload, customs
 
-    async def parse_output_data(self, request: HttpRequest, data: Schema):
-        """
-        Post-process serialized output.
-
-        For nested FK / OneToOne dicts:
-        - Replace dict with authoritative related instance.
-        - Rewrite nested FK keys to <name>_id for nested foreign keys.
-
-        Parameters
-        ----------
-        request : HttpRequest
-        data : Schema
-            Schema (from_orm) instance.
-
-        Returns
-        -------
-        dict
-            Normalized output payload.
-        """
-        payload = data.model_dump(mode="json")
-
-        for k, v in payload.items():
-            field_obj = await self._extract_field_obj(k)
-            if not self._should_process_nested(v, field_obj):
-                continue
-            rel_instance = await self._fetch_related_instance(request, field_obj, v)
-            if isinstance(field_obj, models.ForeignKey):
-                v = await self._rewrite_nested_foreign_keys(rel_instance, v)
-            payload[k] = rel_instance
-        return payload
-
     async def create_s(self, request: HttpRequest, data: Schema, obj_schema: Schema):
         """
         Create a new instance and return serialized output.
@@ -451,39 +667,167 @@ class ModelUtil:
         obj = await self.get_object(request, pk)
         if isinstance(self.model, ModelSerializerMeta):
             await asyncio.gather(obj.custom_actions(customs), obj.post_create())
-        return await self.read_s(request, obj, obj_schema)
+        return await self.read_s(obj_schema, request, obj)
 
-    async def read_s(
+    async def _read_s(
         self,
-        request: HttpRequest,
-        obj: type["ModelSerializer"],
-        obj_schema: Schema,
+        schema: Schema,
+        request: HttpRequest = None,
+        instance: models.QuerySet[type["ModelSerializer"] | models.Model]
+        | type["ModelSerializer"]
+        | models.Model = None,
+        query_data: QuerySchema = None,
+        is_for_read: bool = False,
     ):
         """
-        Serialize an existing instance with the provided read schema.
+        Internal serialization method handling both single instances and querysets.
 
         Parameters
         ----------
-        request : HttpRequest
-        obj : Model
-            Target instance.
-        obj_schema : Schema
-            Read schema class.
+        schema : Schema
+            Read schema class for serialization.
+        request : HttpRequest, optional
+            HTTP request object, required when instance is None.
+        instance : QuerySet | Model, optional
+            Instance(s) to serialize. If None, fetches based on query_data.
+        query_data : QuerySchema, optional
+            Query parameters for fetching objects when instance is None.
+        is_for_read : bool, optional
+            Whether to apply read-specific query optimizations.
+
+        Returns
+        -------
+        dict | list[dict]
+            Serialized instance(s).
+
+        Raises
+        ------
+        SerializeError
+            If schema is None or validation fails.
+        """
+        if schema is None:
+            raise SerializeError({"schema": "must be provided"}, 400)
+
+        if instance is not None:
+            if isinstance(instance, models.QuerySet):
+                return [
+                    await self._bump_object_from_schema(obj, schema)
+                    async for obj in instance
+                ]
+            return await self._bump_object_from_schema(instance, schema)
+
+        self._validate_read_params(request, query_data)
+        return await self._handle_query_mode(request, query_data, schema, is_for_read)
+
+    async def read_s(
+        self,
+        schema: Schema,
+        request: HttpRequest = None,
+        instance: type["ModelSerializer"] = None,
+        query_data: ObjectQuerySchema = None,
+        is_for_read: bool = False,
+    ) -> dict:
+        """
+        Serialize a single model instance or fetch and serialize using query parameters.
+
+        This method handles single-object serialization. It can serialize a provided
+        instance directly or fetch and serialize a single object using query_data.getters.
+
+        Parameters
+        ----------
+        schema : Schema
+            Read schema class for serialization output.
+        request : HttpRequest, optional
+            HTTP request object, required when instance is None.
+        instance : ModelSerializer | Model, optional
+            Single instance to serialize. If None, fetched based on query_data.
+        query_data : ObjectQuerySchema, optional
+            Query parameters with getters for single object lookup.
+            Required when instance is None.
+        is_for_read : bool, optional
+            Whether to apply read-specific query optimizations. Defaults to False.
 
         Returns
         -------
         dict
-            Serialized payload.
+            Serialized model instance as dictionary.
 
         Raises
         ------
         SerializeError
-            If obj_schema not provided.
+            - If schema is None
+            - If instance is None and request or query_data is None
+            - If query_data validation fails
+        NotFoundError
+            If using getters and no matching object is found.
+
+        Notes
+        -----
+        - Uses Pydantic's from_orm() with mode="json" for serialization
+        - When instance is provided, request and query_data are ignored
+        - Query optimizations applied when is_for_read=True
+        """
+        return await self._read_s(
+            schema,
+            request,
+            instance,
+            query_data,
+            is_for_read,
+        )
+
+    async def list_read_s(
+        self,
+        schema: Schema,
+        request: HttpRequest = None,
+        instances: models.QuerySet[type["ModelSerializer"] | models.Model] = None,
+        query_data: ObjectsQuerySchema = None,
+        is_for_read: bool = False,
+    ) -> list[dict]:
         """
-        if obj_schema is None:
-            raise SerializeError({"obj_schema": "must be provided"}, 400)
-        return await self.parse_output_data(
-            request, await sync_to_async(obj_schema.from_orm)(obj)
+        Serialize multiple model instances or fetch and serialize using query parameters.
+
+        This method handles queryset serialization. It can serialize provided instances
+        directly or fetch and serialize multiple objects using query_data.filters.
+
+        Parameters
+        ----------
+        schema : Schema
+            Read schema class for serialization output.
+        request : HttpRequest, optional
+            HTTP request object, required when instances is None.
+        instances : QuerySet, optional
+            Queryset of instances to serialize. If None, fetched based on query_data.
+        query_data : ObjectsQuerySchema, optional
+            Query parameters with filters for multiple object lookup.
+            Required when instances is None.
+        is_for_read : bool, optional
+            Whether to apply read-specific query optimizations. Defaults to False.
+
+        Returns
+        -------
+        list[dict]
+            List of serialized model instances as dictionaries.
+
+        Raises
+        ------
+        SerializeError
+            - If schema is None
+            - If instances is None and request or query_data is None
+            - If query_data validation fails
+
+        Notes
+        -----
+        - Uses Pydantic's from_orm() with mode="json" for serialization
+        - When instances is provided, request and query_data are ignored
+        - Query optimizations applied when is_for_read=True
+        - Processes queryset asynchronously for efficiency
+        """
+        return await self._read_s(
+            schema,
+            request,
+            instances,
+            query_data,
+            is_for_read,
         )
 
     async def update_s(
@@ -518,7 +862,7 @@ class ModelUtil:
             await obj.custom_actions(customs)
         await obj.asave()
         updated_object = await self.get_object(request, pk)
-        return await self.read_s(request, updated_object, obj_schema)
+        return await self.read_s(obj_schema, request, updated_object)
 
     async def delete_s(self, request: HttpRequest, pk: int | str):
         """
@@ -555,9 +899,39 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
     See inline docstrings for per-method behavior.
     """
 
+    util: ClassVar[ModelUtil]
+    query_util: ClassVar[QueryUtil]
+
     class Meta:
         abstract = True
 
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        # Bind a ModelUtil instance to the subclass for convenient access
+        cls.util = ModelUtil(cls)
+        cls.query_util = QueryUtil(cls)
+
+    class QuerySet:
+        """
+        Configuration container describing how to build query schemas for a model.
+        Purpose
+        -------
+        Describes which fields and extras are available when querying for model
+        instances. A factory/metaclass can read this configuration to generate
+        Pydantic / Ninja query schemas.
+        Attributes
+        ----------
+        read : ModelQuerySetSchema
+            Schema configuration for read operations.
+        queryset_request : ModelQuerySetSchema
+            Schema configuration for queryset_request hook.
+        extras : list[ModelQuerySetExtraSchema]
+            Additional computed / synthetic query parameters.
+        """
+        read = ModelQuerySetSchema()
+        queryset_request = ModelQuerySetSchema()
+        extras: list[ModelQuerySetExtraSchema] = []
+
     class CreateSerializer:
         """Configuration container describing how to build a create (input) schema for a model.
 
@@ -621,48 +995,6 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
         optionals: list[tuple[str, type]] = []
         excludes: list[str] = []
 
-    @property
-    def has_custom_fields_create(self):
-        """
-        Whether CreateSerializer declares custom fields.
-        """
-        return hasattr(self.CreateSerializer, "customs")
-
-    @property
-    def has_custom_fields_update(self):
-        """
-        Whether UpdateSerializer declares custom fields.
-        """
-        return hasattr(self.UpdateSerializer, "customs")
-
-    @property
-    def has_custom_fields(self):
-        """
-        Whether any serializer declares custom fields.
-        """
-        return self.has_custom_fields_create or self.has_custom_fields_update
-
-    @property
-    def has_optional_fields_create(self):
-        """
-        Whether CreateSerializer declares optional fields.
-        """
-        return hasattr(self.CreateSerializer, "optionals")
-
-    @property
-    def has_optional_fields_update(self):
-        """
-        Whether UpdateSerializer declares optional fields.
-        """
-        return hasattr(self.UpdateSerializer, "optionals")
-
-    @property
-    def has_optional_fields(self):
-        """
-        Whether any serializer declares optional fields.
-        """
-        return self.has_optional_fields_create or self.has_optional_fields_update
-
     @classmethod
     def _get_fields(cls, s_type: type[S_TYPES], f_type: type[F_TYPES]):
         """
@@ -823,7 +1155,10 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
         -------
         QuerySet
         """
-        return cls.objects.select_related().all()
+        return cls.query_util.apply_queryset_optimizations(
+            queryset=cls.objects.all(),
+            scope=cls.query_util.SCOPES.QUERYSET_REQUEST,
+        )
 
     async def post_create(self) -> None:
         """
@@ -1179,11 +1514,12 @@ class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
         """
         Override save lifecycle to inject create/update hooks.
         """
-        if self._state.adding:
+        state_adding = self._state.adding
+        if state_adding:
             self.on_create_before_save()
         self.before_save()
         super().save(*args, **kwargs)
-        if self._state.adding:
+        if state_adding:
             self.on_create_after_save()
         self.after_save()
 

django_ninja_aio_crud-2.0.0rc1/ninja_aio/schemas/__init__.py

@@ -0,0 +1,23 @@
+from .generics import GenericMessageSchema
+from .api import (
+    M2MDetailSchema,
+    M2MSchemaOut,
+    M2MAddSchemaIn,
+    M2MRemoveSchemaIn,
+    M2MSchemaIn,
+)
+from .helpers import M2MRelationSchema, QuerySchema, ModelQuerySetSchema, ObjectQuerySchema, ObjectsQuerySchema
+
+__all__ = [
+    "GenericMessageSchema",
+    "M2MDetailSchema",
+    "M2MSchemaOut",
+    "M2MAddSchemaIn",
+    "M2MRemoveSchemaIn",
+    "M2MSchemaIn",
+    "M2MRelationSchema",
+    "QuerySchema",
+    "ModelQuerySetSchema",
+    "ObjectQuerySchema",
+    "ObjectsQuerySchema",
+]

django_ninja_aio_crud-2.0.0rc1/ninja_aio/schemas/api.py

@@ -0,0 +1,24 @@
+from ninja import Schema
+
+
+class M2MDetailSchema(Schema):
+    count: int
+    details: list[str]
+
+
+class M2MSchemaOut(Schema):
+    errors: M2MDetailSchema
+    results: M2MDetailSchema
+
+
+class M2MAddSchemaIn(Schema):
+    add: list = []
+
+
+class M2MRemoveSchemaIn(Schema):
+    remove: list = []
+
+
+class M2MSchemaIn(Schema):
+    add: list = []
+    remove: list = []

django_ninja_aio_crud-2.0.0rc1/ninja_aio/schemas/generics.py

@@ -0,0 +1,5 @@
+from pydantic import RootModel
+
+
+class GenericMessageSchema(RootModel[dict[str, str]]):
+    root: dict[str, str]

django_ninja_aio_crud-1.0.5/ninja_aio/schemas.py → django_ninja_aio_crud-2.0.0rc1/ninja_aio/schemas/helpers.py

@@ -1,36 +1,9 @@
 from typing import Optional, Type
 
 from ninja import Schema
-from .models import ModelSerializer
+from ninja_aio.types import ModelSerializerMeta
 from django.db.models import Model
-from pydantic import BaseModel, RootModel, ConfigDict, model_validator
-
-
-class GenericMessageSchema(RootModel[dict[str, str]]):
-    root: dict[str, str]
-
-
-class M2MDetailSchema(Schema):
-    count: int
-    details: list[str]
-
-
-class M2MSchemaOut(Schema):
-    errors: M2MDetailSchema
-    results: M2MDetailSchema
-
-
-class M2MAddSchemaIn(Schema):
-    add: list = []
-
-
-class M2MRemoveSchemaIn(Schema):
-    remove: list = []
-
-
-class M2MSchemaIn(Schema):
-    add: list = []
-    remove: list = []
+from pydantic import BaseModel, ConfigDict, model_validator
 
 
 class M2MRelationSchema(BaseModel):
@@ -55,7 +28,7 @@ class M2MRelationSchema(BaseModel):
         )
     """
 
-    model: Type[ModelSerializer] | Type[Model]
+    model: ModelSerializerMeta | Type[Model]
     related_name: str
     add: bool = True
     remove: bool = True
@@ -74,9 +47,36 @@ class M2MRelationSchema(BaseModel):
         if related_schema is not None:
             return data
         model = data.get("model")
-        if not issubclass(model, ModelSerializer):
+        if not isinstance(model, ModelSerializerMeta):
             raise ValueError(
                 "related_schema must be provided if model is not a ModelSerializer",
             )
         data["related_schema"] = model.generate_related_s()
         return data
+
+
+class ModelQuerySetSchema(BaseModel):
+    select_related: Optional[list[str]] = []
+    prefetch_related: Optional[list[str]] = []
+
+
+class ModelQuerySetExtraSchema(ModelQuerySetSchema):
+    scope: str
+
+
+class ObjectQuerySchema(ModelQuerySetSchema):
+    getters: Optional[dict] = {}
+
+
+class ObjectsQuerySchema(ModelQuerySetSchema):
+    filters: Optional[dict] = {}
+
+
+class QuerySchema(ModelQuerySetSchema):
+    filters: Optional[dict] = {}
+    getters: Optional[dict] = {}
+
+
+class QueryUtilBaseScopesSchema(BaseModel):
+    READ: str = "read"
+    QUERYSET_REQUEST: str = "queryset_request"

{django_ninja_aio_crud-1.0.5 → django_ninja_aio_crud-2.0.0rc1}/ninja_aio/views.py

@@ -7,12 +7,14 @@ from django.http import HttpRequest
 from django.db.models import Model, QuerySet
 from pydantic import create_model
 
+from ninja_aio.schemas.helpers import ModelQuerySetSchema, QuerySchema
+
 from .models import ModelSerializer, ModelUtil
 from .schemas import (
     GenericMessageSchema,
     M2MRelationSchema,
 )
-from .helpers import ManyToManyAPI
+from .helpers.api import ManyToManyAPI
 from .types import ModelSerializerMeta, VIEW_TYPES
 from .decorators import unique_view
 
@@ -178,7 +180,11 @@ class APIViewSet:
 
     def __init__(self) -> None:
         self.error_codes = ERROR_CODES
-        self.model_util = ModelUtil(self.model)
+        self.model_util = (
+            ModelUtil(self.model)
+            if not isinstance(self.model, ModelSerializerMeta)
+            else self.model.util
+        )
         self.schema_out, self.schema_in, self.schema_update = self.get_schemas()
         self.path_schema = self._generate_path_schema()
         self.filters_schema = self._generate_filters_schema()
@@ -241,7 +247,7 @@ class APIViewSet:
         Schema containing only the primary key field for path resolution.
         """
         return self._generate_schema(
-            {self.model_util.model_pk_name: (int | str, ...)}, "PathSchema"
+            {self.model_util.model_pk_name: self.model_util.pk_field_type}, "PathSchema"
         )
 
     def _generate_filters_schema(self):
@@ -256,6 +262,16 @@ class APIViewSet:
         """
         return data.model_dump()[self.model_util.model_pk_name]
 
+    def _get_query_data(self) -> ModelQuerySetSchema:
+        """
+        Return default query data for list/retrieve views.
+        """
+        return (
+            ModelQuerySetSchema()
+            if not isinstance(self.model, ModelSerializerMeta)
+            else self.model.query_util.read_config
+        )
+
     def get_schemas(self):
         """
         Return (schema_out, schema_in, schema_update), generating them if model is a ModelSerializer.
@@ -317,19 +333,14 @@ class APIViewSet:
             request: HttpRequest,
             filters: Query[self.filters_schema] = None,  # type: ignore
         ):
-            qs = self.model.objects.select_related()
-            if isinstance(self.model, ModelSerializerMeta):
-                qs = await self.model.queryset_request(request)
-            rels = self.model_util.get_reverse_relations()
-            if len(rels) > 0:
-                qs = qs.prefetch_related(*rels)
+            qs = await self.model_util.get_objects(
+                request,
+                query_data=self._get_query_data(),
+                is_for_read=True,
+            )
             if filters is not None:
                 qs = await self.query_params_handler(qs, filters.model_dump())
-            objs = [
-                await self.model_util.read_s(request, obj, self.schema_out)
-                async for obj in qs.all()
-            ]
-            return objs
+            return await self.model_util.list_read_s(self.schema_out, request, qs)
 
         return list
 
@@ -347,8 +358,14 @@ class APIViewSet:
         )
         @unique_view(self)
         async def retrieve(request: HttpRequest, pk: Path[self.path_schema]):  # type: ignore
-            obj = await self.model_util.get_object(request, self._get_pk(pk))
-            return await self.model_util.read_s(request, obj, self.schema_out)
+            query_data = self._get_query_data()
+            return await self.model_util.read_s(
+                self.schema_out,
+                request,
+                query_data=QuerySchema(
+                    getters={"pk": self._get_pk(pk)}, **query_data.model_dump()
+                ),
+            )
 
         return retrieve
 

{django_ninja_aio_crud-1.0.5 → django_ninja_aio_crud-2.0.0rc1}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
 ]
 
-requires = ["django-ninja >=1.3.0, <=1.4.5", "joserfc >=1.0.0, <= 1.4.1", "orjson >= 3.10.7, <= 3.11.4"]
+requires = ["django-ninja >=1.3.0, <=1.5.0", "joserfc >=1.0.0, <= 1.4.1", "orjson >= 3.10.7, <= 3.11.4"]
 description-file = "README.md"
 requires-python = ">=3.10"
 

django_ninja_aio_crud-1.0.5/ninja_aio/helpers/__init__.py

@@ -1,3 +0,0 @@
-from .api import ManyToManyAPI
-
-__all__ = ["ManyToManyAPI"]