Typehints, Postprocessor returns Any, and defaults configuration value for postprocessor

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,
             )
 

docs/src/features/settings.md

@@ -20,6 +20,9 @@
 
     # The URL for IDOM to serve websockets
     IDOM_WEBSOCKET_URL = "idom/"
+
+    # Dotted path to the default postprocessor function, or `None`
+    IDOM_DEFAULT_QUERY_POSTPROCESSOR = "example_project.utils.my_postprocessor"
     ```
 
     <!--settings-end-->

src/django_idom/config.py

@@ -1,10 +1,13 @@
+from __future__ import annotations
+
 from typing import Dict
 
 from django.conf import settings
 from django.core.cache import DEFAULT_CACHE_ALIAS, BaseCache, caches
 from idom.core.types import ComponentConstructor
 
-from django_idom.types import ViewComponentIframe
+from django_idom.defaults import _DEFAULT_QUERY_POSTPROCESSOR
+from django_idom.types import Postprocessor, ViewComponentIframe
 
 
 IDOM_REGISTERED_COMPONENTS: Dict[str, ComponentConstructor] = {}
@@ -14,6 +17,7 @@
 IDOM_WS_MAX_RECONNECT_TIMEOUT = getattr(
     settings, "IDOM_WS_MAX_RECONNECT_TIMEOUT", 604800
 )
+IDOM_DEFAULT_QUERY_POSTPROCESSOR: Postprocessor | None = _DEFAULT_QUERY_POSTPROCESSOR
 
 # Determine if using Django caching or LRU cache
 IDOM_CACHE: BaseCache = (

src/django_idom/defaults.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from django.conf import settings
+
+from django_idom.utils import _import_dotted_path
+
+
+_DEFAULT_QUERY_POSTPROCESSOR: Callable[..., Any] | None = _import_dotted_path(
+    getattr(
+        settings,
+        "IDOM_DEFAULT_QUERY_POSTPROCESSOR",
+        "django_idom.utils.django_query_postprocessor",
+    )
+)

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.defaults import _DEFAULT_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 = _DEFAULT_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

@@ -19,8 +19,6 @@
 from django.utils.encoding import smart_str
 from django.views import View
 
-from django_idom.config import IDOM_REGISTERED_COMPONENTS
-
 
 _logger = logging.getLogger(__name__)
 _component_tag = r"(?P<tag>component)"
@@ -77,6 +75,8 @@ async def render_view(
 
 
 def _register_component(dotted_path: str) -> None:
+    from django_idom.config import IDOM_REGISTERED_COMPONENTS
+
     if dotted_path in IDOM_REGISTERED_COMPONENTS:
         return
 
@@ -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