documentation for new changes

Author: Archmonger

CHANGELOG.md

@@ -34,7 +34,21 @@ Using the following categories, list your changes in this order:
 
 ## [Unreleased]
 
--   Nothing (yet)!
+### Changed
+
+-   New syntax for `use_query` and `use_mutation` hooks. Here's a quick comparison of the changes:
+
+    ```python
+    query = use_query(QueryOptions(thread_sensitive=True), get_items, value=123456, foo="bar") # Old
+    query = use_query(get_items, {"value":12356, "foo":"bar"}, thread_sensitive=True) # New
+
+    mutation = use_mutation(MutationOptions(thread_sensitive=True), remove_item) # Old
+    mutation = use_mutation(remove_item, thread_sensitive=True) # New
+    ```
+
+### Removed
+
+-   `QueryOptions` and `MutationOptions` have been removed. Their values are now passed direct into the hook.
 
 ## [3.8.1] - 2024-05-07
 

docs/includes/orm.md

@@ -8,6 +8,6 @@ These `#!python SynchronousOnlyOperation` exceptions may be removed in a future
 
 <!--orm-fetch-start-->
 
-By default, automatic recursive fetching of `#!python ManyToMany` or `#!python ForeignKey` fields is enabled within the `django_query_postprocessor`. This is needed to prevent `#!python SynchronousOnlyOperation` exceptions when accessing these fields within your ReactPy components.
+By default, automatic recursive fetching of `#!python ManyToMany` or `#!python ForeignKey` fields is enabled within the `#!python django_query_postprocessor`. This is needed to prevent `#!python SynchronousOnlyOperation` exceptions when accessing these fields within your ReactPy components.
 
 <!--orm-fetch-end-->

docs/src/reference/hooks.md

@@ -44,20 +44,21 @@ Query functions can be sync or async.
 
     | Name | Type | Description | Default |
     | --- | --- | --- | --- |
-    | `#!python options` | `#!python QueryOptions | None` | An optional `#!python QueryOptions` object that can modify how the query is executed. | `#!python None` |
-    | `#!python query` | `#!python Callable[_Params, _Result | None]` | A callable that returns a Django `#!python Model` or `#!python QuerySet`. | N/A |
-    | `#!python *args` | `#!python _Params.args` | Positional arguments to pass into `#!python query`. | N/A |
-    | `#!python **kwargs` | `#!python _Params.kwargs` | Keyword arguments to pass into `#!python query`. | N/A |
+    | `#!python query` | `#!python Callable[FuncParams, Awaitable[Inferred]] | Callable[FuncParams, Inferred]` | A function that executes a query and returns some data. | N/A |
+    | `#!python kwargs` | `#!python dict[str, Any] | None` | Keyword arguments to passed into the `#!python query` function. | `#!python None` |
+    | `#!python thread_sensitive` | `#!python bool` | Whether to run your query function in thread sensitive mode. This mode only applies to sync query functions, and is turned on by default due to Django ORM limitations. | `#!python True` |
+    | `#!python postprocessor` | `#!python AsyncPostprocessor | SyncPostprocessor | None` | A callable that processes the query `#!python data` before it is returned. The first argument of postprocessor function must be the query `#!python data`. All proceeding arguments are optional `#!python postprocessor_kwargs`. This postprocessor function must return the modified `#!python data`. | `#!python None` |
+    | `#!python postprocessor_kwargs` | `#!python dict[str, Any] | None` | Keyworded arguments passed into the `#!python postprocessor` function. | `#!python None` |
 
     <font size="4">**Returns**</font>
 
     | Type | Description |
     | --- | --- |
-    | `#!python Query[_Result | None]` | An object containing `#!python loading`/`#!python error` states, your `#!python data` (if the query has successfully executed), and a `#!python refetch` callable that can be used to re-run the query. |
+    | `#!python Query[Inferred]` | An object containing `#!python loading`/`#!python error` states, your `#!python data` (if the query has successfully executed), and a `#!python refetch` callable that can be used to re-run the query. |
 
 ??? question "How can I provide arguments to my query function?"
 
-    `#!python *args` and `#!python **kwargs` can be provided to your query function via `#!python use_query` parameters.
+    `#!python kwargs` can be provided to your query function via the `#!python kwargs=...` parameter.
 
     === "components.py"
 
@@ -67,15 +68,15 @@ Query functions can be sync or async.
 
 ??? question "How can I customize this hook's behavior?"
 
-    This hook accepts a `#!python options: QueryOptions` parameter that can be used to customize behavior.
+    This hook has several parameters that can be used to customize behavior.
 
-    Below are the settings that can be modified via these `#!python QueryOptions`.
+    Below are examples of values that can be modified.
 
     ---
 
     <font size="4">**`#!python thread_sensitive`**</font>
 
-    Whether to run your synchronous query function in thread-sensitive mode. Thread-sensitive mode is turned on by default due to Django ORM limitations. See Django's [`sync_to_async` docs](https://docs.djangoproject.com/en/dev/topics/async/#sync-to-async) docs for more information.
+    Whether to run your synchronous query function in thread sensitive mode. Thread sensitive mode is turned on by default due to Django ORM limitations. See Django's [`sync_to_async` docs](https://docs.djangoproject.com/en/dev/topics/async/#sync-to-async) docs for more information.
 
     This setting only applies to sync query functions, and will be ignored for async functions.
 
@@ -96,19 +97,15 @@ Query functions can be sync or async.
     1. Want to use this hook to defer IO intensive tasks to be computed in the background
     2. Want to to utilize `#!python use_query` with a different ORM
 
-    ... then you can either set a custom `#!python postprocessor`, or disable all postprocessing behavior by modifying the `#!python QueryOptions.postprocessor` parameter. In the example below, we will set the `#!python postprocessor` to `#!python None` to disable postprocessing behavior.
+    ... then you can either set a custom `#!python postprocessor`, or disable all postprocessing behavior by modifying the `#!python postprocessor=...` parameter. In the example below, we will set the `#!python postprocessor` to `#!python None` to disable postprocessing behavior.
 
     === "components.py"
 
         ```python
         {% include "../../examples/python/use-query-postprocessor-disable.py" %}
         ```
 
-    If you wish to create a custom `#!python postprocessor`, you will need to create a callable.
-
-    The first argument of `#!python postprocessor` must be the query `#!python data`. All proceeding arguments
-    are optional `#!python postprocessor_kwargs` (see below). This `#!python postprocessor` must return
-    the modified `#!python data`.
+    If you wish to create a custom `#!python postprocessor`, you will need to create a function where the first must be the query `#!python data`. All proceeding arguments are optional `#!python postprocessor_kwargs` (see below). This `#!python postprocessor` function must return the modified `#!python data`.
 
     === "components.py"
 
@@ -124,7 +121,7 @@ Query functions can be sync or async.
 
     However, if you have deep nested trees of relational data, this may not be a desirable behavior. In these scenarios, you may prefer to manually fetch these relational fields using a second `#!python use_query` hook.
 
-    You can disable the prefetching behavior of the default `#!python postprocessor` (located at `#!python reactpy_django.utils.django_query_postprocessor`) via the `#!python QueryOptions.postprocessor_kwargs` parameter.
+    You can disable the prefetching behavior of the default `#!python postprocessor` (located at `#!python reactpy_django.utils.django_query_postprocessor`) via the `#!python postprocessor_kwargs=...` parameter.
 
     === "components.py"
 
@@ -140,7 +137,7 @@ Query functions can be sync or async.
 
 ??? question "Can I make a failed query try again?"
 
-    Yes, a `#!python use_mutation` can be re-performed by calling `#!python reset()` on your `#!python use_mutation` instance.
+    Yes, `#!python use_mutation` can be re-executed by calling `#!python reset()` on your `#!python use_mutation` instance.
 
     For example, take a look at `#!python reset_event` below.
 
@@ -190,14 +187,15 @@ Mutation functions can be sync or async.
 
     | Name | Type | Description | Default |
     | --- | --- | --- | --- |
-    | `#!python mutation` | `#!python Callable[_Params, bool | None]` | A callable that performs Django ORM create, update, or delete functionality. If this function returns `#!python False`, then your `#!python refetch` function will not be used. | N/A |
-    | `#!python refetch` | `#!python Callable[..., Any] | Sequence[Callable[..., Any]] | None` | A query function (the function you provide to your `#!python use_query` 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. | `#!python None` |
+    | `#!python mutation` | `#!python Callable[FuncParams, bool | None] | Callable[FuncParams, Awaitable[bool | None]]` | A callable that performs Django ORM create, update, or delete functionality. If this function returns `#!python False`, then your `#!python refetch` function will not be used. | N/A |
+    | `#!python thread_sensitive` | `#!python bool` | Whether to run the mutation in thread sensitive mode. This mode only applies to sync mutation functions, and is turned on by default due to Django ORM limitations. | `#!python True` |
+    | `#!python refetch` | `#!python Callable[..., Any] | Sequence[Callable[..., Any]] | None` | A query function (the function you provide to your `#!python use_query` hook) or a sequence of query functions that need a `#!python refetch` if the mutation succeeds. This is useful for refreshing data after a mutation has been performed. | `#!python None` |
 
     <font size="4">**Returns**</font>
 
     | Type | Description |
     | --- | --- |
-    | `#!python Mutation[_Params]` | An object containing `#!python loading`/`#!python error` states, a `#!python reset` callable that will set `#!python loading`/`#!python error` states to defaults, and a `#!python execute` callable that will run the query. |
+    | `#!python Mutation[FuncParams]` | An object containing `#!python loading`/`#!python error` states, and a `#!python reset` callable that will set `#!python loading`/`#!python error` states to defaults. This object can be called to run the query. |
 
 ??? question "How can I provide arguments to my mutation function?"
 
@@ -211,15 +209,15 @@ Mutation functions can be sync or async.
 
 ??? question "How can I customize this hook's behavior?"
 
-    This hook accepts a `#!python options: MutationOptions` parameter that can be used to customize behavior.
+    This hook has several parameters that can be used to customize behavior.
 
-    Below are the settings that can be modified via these `#!python MutationOptions`.
+    Below are examples of values that can be modified.
 
     ---
 
     <font size="4">**`#!python thread_sensitive`**</font>
 
-    Whether to run your synchronous mutation function in thread-sensitive mode. Thread-sensitive mode is turned on by default due to Django ORM limitations. See Django's [`sync_to_async` docs](https://docs.djangoproject.com/en/dev/topics/async/#sync-to-async) docs for more information.
+    Whether to run your synchronous mutation function in thread sensitive mode. Thread sensitive mode is turned on by default due to Django ORM limitations. See Django's [`sync_to_async` docs](https://docs.djangoproject.com/en/dev/topics/async/#sync-to-async) docs for more information.
 
     This setting only applies to sync query functions, and will be ignored for async functions.
 
@@ -235,7 +233,7 @@ Mutation functions can be sync or async.
 
 ??? question "Can I make a failed mutation try again?"
 
-    Yes, a `#!python use_mutation` can be re-performed by calling `#!python reset()` on your `#!python use_mutation` instance.
+    Yes, `#!python use_mutation` can be re-executed by calling `#!python reset()` on your `#!python use_mutation` instance.
 
     For example, take a look at `#!python reset_event` below.
 
@@ -257,7 +255,7 @@ Mutation functions can be sync or async.
 
     The example below is a merge of the `#!python use_query` and `#!python use_mutation` examples above with the addition of a `#!python use_mutation(refetch=...)` argument.
 
-    Please note that `refetch` will cause all `#!python use_query` hooks that use `#!python get_items` in the current component tree will be refetched.
+    Please note that `#!python refetch` will cause all `#!python use_query` hooks that use `#!python get_items` in the current component tree will be refetched.
 
     === "components.py"
 

src/reactpy_django/hooks.py

@@ -50,7 +50,6 @@
 )
 
 
-# TODO: Deprecate this once the equivalent hook gets moved to reactpy.hooks.*
 def use_location() -> Location:
     """Get the current route as a `Location` object"""
     return _use_location()
@@ -84,7 +83,6 @@ def use_origin() -> str | None:
     return None
 
 
-# TODO: Deprecate this once the equivalent hook gets moved to reactpy.hooks.*
 def use_scope() -> dict[str, Any]:
     """Get the current ASGI scope dictionary"""
     scope = _use_scope()
@@ -95,7 +93,6 @@ def use_scope() -> dict[str, Any]:
     raise TypeError(f"Expected scope to be a dict, got {type(scope)}")
 
 
-# TODO: Deprecate this once the equivalent hook gets moved to reactpy.hooks.*
 def use_connection() -> ConnectionType:
     """Get the current `Connection` object"""
     return _use_connection()
@@ -115,25 +112,26 @@ def use_query(
         typically to read data the Django ORM.
 
     Args:
-        query: A callable that returns a Django `Model` or `QuerySet`.
+        query: A function that executes a query and returns some data.
 
     Kwargs:
         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.
-        postprocessor: A callable that processes the query result prior to returning it. \
+        thread_sensitive: Whether to run the query in thread sensitive mode. \
+            This mode only applies to sync query functions, and is turned on by default \
+            due to Django ORM limitations.
+        postprocessor: A callable that processes the query `data` before it is returned. \
             The first argument of postprocessor function must be the query `data`. All \
-            proceeding arguments are optional `postprocessor_kwargs` (see below). This \
-            postprocessor function must return the modified `data`. \
+            proceeding arguments are optional `postprocessor_kwargs`. This postprocessor \
+            function must return the modified `data`. \
             \
             If unset, `REACTPY_DEFAULT_QUERY_POSTPROCESSOR` is used. By default, this \
             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.
+         An object containing `loading`/`#!python error` states, your `data` (if the query \
+         has successfully executed), and a `refetch` callable that can be used to re-run the query.
     """
 
     should_execute, set_should_execute = use_state(True)
@@ -231,16 +229,18 @@ def use_mutation(
             function will not be used.
 
     Kwargs:
-        thread_sensitive: Whether to run the mutation in thread-sensitive mode. \
-            This setting only applies to sync mutation functions.
+        thread_sensitive: Whether to run the mutation in thread sensitive mode. \
+            This mode only applies to sync mutation functions, and is turned on by default \
+            due to Django ORM limitations.
         refetch:  A query function (the function you provide to your `use_query` \
             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.
+        An object containing `#!python loading`/`#!python error` states, and a \
+        `#!python reset` callable that will set `#!python loading`/`#!python error` \
+        states to defaults. This object can be called to run the query.
     """
 
     loading, set_loading = use_state(False)