Typehints and Postprocessor returns Any

Author: Archmonger

docs/src/features/hooks.md

@@ -103,7 +103,7 @@ The function you provide into this hook must return either a `Model` or `QuerySe
     1. Want to use this hook to defer IO intensive tasks to be computed in the background
     2. Want to to utilize `use_query` with a different ORM
 
-    ... then you can disable all postprocessing behavior by modifying the `QueryOptions.postprocessor` parameter. In the example below, we will set the `postprocessor` to a function that takes one argument and returns `None`.
+    ... then you can disable all postprocessing behavior by modifying the `QueryOptions.postprocessor` parameter. In the example below, we will set the `postprocessor` to `None`.
 
     === "components.py"
 
@@ -118,10 +118,8 @@ The function you provide into this hook must return either a `Model` or `QuerySe
 
         @component
         def todo_list():
-            # By setting the postprocessor to a function that takes one argument
-            # and returns None, we can disable postprocessing behavior.
             query = use_query(
-                QueryOptions(postprocessor=lambda data: None),
+                QueryOptions(postprocessor=None),
                 execute_io_intensive_operation,
             )
 

src/django_idom/hooks.py

@@ -26,7 +26,7 @@
     _Params,
     _Result,
 )
-from django_idom.utils import _generate_obj_name, django_query_postprocessor
+from django_idom.utils import _generate_obj_name
 
 
 _logger = logging.getLogger(__name__)
@@ -155,17 +155,11 @@ def execute_query() -> None:
             # Run the initial query
             new_data = query(*args, **kwargs)
 
-            # Use a custom postprocessor, if provided
             if query_options.postprocessor:
-                query_options.postprocessor(
+                new_data = query_options.postprocessor(
                     new_data, **query_options.postprocessor_kwargs
                 )
 
-            # Use the default postprocessor
-            else:
-                django_query_postprocessor(
-                    new_data, **query_options.postprocessor_kwargs
-                )
         except Exception as e:
             set_data(None)
             set_loading(False)

src/django_idom/types.py

@@ -18,6 +18,8 @@
 from django.views.generic import View
 from typing_extensions import ParamSpec
 
+from django_idom.utils import django_query_postprocessor
+
 
 __all__ = ["_Result", "_Params", "_Data", "IdomWebsocket", "Query", "Mutation"]
 
@@ -64,16 +66,20 @@ class ViewComponentIframe:
 
 
 class Postprocessor(Protocol):
-    def __call__(self, data: Any, **kwargs: Any) -> None:
+    def __call__(self, data: Any) -> Any:
         ...
 
 
 @dataclass
 class QueryOptions:
     """Configuration options that can be provided to `use_query`."""
 
-    postprocessor: Postprocessor | None = None
-    """A post processing callable that can read/modify the query `data`.
+    postprocessor: Postprocessor | None = django_query_postprocessor
+    """A callable that can modify the query `data` after the query has been executed.
+
+    The first argument of postprocessor must be the query `data`. All proceeding arguments
+    are optional `postprocessor_kwargs` (see below). This postprocessor function must return
+    the modified `data`.
 
     If `None`, the default postprocessor is used.
 

src/django_idom/utils.py

@@ -206,8 +206,8 @@ def _generate_obj_name(object: Any) -> str | None:
 
 
 def django_query_postprocessor(
-    data: QuerySet | Model, /, many_to_many: bool = True, many_to_one: bool = True
-) -> None:
+    data: QuerySet | Model, many_to_many: bool = True, many_to_one: bool = True
+) -> QuerySet | Model:
     """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."""
@@ -254,3 +254,5 @@ def django_query_postprocessor(
             "  - You are attempting to use `use_query` to fetch non-ORM data.\n\n"
             "If these situations seem correct, you may want to consider disabling the postprocessor via `QueryOptions`."
         )
+
+    return data