Async ORM mutations and queries (#134)

- Disable `thread_sensitive` where it's not needed
- Perform queries and mutations using async
   -   `use_query` now supports async functions.
   -   `use_mutation` now supports async functions.
   -   `django_idom.types.QueryOptions.thread_sensitive` option to customize how sync queries are executed.
   -   `django_idom.hooks.use_mutation` now accepts `django_idom.types.MutationOptions` option to customize how mutations are executed.
- Use Python's arg/kwarg handlers to properly interpret and differentiate between `kwarg` and `args`. This allow things such as `query=my_function` to be properly handled.
-  The `mutate` argument on `django_idom.hooks.use_mutation` has been renamed to `mutation`.
- Add tests for our database routing feature
- Reduce runtime for tests from ~181 seconds to ~11 seconds by only starting the Django server once
- Fix bug where ReactPy utilizes Django's default cache timeout, which can prematurely expire our cache entries.

Author: Archmonger

Diff for: .gitignore

@@ -8,7 +8,8 @@ logs
 *.pyc
 .dccachea
 __pycache__
-db.sqlite3
+*.sqlite3
+*.sqlite3-journal
 media
 cache
 static-deploy

Diff for: CHANGELOG.md

@@ -34,9 +34,22 @@ Using the following categories, list your changes in this order:
 
 ## [Unreleased]
 
--   Nothing (yet)!
+### Added
+
+-   `use_query` now supports async functions.
+-   `use_mutation` now supports async functions.
+-   `reactpy_django.types.QueryOptions.thread_sensitive` option to customize how sync queries are executed.
+-   `reactpy_django.hooks.use_mutation` now accepts `reactpy_django.types.MutationOptions` option to customize how mutations are executed.
+
+### Changed
+
+-   The `mutate` argument on `reactpy_django.hooks.use_mutation` has been renamed to `mutation`.
+
+### Fixed
+
+-   Fix bug where ReactPy utilizes Django's default cache timeout, which can prematurely expire the component cache.
 
-## [3.0.1] - 2023-03-31
+## [3.0.1] - 2023-04-06
 
 ### Changed
 

Diff for: README.md

@@ -27,7 +27,7 @@
         </td>
         <td>
             <a href="https://github.com/reactive-python/reactpy-django">Django</a>,
-            <a href="https://github.com/idom-team/idom-jupyter">Jupyter</a>,
+            <a href="https://github.com/reactive-python/reactpy-jupyter">Jupyter</a>,
             <a href="https://github.com/idom-team/idom-dash">Plotly-Dash</a>
         </td>
         </tr>

Diff for: docs/python/use-query-async.py

@@ -0,0 +1,23 @@
+from channels.db import database_sync_to_async
+from example.models import TodoItem
+from reactpy import component, html
+
+from reactpy_django.hooks import use_query
+
+
+async def get_items():
+    return await database_sync_to_async(TodoItem.objects.all)()
+
+
+@component
+def todo_list():
+    item_query = use_query(get_items)
+
+    if item_query.loading:
+        rendered_items = html.h2("Loading...")
+    elif item_query.error or not item_query.data:
+        rendered_items = html.h2("Error when loading!")
+    else:
+        rendered_items = html.ul([html.li(item, key=item) for item in item_query.data])
+
+    return html.div("Rendered items: ", rendered_items)

Diff for: docs/python/use-query-postprocessor-change.py

@@ -17,7 +17,7 @@ def execute_io_intensive_operation():
 
 
 @component
-def todo_list():
+def my_component():
     query = use_query(
         QueryOptions(
             postprocessor=my_postprocessor,

Diff for: docs/python/use-query-postprocessor-disable.py

@@ -10,7 +10,7 @@ def execute_io_intensive_operation():
 
 
 @component
-def todo_list():
+def my_component():
     query = use_query(
         QueryOptions(postprocessor=None),
         execute_io_intensive_operation,

Diff for: docs/python/use-query-postprocessor-kwargs.py

@@ -16,7 +16,7 @@ def get_model_with_relationships():
 
 
 @component
-def todo_list():
+def my_component():
     query = use_query(
         QueryOptions(
             postprocessor_kwargs={"many_to_many": False, "many_to_one": False}

Diff for: docs/python/use-query-thread-sensitive.py

@@ -0,0 +1,22 @@
+from reactpy import component
+
+from reactpy_django.hooks import use_query
+from reactpy_django.types import QueryOptions
+
+
+def execute_thread_safe_operation():
+    """This is an example query function that does some thread-safe operation."""
+    pass
+
+
+@component
+def my_component():
+    query = use_query(
+        QueryOptions(thread_sensitive=False),
+        execute_thread_safe_operation,
+    )
+
+    if query.loading or query.error:
+        return None
+
+    return str(query.data)

Diff for: docs/python/use-query.py

@@ -17,6 +17,6 @@ def todo_list():
     elif item_query.error or not item_query.data:
         rendered_items = html.h2("Error when loading!")
     else:
-        rendered_items = html.ul(html.li(item, key=item) for item in item_query.data)
+        rendered_items = html.ul([html.li(item, key=item) for item in item_query.data])
 
     return html.div("Rendered items: ", rendered_items)

Diff for: docs/src/dictionary.txt

@@ -30,6 +30,7 @@ postprocessing
 serializable
 postprocessor
 preprocessor
+middleware
 backends
 backend
 frontend

Diff for: docs/src/features/hooks.md

@@ -57,13 +57,29 @@ The function you provide into this hook must return either a `Model` or `QuerySe
         {% include "../../python/use-query-args.py" %}
         ```
 
-??? question "Why does the example `get_items` function return `TodoItem.objects.all()`?"
+??? question "Why does `get_items` in the example return `TodoItem.objects.all()`?"
 
     This was a technical design decision to based on [Apollo's `useQuery` hook](https://www.apollographql.com/docs/react/data/queries/), 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.
 
-??? question "Can this hook be used for things other than the Django ORM?"
+??? question "How can I use `QueryOptions` to customize fetching behavior?"
+
+    <font size="4">**`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.
+
+    This setting only applies to sync query functions, and will be ignored for async functions.
+
+    === "components.py"
+
+        ```python
+        {% include "../../python/use-query-thread-sensitive.py" %}
+        ```
+
+    ---
+
+    <font size="4">**`postprocessor`**</font>
 
     {% include-markdown "../../includes/orm.md" start="<!--orm-fetch-start-->" end="<!--orm-fetch-end-->" %}
 
@@ -72,7 +88,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 `None` to disable postprocessing behavior.
+    ... then you can either set a custom `postprocessor`, or disable all postprocessing behavior by modifying the `QueryOptions.postprocessor` parameter. In the example below, we will set the `postprocessor` to `None` to disable postprocessing behavior.
 
     === "components.py"
 
@@ -92,7 +108,9 @@ The function you provide into this hook must return either a `Model` or `QuerySe
         {% include "../../python/use-query-postprocessor-change.py" %}
         ```
 
-??? question "How can I prevent this hook from recursively fetching `ManyToMany` fields or `ForeignKey` relationships?"
+    ---
+
+    <font size="4">**`postprocessor_kwargs`**</font>
 
     {% include-markdown "../../includes/orm.md" start="<!--orm-fetch-start-->" end="<!--orm-fetch-end-->" %}
 
@@ -108,6 +126,18 @@ The function you provide into this hook must return either a `Model` or `QuerySe
 
     _Note: In Django's ORM design, the field name to access foreign keys is [postfixed with `_set`](https://docs.djangoproject.com/en/dev/topics/db/examples/many_to_one/) by default._
 
+??? question "Can I define async query functions?"
+
+    Async functions are supported by `use_query`. You can use them in the same way as a sync query function.
+
+    However, be mindful of Django async ORM restrictions.
+
+    === "components.py"
+
+        ```python
+        {% include "../../python/use-query-async.py" %}
+        ```
+
 ??? question "Can I make ORM calls without hooks?"
 
     {% include-markdown "../../includes/orm.md" start="<!--orm-excp-start-->" end="<!--orm-excp-end-->" %}

Diff for: docs/src/get-started/render-view.md renamed to docs/src/get-started/register-view.md

@@ -6,7 +6,7 @@
 
 ---
 
-## Render Your View
+## Register a View
 
 We will assume you have [created a Django View](https://docs.djangoproject.com/en/dev/intro/tutorial01/#write-your-first-view) before, but here's a simple example below.
 
@@ -28,8 +28,6 @@ We will add this new view into your [`urls.py`](https://docs.djangoproject.com/e
     {% include "../../python/example/urls.py" %}
     ```
 
-Now, navigate to `http://127.0.0.1:8000/example/`. If you copy-pasted the component from the previous example, you will now see your component display "Hello World".
-
 ??? question "Which urls.py do I add my views to?"
 
     For simple **Django projects**, you can easily add all of your views directly into the **Django project's** `urls.py`. However, as you start increase your project's complexity you might end up with way too much within one file.

Diff for: docs/src/get-started/run-webserver.md

@@ -0,0 +1,23 @@
+## Overview
+
+!!! summary
+
+    Run a webserver to display your Django view.
+
+---
+
+## Run the Webserver
+
+To test your new Django view, run the following command to start up a development webserver.
+
+```bash linenums="0"
+python manage.py runserver
+```
+
+Now you can navigate to your **Django project** URL that contains an ReactPy component, such as `http://127.0.0.1:8000/example/` (_from the previous step_).
+
+If you copy-pasted our example component, you will now see your component display "Hello World".
+
+??? warning "Do not use `manage.py runserver` for production."
+
+    The webserver contained within `manage.py runserver` is only intended for development and testing purposes. For production deployments make sure to read [Django's documentation](https://docs.djangoproject.com/en/dev/howto/deployment/).

Diff for: mkdocs.yml

@@ -6,7 +6,8 @@ nav:
           - Choose a Django App: get-started/choose-django-app.md
           - Create a Component: get-started/create-component.md
           - Use the Template Tag: get-started/use-template-tag.md
-          - Render Your View: get-started/render-view.md
+          - Register a View: get-started/register-view.md
+          - Run the Webserver: get-started/run-webserver.md
           - Learn More: get-started/learn-more.md
     - Reference:
           - Components: features/components.md

Diff for: noxfile.py

@@ -56,7 +56,7 @@ def test_suite(session: Session) -> None:
         posargs.append("--debug-mode")
 
     session.run("playwright", "install", "chromium")
-    session.run("python", "manage.py", "test", *posargs)
+    session.run("python", "manage.py", "test", *posargs, "-v 2")
 
 
 @nox.session

Diff for: requirements/test-env.txt

@@ -2,3 +2,4 @@ django
 playwright
 twisted
 channels[daphne]>=4.0.0
+tblib

Diff for: src/reactpy_django/config.py

@@ -6,7 +6,11 @@
 from reactpy.config import REACTPY_DEBUG_MODE
 from reactpy.core.types import ComponentConstructor
 
-from reactpy_django.types import Postprocessor, ViewComponentIframe
+from reactpy_django.types import (
+    AsyncPostprocessor,
+    SyncPostprocessor,
+    ViewComponentIframe,
+)
 from reactpy_django.utils import import_dotted_path
 
 
@@ -37,10 +41,12 @@
     "REACTPY_DATABASE",
     DEFAULT_DB_ALIAS,
 )
-REACTPY_DEFAULT_QUERY_POSTPROCESSOR: Postprocessor | None = import_dotted_path(
-    getattr(
-        settings,
-        "REACTPY_DEFAULT_QUERY_POSTPROCESSOR",
-        "reactpy_django.utils.django_query_postprocessor",
+REACTPY_DEFAULT_QUERY_POSTPROCESSOR: AsyncPostprocessor | SyncPostprocessor | None = (
+    import_dotted_path(
+        getattr(
+            settings,
+            "REACTPY_DEFAULT_QUERY_POSTPROCESSOR",
+            "reactpy_django.utils.django_query_postprocessor",
+        )
     )
 )