postprocessor options as kwargs

Author: Archmonger

src/django_idom/hooks.py

@@ -159,11 +159,11 @@ def execute_query() -> None:
 
             # Use a custom postprocessor, if provided
             if query_options.postprocessor:
-                query_options.postprocessor(data, query_options)
+                query_options.postprocessor(data, **query_options.postprocessor_options)
 
             # Use the default postprocessor
             else:
-                _postprocess_django_query(data, query_options.postprocessor_options)
+                _postprocess_django_query(data, **query_options.postprocessor_options)
         except Exception as e:
             set_data(None)
             set_loading(False)
@@ -235,7 +235,9 @@ def reset() -> None:
     return Mutation(call, loading, error, reset)
 
 
-def _postprocess_django_query(data: QuerySet | Model, options: dict[str, Any]) -> None:
+def _postprocess_django_query(
+    data: QuerySet | Model, /, many_to_many: bool = False, many_to_one: bool = False
+) -> None:
     """Recursively fetch all fields within a `Model` or `QuerySet` to ensure they are not performed lazily.
 
     Some behaviors can be modified through `query_options` attributes."""
@@ -244,7 +246,11 @@ def _postprocess_django_query(data: QuerySet | Model, options: dict[str, Any]) -
     # https://github.com/typeddjango/django-stubs/issues/704
     if isinstance(data, QuerySet):  # type: ignore[misc]
         for model in data:
-            _postprocess_django_query(model, options)
+            _postprocess_django_query(
+                model,
+                many_to_many=many_to_many,
+                many_to_one=many_to_one,
+            )
 
     # `Model` instances
     elif isinstance(data, Model):
@@ -255,20 +261,26 @@ def _postprocess_django_query(data: QuerySet | Model, options: dict[str, Any]) -
             with contextlib.suppress(AttributeError):
                 getattr(data, field.name)
 
-            if options.get("many_to_one", False) and type(field) == ManyToOneRel:
+            if many_to_one and type(field) == ManyToOneRel:
                 prefetch_fields.append(f"{field.name}_set")
 
-            elif options.get("many_to_many", False) and isinstance(
-                field, ManyToManyField
-            ):
+            elif many_to_many and isinstance(field, ManyToManyField):
                 prefetch_fields.append(field.name)
                 _postprocess_django_query(
-                    getattr(data, field.name).get_queryset(), options
+                    getattr(data, field.name).get_queryset(),
+                    many_to_many=many_to_many,
+                    many_to_one=many_to_one,
                 )
 
         if prefetch_fields:
             prefetch_related_objects([data], *prefetch_fields)
 
     # Unrecognized type
     else:
-        raise ValueError(f"Expected a Model or QuerySet, got {data!r}")
+        raise TypeError(
+            f"Django query postprocessor expected a Model or QuerySet, got {data!r}.\n"
+            "One of the following may have occurred:\n"
+            "  - You are using a non-Django ORM.\n"
+            "  - You are attempting to use `use_query` to fetch a non-ORM data.\n\n"
+            "If these situations seem correct, you may want to consider disabling the postprocessor via `QueryOptions`."
+        )

src/django_idom/types.py

@@ -1,7 +1,17 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any, Awaitable, Callable, Generic, Optional, Sequence, TypeVar, Union
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Generic,
+    Optional,
+    Protocol,
+    Sequence,
+    TypeVar,
+    Union,
+)
 
 from django.db.models.base import Model
 from django.db.models.query import QuerySet
@@ -53,15 +63,25 @@ class ViewComponentIframe:
     kwargs: dict
 
 
+class Postprocessor(Protocol):
+    def __call__(self, data: Any, **kwargs: Any) -> None:
+        ...
+
+
 @dataclass
 class QueryOptions:
     """Configuration options that can be provided to `use_query`."""
 
     postprocessor_options: dict[str, Any] = field(default_factory=lambda: {})
     """Configuration values usable by the `postprocessor`."""
 
-    postprocessor: Callable[[_Data, QueryOptions], None] | None = None
-    """A post processing callable that can read/modify the query `data` and the `QueryOptions` object.
+    postprocessor: Postprocessor | None = None
+    """A post processing callable that can read/modify the query `data`.
+
+    `postprocessor_options` are provided to this `postprocessor` as keyword arguments.
+
+    If `None`, the default postprocessor is used.
 
-    If unset, the default handler is used. This handler can be configured via `postprocessor_options`
-    to recursively fetch all fields to ensure queries are not performed lazily."""
+    This default Django query postprocessor prevents Django's lazy query execution, and
+    additionally can be configured via `postprocessor_options` to recursively fetch
+    `many_to_many` and `many_to_one` fields."""