docs and changelog

Author: Archmonger

CHANGELOG.md

@@ -21,11 +21,16 @@ Don't forget to remove deprecated code on each major release!
 
 ### Added
 
+-   User login/logout features!
+    -   `reactpy_django.hooks.use_auth` to provide **persistent** `login` and `logout` functionality to your components.
+    -   `settings.py:REACTPY_AUTH_TOKEN_TIMEOUT` to control the maximum seconds before ReactPy no longer allows the browser to obtain a persistent login cookie.
+    -   `settings.py:REACTPY_CLEAN_AUTH_TOKENS` to control whether ReactPy should clean up expired authentication tokens during automatic cleanups.
 -   Automatically convert Django forms to ReactPy forms via the new `reactpy_django.components.django_form` component!
+-   The ReactPy component tree can now be forcibly re-rendered via the new `reactpy_django.hooks.use_rerender` hook.
 
 ### Changed
 
--   Refactoring of internal code to improve maintainability. No changes to public/documented API.
+-   Refactoring of internal code to improve maintainability. No changes to publicly documented API.
 
 ## [5.1.1] - 2024-12-02
 

docs/examples/python/use_auth.py

@@ -0,0 +1,23 @@
+from django.contrib.auth import get_user_model
+from reactpy import component, html
+
+from reactpy_django.hooks import use_auth, use_user
+
+
+@component
+def my_component():
+    auth = use_auth()
+    user = use_user()
+
+    async def login_user(event):
+        new_user, _created = await get_user_model().objects.aget_or_create(username="ExampleUser")
+        await auth.login(new_user)
+
+    async def logout_user(event):
+        await auth.logout()
+
+    return html.div(
+        f"Current User: {user}",
+        html.button({"onClick": login_user}, "Login"),
+        html.button({"onClick": logout_user}, "Logout"),
+    )

docs/examples/python/use_rerender.py

@@ -0,0 +1,15 @@
+from uuid import uuid4
+
+from reactpy import component, html
+
+from reactpy_django.hooks import use_rerender
+
+
+@component
+def my_component():
+    rerender = use_rerender()
+
+    def on_click():
+        rerender()
+
+    return html.div(f"UUID: {uuid4()}", html.button({"onClick": on_click}, "Rerender"))

docs/includes/auth-middleware-stack.md

@@ -0,0 +1,3 @@
+```python linenums="0"
+{% include "../examples/python/configure_asgi_middleware.py" start="# start" %}
+```

docs/src/learn/add-reactpy-to-a-django-project.md

@@ -87,9 +87,7 @@ Register ReactPy's WebSocket using `#!python REACTPY_WEBSOCKET_ROUTE` in your [`
 
     In these situations will need to ensure you are using `#!python AuthMiddlewareStack`.
 
-    ```python linenums="0"
-    {% include "../../examples/python/configure_asgi_middleware.py" start="# start" %}
-    ```
+    {% include "../../includes/auth-middleware-stack.md" %}
 
 ??? question "Where is my `asgi.py`?"
 

docs/src/reference/hooks.md

@@ -271,6 +271,83 @@ Mutation functions can be sync or async.
 
 ---
 
+## User Hooks
+
+---
+
+### Use Auth
+
+Provides a `#!python NamedTuple` containing `#!python async login` and `#!python async logout` functions.
+
+This hook utilizes the Django's authentication framework in a way that provides **persistent** authentication across WebSocket and HTTP connections.
+
+=== "components.py"
+
+    ```python
+    {% include "../../examples/python/use_auth.py" %}
+    ```
+
+??? example "See Interface"
+
+    <font size="4">**Parameters**</font>
+
+    `#!python None`
+
+    <font size="4">**Returns**</font>
+
+    | Type | Description |
+    | --- | --- |
+    | `#!python UseAuthTuple` | A named tuple containing `#!python login` and `#!python logout` async functions. |
+
+??? warning "Extra Django configuration required"
+
+    Your ReactPy WebSocket must utilize `#!python AuthMiddlewareStack` in order to use this hook.
+
+    {% include "../../includes/auth-middleware-stack.md" %}
+
+??? question "Why use this instead of `#!python channels.auth.login`?"
+
+    The `#!python channels.auth.*` functions cannot trigger re-renders of your ReactPy components. Additionally, it does not provide persistent authentication when used within ReactPy.
+
+    Django's authentication design requires cookies to retain login status. ReactPy is rendered via WebSockets, and browsers do not allow active WebSocket connections to modify cookies.
+
+    To work around this limitation, when `#!python use_auth().login()` is called within your application, ReactPy performs the following process...
+
+    1. The server authenticates the user into the WebSocket session
+    2. The server generates a temporary login token linked to the WebSocket session
+    3. The server commands the browser to fetch the login token via HTTP
+    4. The client performs the HTTP request
+    5. The server returns the HTTP response, which contains all necessary cookies
+    6. The client stores these cookies in the browser
+
+    This ultimately results in persistent authentication which will be retained even if the browser tab is refreshed.
+
+---
+
+### Use User
+
+Shortcut that returns the WebSocket or HTTP connection's `#!python User`.
+
+=== "components.py"
+
+    ```python
+    {% include "../../examples/python/use_user.py" %}
+    ```
+
+??? example "See Interface"
+
+    <font size="4">**Parameters**</font>
+
+    `#!python None`
+
+    <font size="4">**Returns**</font>
+
+    | Type | Description |
+    | --- | --- |
+    | `#!python AbstractUser` | A Django `#!python User`, which can also be an `#!python AnonymousUser`. |
+
+---
+
 ### Use User Data
 
 Store or retrieve a `#!python dict` containing user data specific to the connection's `#!python User`.
@@ -522,7 +599,7 @@ You can expect this hook to provide strings such as `http://example.com`.
 
 Shortcut that returns the root component's `#!python id` from the WebSocket or HTTP connection.
 
-The root ID is a randomly generated `#!python uuid4`. It is notable to mention that it is persistent across the current connection. The `uuid` is reset when the page is refreshed.
+The root ID is a randomly generated `#!python uuid4`. It is notable to mention that it is persistent across the current connection. The `uuid` is reset only when the page is refreshed.
 
 This is useful when used in combination with [`#!python use_channel_layer`](#use-channel-layer) to send messages to a specific component instance, and/or retain a backlog of messages in case that component is disconnected via `#!python use_channel_layer( ... , group_discard=False)`.
 
@@ -546,14 +623,14 @@ This is useful when used in combination with [`#!python use_channel_layer`](#use
 
 ---
 
-### Use User
+### Use Re-render
 
-Shortcut that returns the WebSocket or HTTP connection's `#!python User`.
+Returns a function that can be used to trigger a re-render of the entire component tree.
 
 === "components.py"
 
     ```python
-    {% include "../../examples/python/use_user.py" %}
+    {% include "../../examples/python/use_rerender.py" %}
     ```
 
 ??? example "See Interface"
@@ -566,4 +643,4 @@ Shortcut that returns the WebSocket or HTTP connection's `#!python User`.
 
     | Type | Description |
     | --- | --- |
-    | `#!python AbstractUser` | A Django `#!python User`, which can also be an `#!python AnonymousUser`. |
+    | `#!python Callable[[], None]` | A function that triggers a re-render of the entire component tree. |

docs/src/reference/settings.md

@@ -6,12 +6,6 @@ These are ReactPy-Django's default settings values. You can modify these values
 
 </p>
 
-!!! abstract "Note"
-
-    The default configuration of ReactPy is suitable for the vast majority of use cases.
-
-    You should only consider changing settings when the necessity arises.
-
 ---
 
 ## General Settings
@@ -60,13 +54,17 @@ This file path must be valid to Django's [template finder](https://docs.djangopr
 
 ---
 
+## Authentication Settings
+
+---
+
 ### `#!python REACTPY_AUTH_BACKEND`
 
 **Default:** `#!python "django.contrib.auth.backends.ModelBackend"`
 
 **Example Value(s):** `#!python "example_project.auth.MyModelBackend"`
 
-Dotted path to the Django authentication backend to use for ReactPy components. This is only needed if:
+Dotted path to the Django authentication backend to use for ReactPy components. This is typically needed if:
 
 1. You are using `#!python settings.py:REACTPY_AUTO_RELOGIN=True` and...
 2. You are using `#!python AuthMiddlewareStack` and...
@@ -75,6 +73,22 @@ Dotted path to the Django authentication backend to use for ReactPy components.
 
 ---
 
+### `#!python REACTPY_AUTH_TOKEN_TIMEOUT`
+
+**Default:** `#!python 30`
+
+**Example Value(s):** `#!python 5`
+
+Maximum seconds before ReactPy no longer allows the browser to obtain a login cookie.
+
+This setting exists because Django's authentication design require cookies to retain login status. ReactPy is rendered via WebSockets, and browsers do not allow active WebSocket connections to modify cookies.
+
+To work around this limitation, this setting provides a maximum validity period of a temporary login token. When `#!python reactpy_django.hooks.use_auth().login()` is called within your application, ReactPy will automatically create this temporary login token and command the browser to fetch it via HTTP.
+
+This setting should be a reasonably low value, but still be high enough to account for a combination of client lag, slow internet, and server response time.
+
+---
+
 ### `#!python REACTPY_AUTO_RELOGIN`
 
 **Default:** `#!python False`
@@ -141,9 +155,9 @@ This setting is incompatible with [`daphne`](https://github.com/django/daphne).
 
 **Example Value(s):** `#!python True`
 
-Configures whether to use an async ReactPy rendering queue. When enabled, large renders will no longer block smaller renders from taking place. Additionally, prevents the rendering queue from being blocked on waiting for async effects to startup/shutdown (which is typically a relatively slow operation).
+Configures whether to use an async ReactPy rendering queue. When enabled, large renders will no longer block smaller renders from taking place. Additionally, prevents the rendering queue from being blocked on waiting for async effects to startup/shutdown (which is a relatively slow operation).
 
-This setting is currently in early release, and currently no effort is made to de-duplicate renders. For example, if parent and child components are scheduled to render at the same time, both renders will take place even though a single render of the parent component would have been sufficient.
+This setting is currently in early release, and currently no effort is made to de-duplicate renders. For example, if parent and child components are scheduled to render at the same time, both renders will take place, even though a single render would have been sufficient.
 
 ---
 
@@ -270,6 +284,16 @@ Configures whether ReactPy should clean up expired component sessions during aut
 
 ---
 
+### `#!python REACTPY_CLEAN_AUTH_TOKENS`
+
+**Default:** `#!python True`
+
+**Example Value(s):** `#!python False`
+
+Configures whether ReactPy should clean up expired authentication tokens during automatic clean up operations.
+
+---
+
 ### `#!python REACTPY_CLEAN_USER_DATA`
 
 **Default:** `#!python True`

docs/src/reference/template-tag.md

@@ -322,7 +322,7 @@ The entire file path provided is loaded directly into the browser, and must have
 
 This template tag configures the current page to be able to run `pyscript`.
 
-You can optionally use this tag to configure the current PyScript environment. For example, you can include a list of Python packages to automatically install within the PyScript environment.
+You can optionally use this tag to configure the current PyScript environment, such as adding dependencies.
 
 === "my_template.html"