You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/includes/orm.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,6 @@ These `#!python SynchronousOnlyOperation` exceptions may be removed in a future
8
8
9
9
<!--orm-fetch-start-->
10
10
11
-
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.
11
+
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.
Copy file name to clipboardExpand all lines: docs/src/reference/hooks.md
+23-25
Original file line number
Diff line number
Diff line change
@@ -44,20 +44,21 @@ Query functions can be sync or async.
44
44
45
45
| Name | Type | Description | Default |
46
46
| --- | --- | --- | --- |
47
-
| `#!python options` | `#!python QueryOptions | None` | An optional `#!python QueryOptions` object that can modify how the query is executed. | `#!python None` |
48
-
| `#!python query` | `#!python Callable[_Params, _Result | None]` | A callable that returns a Django `#!python Model` or `#!python QuerySet`. | N/A |
49
-
| `#!python *args` | `#!python _Params.args` | Positional arguments to pass into `#!python query`. | N/A |
50
-
| `#!python **kwargs` | `#!python _Params.kwargs` | Keyword arguments to pass into `#!python query`. | N/A |
47
+
| `#!python query` | `#!python Callable[FuncParams, Awaitable[Inferred]] | Callable[FuncParams, Inferred]` | A function that executes a query and returns some data. | N/A |
48
+
| `#!python kwargs` | `#!python dict[str, Any] | None` | Keyword arguments to passed into the `#!python query` function. | `#!python None` |
49
+
| `#!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` |
50
+
| `#!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 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. |
57
+
| `#!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. |
57
58
58
59
??? question "How can I provide arguments to my query function?"
59
60
60
-
`#!python *args` and `#!python **kwargs` can be provided to your query function via `#!python use_query` parameters.
61
+
`#!python kwargs` can be provided to your query function via the `#!python kwargs=...` parameter.
61
62
62
63
=== "components.py"
63
64
@@ -67,15 +68,15 @@ Query functions can be sync or async.
67
68
68
69
??? question "How can I customize this hook's behavior?"
69
70
70
-
This hook accepts a `#!python options: QueryOptions` parameter that can be used to customize behavior.
71
+
This hook has several parameters that can be used to customize behavior.
71
72
72
-
Below are the settings that can be modified via these `#!python QueryOptions`.
73
+
Below are examples of values that can be modified.
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.
79
+
Whether to run your synchronous query function in threadsensitive mode. Threadsensitive 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.
79
80
80
81
This setting only applies to sync query functions, and will be ignored for async functions.
81
82
@@ -96,19 +97,15 @@ Query functions can be sync or async.
96
97
1. Want to use this hook to defer IO intensive tasks to be computed in the background
97
98
2. Want to to utilize `#!python use_query` with a different ORM
98
99
99
-
... 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.
100
+
... 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.
100
101
101
102
=== "components.py"
102
103
103
104
```python
104
105
{% include "../../examples/python/use-query-postprocessor-disable.py" %}
105
106
```
106
107
107
-
If you wish to create a custom `#!python postprocessor`, you will need to create a callable.
108
-
109
-
The first argument of `#!python postprocessor` must be the query `#!python data`. All proceeding arguments
110
-
are optional `#!python postprocessor_kwargs` (see below). This `#!python postprocessor` must return
111
-
the modified `#!python data`.
108
+
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`.
112
109
113
110
=== "components.py"
114
111
@@ -124,7 +121,7 @@ Query functions can be sync or async.
124
121
125
122
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.
126
123
127
-
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.
124
+
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.
128
125
129
126
=== "components.py"
130
127
@@ -140,7 +137,7 @@ Query functions can be sync or async.
140
137
141
138
??? question "Can I make a failed query try again?"
142
139
143
-
Yes, a `#!python use_mutation` can be re-performed by calling `#!python reset()` on your `#!python use_mutation` instance.
140
+
Yes, `#!python use_mutation` can be re-executed by calling `#!python reset()` on your `#!python use_mutation` instance.
144
141
145
142
For example, take a look at `#!python reset_event` below.
146
143
@@ -190,14 +187,15 @@ Mutation functions can be sync or async.
190
187
191
188
| Name | Type | Description | Default |
192
189
| --- | --- | --- | --- |
193
-
| `#!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 |
194
-
| `#!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` |
190
+
| `#!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 |
191
+
| `#!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` |
192
+
| `#!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` |
195
193
196
194
<font size="4">**Returns**</font>
197
195
198
196
| Type | Description |
199
197
| --- | --- |
200
-
| `#!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. |
198
+
| `#!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. |
201
199
202
200
??? question "How can I provide arguments to my mutation function?"
203
201
@@ -211,15 +209,15 @@ Mutation functions can be sync or async.
211
209
212
210
??? question "How can I customize this hook's behavior?"
213
211
214
-
This hook accepts a `#!python options: MutationOptions` parameter that can be used to customize behavior.
212
+
This hook has several parameters that can be used to customize behavior.
215
213
216
-
Below are the settings that can be modified via these `#!python MutationOptions`.
214
+
Below are examples of values that can be modified.
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.
220
+
Whether to run your synchronous mutation function in threadsensitive mode. Threadsensitive 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.
223
221
224
222
This setting only applies to sync query functions, and will be ignored for async functions.
225
223
@@ -235,7 +233,7 @@ Mutation functions can be sync or async.
235
233
236
234
??? question "Can I make a failed mutation try again?"
237
235
238
-
Yes, a `#!python use_mutation` can be re-performed by calling `#!python reset()` on your `#!python use_mutation` instance.
236
+
Yes, `#!python use_mutation` can be re-executed by calling `#!python reset()` on your `#!python use_mutation` instance.
239
237
240
238
For example, take a look at `#!python reset_event` below.
241
239
@@ -257,7 +255,7 @@ Mutation functions can be sync or async.
257
255
258
256
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.
259
257
260
-
Please note that `refetch` will cause all `#!python use_query` hooks that use `#!python get_items` in the current component tree will be refetched.
258
+
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.
0 commit comments