documentation

Author: Archmonger

docs/src/dictionary.txt

@@ -22,3 +22,5 @@ unstyled
 py
 idom
 asgi
+postfixed
+postprocessing

docs/src/features/hooks.md

@@ -54,6 +54,7 @@ The function you provide into this hook must return either a `Model` or `QuerySe
     | Name | Type | Description | Default |
     | --- | --- | --- | --- |
     | `query` | `Callable[_Params, _Result | None]` | A callable that returns a Django `Model` or `QuerySet`. | N/A |
+    | `options` | `QueryOptions | None` | An optional `QueryOptions` object that can modify how the query is executed. | None |
     | `*args` | `_Params.args` | Positional arguments to pass into `query`. | N/A |
     | `**kwargs` | `_Params.kwargs` | Keyword arguments to pass into `query`. | N/A |
 
@@ -67,19 +68,83 @@ The function you provide into this hook must return either a `Model` or `QuerySe
 
     Due to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a `SynchronousOnlyOperation` exception.
 
-    This may be resolved in a future version of Django containing an asynchronous ORM.
+    This compatibility may be resolved in a future version of Django containing an asynchronous ORM. However, it is still best practice to always perform ORM calls in the background via `use_query`.
 
-??? question "Why does the example `get_items` function return a `Model` or `QuerySet`?"
+??? question "Can this hook be used for things other than the Django ORM?"
 
-    This was a technical design decision to [based on Apollo](https://www.apollographql.com/docs/react/data/mutations/#usemutation-api), but ultimately helps avoid Django's `SynchronousOnlyOperation` exceptions.
+    If you...
 
-    The `use_query` hook ensures the provided `Model` or `QuerySet` executes all [deferred](https://docs.djangoproject.com/en/dev/ref/models/instances/#django.db.models.Model.get_deferred_fields)/[lazy queries](https://docs.djangoproject.com/en/dev/topics/db/queries/#querysets-are-lazy) safely prior to reaching your components.
+    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 `postprocessor` parameter in `QueryOptions`.
+
+    ```python
+    from django_idom.types import QueryOptions
+    from django_idom.hooks import use_query
+
+    def io_intensive_operation():
+        """This is an example function call that does something IO intensive, but can
+        potentially fail to execute."""
+        ...
+
+    @component
+    def todo_list():
+        query = use_query(
+            io_intensive_operation,
+            QueryOptions(
+                # By setting the postprocessor to a function that takes one argument
+                # and returns None, we can disable postprocessing behavior.
+                postprocessor=lambda data: None,
+            ),
+        )
+
+        if query.loading or query.error:
+            return None
+
+        return str(query.data)
+    ```
+
+??? question "Can this hook automatically fetch `ManyToMany` fields or `ForeignKey` relationships?"
+
+    By default, automatic recursive fetching of `ManyToMany` or `ForeignKey` fields is disabled for performance reasons.
+
+    If you wish you enable this feature, you can modify the `postprocessor_kwargs` parameter in `QueryOptions`.
 
-??? question "What is an "ORM"?"
+    ```python
+    from example_project.my_app.models import MyModel
+    from django_idom.types import QueryOptions
+    from django_idom.hooks import use_query
+
+    def model_with_relationships():
+        """This is an example function that gets `MyModel` that has a ManyToMany field, and
+        additionally other models that have formed a ForeignKey association to `MyModel`.
+
+        ManyToMany Field: `many_to_many_field`
+        ForeignKey Field: `foreign_key_field_set`
+        """
+        return MyModel.objects.get(id=1)
+
+    @component
+    def todo_list():
+        query = use_query(
+            io_intensive_operation,
+            QueryOptions(postprocessor_kwargs={"many_to_many": True, "many_to_one": True}),
+        )
+
+        if query.loading or query.error:
+            return None
+
+        return f"{query.data.many_to_many_field} {query.data.foriegn_key_field_set}"
+    ```
 
-    A Python **Object Relational Mapper** is an API for your code to access a database.
+    Please note that due Django's ORM design, the field name to access foreign keys is [always be postfixed with `_set`](https://docs.djangoproject.com/en/dev/topics/db/examples/many_to_one/).
 
-    See the [Django ORM documentation](https://docs.djangoproject.com/en/dev/topics/db/queries/) for more information.
+??? question "Why does the example `get_items` function return a `Model` or `QuerySet`?"
+
+    This was a technical design decision to [based on Apollo](https://www.apollographql.com/docs/react/data/mutations/#usemutation-api), but ultimately helps avoid Django's `SynchronousOnlyOperation` exceptions.
+
+    The `use_query` hook ensures the provided `Model` or `QuerySet` executes all [deferred](https://docs.djangoproject.com/en/dev/ref/models/instances/#django.db.models.Model.get_deferred_fields)/[lazy queries](https://docs.djangoproject.com/en/dev/topics/db/queries/#querysets-are-lazy) safely prior to reaching your components.
 
 ## Use Mutation
 
@@ -244,12 +309,6 @@ The function you provide into this hook will have no return value.
 
     However, even when resolved it is best practice to perform ORM queries within the `use_query` in order to handle `loading` and `error` states.
 
-??? question "What is an "ORM"?"
-
-    A Python **Object Relational Mapper** is an API for your code to access a database.
-
-    See the [Django ORM documentation](https://docs.djangoproject.com/en/dev/topics/db/queries/) for more information.
-
 ## Use Websocket
 
 You can fetch the Django Channels [websocket](https://channels.readthedocs.io/en/stable/topics/consumers.html#asyncjsonwebsocketconsumer) at any time by using `use_websocket`.

src/django_idom/hooks.py

@@ -112,7 +112,7 @@ def use_query(
 
     Args:
         query: A callable that returns a Django `Model` or `QuerySet`.
-        options: An optional `QueryOptions` object that can modify how the query is excuted.
+        options: An optional `QueryOptions` object that can modify how the query is executed.
         *args: Positional arguments to pass into `query`.
 
     Keyword Args:
@@ -159,11 +159,11 @@ def execute_query() -> None:
 
             # Use a custom postprocessor, if provided
             if query_options.postprocessor:
-                query_options.postprocessor(data, **query_options.postprocessor_options)
+                query_options.postprocessor(data, **query_options.postprocessor_kwargs)
 
             # Use the default postprocessor
             else:
-                _postprocess_django_query(data, **query_options.postprocessor_options)
+                postprocess_django_query(data, **query_options.postprocessor_kwargs)
         except Exception as e:
             set_data(None)
             set_loading(False)
@@ -235,7 +235,7 @@ def reset() -> None:
     return Mutation(call, loading, error, reset)
 
 
-def _postprocess_django_query(
+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.
@@ -246,7 +246,7 @@ def _postprocess_django_query(
     # https://github.com/typeddjango/django-stubs/issues/704
     if isinstance(data, QuerySet):  # type: ignore[misc]
         for model in data:
-            _postprocess_django_query(
+            postprocess_django_query(
                 model,
                 many_to_many=many_to_many,
                 many_to_one=many_to_one,
@@ -266,7 +266,7 @@ def _postprocess_django_query(
 
             elif many_to_many and isinstance(field, ManyToManyField):
                 prefetch_fields.append(field.name)
-                _postprocess_django_query(
+                postprocess_django_query(
                     getattr(data, field.name).get_queryset(),
                     many_to_many=many_to_many,
                     many_to_one=many_to_one,

src/django_idom/types.py

@@ -72,16 +72,14 @@ def __call__(self, data: Any, **kwargs: Any) -> None:
 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: 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.
 
     This default Django query postprocessor prevents Django's lazy query execution, and
-    additionally can be configured via `postprocessor_options` to recursively fetch
+    additionally can be configured via `postprocessor_kwargs` to recursively fetch
     `many_to_many` and `many_to_one` fields."""
+
+    postprocessor_kwargs: dict[str, Any] = field(default_factory=lambda: {})
+    """Keyworded arguments directly passed into the `postprocessor` for configuration."""

tests/test_app/components.py

@@ -185,7 +185,7 @@ def get_foriegn_child_query():
 def relational_query():
     relational_parent = use_query(
         get_relational_parent_query,
-        QueryOptions(postprocessor_options={"many_to_many": True, "many_to_one": True}),
+        QueryOptions(postprocessor_kwargs={"many_to_many": True, "many_to_one": True}),
     )
     foriegn_child = use_query(get_foriegn_child_query)