refactor to remove query & mutation options

Author: Archmonger

docs/examples/python/django-query-postprocessor.py

@@ -1,7 +1,6 @@
 from example.models import TodoItem
 from reactpy import component
 from reactpy_django.hooks import use_query
-from reactpy_django.types import QueryOptions
 from reactpy_django.utils import django_query_postprocessor
 
 
@@ -11,13 +10,11 @@ def get_items():
 
 @component
 def todo_list():
-    # These `QueryOptions` are functionally equivalent to ReactPy-Django's default values
+    # These postprocessor options are functionally equivalent to ReactPy-Django's default values
     item_query = use_query(
-        QueryOptions(
-            postprocessor=django_query_postprocessor,
-            postprocessor_kwargs={"many_to_many": True, "many_to_one": True},
-        ),
         get_items,
+        postprocessor=django_query_postprocessor,
+        postprocessor_kwargs={"many_to_many": True, "many_to_one": True},
     )
 
     return item_query.data

docs/examples/python/use-mutation-thread-sensitive.py

@@ -1,6 +1,5 @@
 from reactpy import component, html
 from reactpy_django.hooks import use_mutation
-from reactpy_django.types import MutationOptions
 
 
 def execute_thread_safe_mutation(text):
@@ -11,8 +10,8 @@ def execute_thread_safe_mutation(text):
 @component
 def my_component():
     item_mutation = use_mutation(
-        MutationOptions(thread_sensitive=False),
         execute_thread_safe_mutation,
+        thread_sensitive=False,
     )
 
     def submit_event(event):

docs/examples/python/use-query-args.py

@@ -2,16 +2,11 @@
 from reactpy_django.hooks import use_query
 
 
-def example_query(value: int, other_value: bool = False):
-    ...
+def example_query(value: int, other_value: bool = False): ...
 
 
 @component
 def my_component():
-    query = use_query(
-        example_query,
-        123,
-        other_value=True,
-    )
+    query = use_query(example_query, kwargs={"value": 123, "other_value": True})
 
     return str(query.data)

docs/examples/python/use-query-postprocessor-change.py

@@ -1,6 +1,5 @@
 from reactpy import component
 from reactpy_django.hooks import use_query
-from reactpy_django.types import QueryOptions
 
 
 def my_postprocessor(data, example_kwarg=True):
@@ -18,11 +17,9 @@ def execute_io_intensive_operation():
 @component
 def my_component():
     query = use_query(
-        QueryOptions(
-            postprocessor=my_postprocessor,
-            postprocessor_kwargs={"example_kwarg": False},
-        ),
         execute_io_intensive_operation,
+        postprocessor=my_postprocessor,
+        postprocessor_kwargs={"example_kwarg": False},
     )
 
     if query.loading or query.error:

docs/examples/python/use-query-postprocessor-disable.py

@@ -1,6 +1,5 @@
 from reactpy import component
 from reactpy_django.hooks import use_query
-from reactpy_django.types import QueryOptions
 
 
 def execute_io_intensive_operation():
@@ -11,8 +10,8 @@ def execute_io_intensive_operation():
 @component
 def my_component():
     query = use_query(
-        QueryOptions(postprocessor=None),
         execute_io_intensive_operation,
+        postprocessor=None,
     )
 
     if query.loading or query.error:

docs/examples/python/use-query-postprocessor-kwargs.py

@@ -1,7 +1,6 @@
 from example.models import TodoItem
 from reactpy import component
 from reactpy_django.hooks import use_query
-from reactpy_django.types import QueryOptions
 
 
 def get_model_with_relationships():
@@ -17,10 +16,8 @@ def get_model_with_relationships():
 @component
 def my_component():
     query = use_query(
-        QueryOptions(
-            postprocessor_kwargs={"many_to_many": False, "many_to_one": False}
-        ),
         get_model_with_relationships,
+        postprocessor_kwargs={"many_to_many": False, "many_to_one": False},
     )
 
     if query.loading or query.error or not query.data:

docs/examples/python/use-query-thread-sensitive.py

@@ -1,6 +1,5 @@
 from reactpy import component
 from reactpy_django.hooks import use_query
-from reactpy_django.types import QueryOptions
 
 
 def execute_thread_safe_operation():
@@ -10,10 +9,7 @@ def execute_thread_safe_operation():
 
 @component
 def my_component():
-    query = use_query(
-        QueryOptions(thread_sensitive=False),
-        execute_thread_safe_operation,
-    )
+    query = use_query(execute_thread_safe_operation, thread_sensitive=False)
 
     if query.loading or query.error:
         return None

src/reactpy_django/hooks.py

@@ -11,7 +11,6 @@
     Sequence,
     Union,
     cast,
-    overload,
 )
 from uuid import uuid4
 
@@ -34,13 +33,11 @@
     FuncParams,
     Inferred,
     Mutation,
-    MutationOptions,
     Query,
-    QueryOptions,
     SyncPostprocessor,
     UserData,
 )
-from reactpy_django.utils import generate_obj_name, get_pk
+from reactpy_django.utils import django_query_postprocessor, generate_obj_name, get_pk
 
 if TYPE_CHECKING:
     from channels_redis.core import RedisChannelLayer
@@ -106,19 +103,19 @@ def use_connection() -> ConnectionType:
 
 def use_query(
     query: Callable[FuncParams, Awaitable[Inferred]] | Callable[FuncParams, Inferred],
-    /,
-    *args: FuncParams.args,
+    *,
+    kwargs: dict[str, Any] | None = None,
     thread_sensitive: bool = True,
-    postprocessor: AsyncPostprocessor | SyncPostprocessor | None = None,
+    postprocessor: (
+        AsyncPostprocessor | SyncPostprocessor | None
+    ) = django_query_postprocessor,
     postprocessor_kwargs: dict[str, Any] | None = None,
-    **kwargs: FuncParams.kwargs,
 ) -> Query[Inferred]:
     """This hook is used to execute functions in the background and return the result, \
         typically to read data the Django ORM.
 
     Args:
         query: A callable that returns a Django `Model` or `QuerySet`.
-        args: Positional arguments to passed into the `query` function.
         kwargs: Keyword arguments to passed into the `query` function.
         thread_sensitive: Whether to run the query in thread-sensitive mode. \
             This setting only applies to sync query functions.
@@ -131,13 +128,20 @@ def use_query(
             is used to prevent Django's lazy query execution and supports `many_to_many` \
             and `many_to_one` as `postprocessor_kwargs`.
         postprocessor_kwargs: Keyworded arguments passed into the `postprocessor` function.
+
+    Returns:
+        A `Query` object containing the query result, loading state, error state, and a `refetch` \
+        function to re-execute the query.
     """
 
     should_execute, set_should_execute = use_state(True)
     data, set_data = use_state(cast(Inferred, None))
     loading, set_loading = use_state(True)
     error, set_error = use_state(cast(Union[Exception, None], None))
     query_ref = use_ref(query)
+    kwargs = kwargs or {}
+    postprocessor_kwargs = postprocessor_kwargs or {}
+
     if query_ref.current is not query:
         raise ValueError(f"Query function changed from {query_ref.current} to {query}.")
 
@@ -146,12 +150,12 @@ async def execute_query() -> None:
         try:
             # Run the query
             if asyncio.iscoroutinefunction(query):
-                new_data = await query(*args, **kwargs)
+                new_data = await query(**kwargs)
             else:
                 new_data = await database_sync_to_async(
                     query,
                     thread_sensitive=thread_sensitive,
-                )(*args, **kwargs)
+                )(**kwargs)
 
             # Run the postprocessor
             if postprocessor:
@@ -202,15 +206,15 @@ def register_refetch_callback() -> Callable[[], None]:
         _REFETCH_CALLBACKS[query].add(refetch)
         return lambda: _REFETCH_CALLBACKS[query].remove(refetch)
 
-    # The query's user API
+    # Return Query user API
     return Query(data, loading, error, refetch)
 
 
 def use_mutation(
     mutation: (
         Callable[FuncParams, bool | None] | Callable[FuncParams, Awaitable[bool | None]]
     ),
-    /,
+    *,
     thread_sensitive: bool = True,
     refetch: Callable[..., Any] | Sequence[Callable[..., Any]] | None = None,
 ) -> Mutation[FuncParams]:
@@ -230,6 +234,10 @@ def use_mutation(
             hook) or a sequence of query functions that need a `refetch` if the \
             mutation succeeds. This is useful for refreshing data after a mutation \
             has been performed.
+
+    Returns:
+        A `Mutation` object that can be called to execute the mutation. This object \
+        also contains loading state, error state, and a `reset` function.
     """
 
     loading, set_loading = use_state(False)
@@ -287,7 +295,7 @@ def reset() -> None:
         set_loading(False)
         set_error(None)
 
-    # The mutation's user API
+    # Return mutation user API
     return Mutation(schedule_mutation, loading, error, reset)
 
 
@@ -331,11 +339,13 @@ async def _set_user_data(data: dict):
         await model.asave()
 
     query: Query[dict | None] = use_query(
-        QueryOptions(postprocessor=None),
         _get_user_data,
-        user=user,
-        default_data=default_data,
-        save_default_data=save_default_data,
+        kwargs={
+            "user": user,
+            "default_data": default_data,
+            "save_default_data": save_default_data,
+        },
+        postprocessor=None,
     )
     mutation = use_mutation(_set_user_data, refetch=_get_user_data)
 

src/reactpy_django/utils.py

@@ -262,7 +262,7 @@ def django_query_postprocessor(
 ) -> QuerySet | Model:
     """Recursively fetch all fields within a `Model` or `QuerySet` to ensure they are not performed lazily.
 
-    Behaviors can be modified through `QueryOptions` within your `use_query` hook.
+    Behavior can be modified through `postprocessor_kwargs` within your `use_query` hook.
 
     Args:
         data: The `Model` or `QuerySet` to recursively fetch fields from.
@@ -275,8 +275,7 @@ def django_query_postprocessor(
         The `Model` or `QuerySet` with all fields fetched.
     """
 
-    # `QuerySet`, which is an iterable of `Model`/`QuerySet` instances
-    # https://github.com/typeddjango/django-stubs/issues/704
+    # `QuerySet`, which is an iterable containing `Model`/`QuerySet` objects.
     if isinstance(data, QuerySet):
         for model in data:
             django_query_postprocessor(
@@ -314,7 +313,7 @@ def django_query_postprocessor(
             "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 non-ORM data.\n\n"
-            "If these situations seem correct, you may want to consider disabling the postprocessor via `QueryOptions`."
+            "If these situations seem correct, you may want to consider disabling the postprocessor."
         )
 
     return data

tests/test_app/components.py

@@ -10,7 +10,6 @@
 from django.shortcuts import render
 from reactpy import component, hooks, html, web
 from reactpy_django.components import view_to_component, view_to_iframe
-from reactpy_django.types import QueryOptions
 
 from test_app.models import (
     AsyncForiegnChild,
@@ -659,7 +658,7 @@ def custom_host(number=0):
 @component
 def broken_postprocessor_query():
     relational_parent = reactpy_django.hooks.use_query(
-        QueryOptions(postprocessor=None), get_relational_parent_query
+        get_relational_parent_query, postprocessor=None
     )
 
     if not relational_parent.data:
@@ -720,9 +719,9 @@ async def on_submit(event):
             "data-fetch-error": bool(user_data_query.error),
             "data-mutation-error": bool(user_data_mutation.error),
             "data-loading": user_data_query.loading or user_data_mutation.loading,
-            "data-username": "AnonymousUser"
-            if current_user.is_anonymous
-            else current_user.username,
+            "data-username": (
+                "AnonymousUser" if current_user.is_anonymous else current_user.username
+            ),
         },
         html.div("use_user_data"),
         html.button({"class": "login-1", "on_click": login_user1}, "Login 1"),
@@ -788,9 +787,9 @@ async def on_submit(event):
             "data-fetch-error": bool(user_data_query.error),
             "data-mutation-error": bool(user_data_mutation.error),
             "data-loading": user_data_query.loading or user_data_mutation.loading,
-            "data-username": "AnonymousUser"
-            if current_user.is_anonymous
-            else current_user.username,
+            "data-username": (
+                "AnonymousUser" if current_user.is_anonymous else current_user.username
+            ),
         },
         html.div("use_user_data_with_default"),
         html.button({"class": "login-3", "on_click": login_user3}, "Login 3"),