The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
settings.py:REACTPY_PRERENDER can be set to True to enable this behavior by default{% component "..." prerender="True" %}reactpy_django.utils.ComponentPreloader to reactpy_django.utils.RootComponentFinder.Suspicious position of 'reactpy_django' in INSTALLED_APPS) has been added.REACTPY_DEFAULT_QUERY_POSTPROCESSOR to None.REACTPY_RECONNECT_INTERVALREACTPY_RECONNECT_MAX_INTERVALREACTPY_RECONNECT_MAX_RETRIESREACTPY_RECONNECT_BACKOFF_MULTIPLIER1.0.2.args/kwargs if settings.py:DEBUG is enabled.@reactpy/client version to 0.3.14.2.settings.py:REACTPY_RECONNECT_MAX is removed. See the docs for the new REACTPY_RECONNECT_* settings.REACTPY_DEFAULT_HOSTS setting can round-robin a list of ReactPy rendering hosts.host argument has been added to the component template tag to force components to render on a specific host.reactpy_django.utils.register_component function can manually register root components.reactpy_django.REACTPY_WEBSOCKET_PATH is deprecated. The identical replacement is REACTPY_WEBSOCKET_ROUTE.settings.py:REACTPY_WEBSOCKET_URL is deprecated. The similar replacement is REACTPY_URL_PREFIX.REACTPY_WEBSOCKET_URL doesn't end with a slash) has been removed. ReactPy now automatically handles slashes.REACTPY_WEBSOCKET_URL doesn't start with an alphanumeric character) has been removed. ReactPy now automatically handles this scenario.channels is not in settings.py:INSTALLED_APPS) has been removed. Newer versions of channels do not require installation via INSTALLED_APPS to receive an ASGI web server.orjson resulting in an ~6% overall performance improvement.asyncio event loops are now patched via nest_asyncio, resulting in an ~10% overall performance improvement. This has no performance impact if you are running your web server with uvloop.REACTPY_WEBSOCKET_URL always generates a warning if unset.assert f is self._write_fut would be raised by uvicorn when REACTPY_BACKHAUL_THREAD = True.daphne when REACTPY_BACKHAUL_THREAD = True.REACTPY_BACKHAUL_THREAD now defaults to False.REACTPY_BACKHAUL_THREAD setting to enable/disable threading behavior.settings.py:REACTPY_DATABASE, reactpy_django.database.Router must now be registered in settings.py:DATABASE_ROUTERS.3.9settings.py:DEBUG is enabled.component template tag from causing the whole template to fail to render.DEBUG mode.REACTPY_AUTH_BACKEND setting to allow for custom authentication backends.SessionMiddlewareStack is now optional.AuthMiddlewareStack is now optional.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.mutate argument on reactpy_django.hooks.use_mutation has been renamed to mutation.django-reactpy database entries are no longer cleaned during Django application startup. Instead, it will occur on webpage loads if REACTPY_RECONNECT_MAX seconds has elapsed since the last cleaning.django-idom has been renamed to reactpy-django! Please note that all references to the word idom in your code should be changed to reactpy. See the docs for more details.This is Django-IDOM's biggest update yet!
To upgrade from previous version you will need to...
django-idom >= 3.0.0idom rewrite-keys <DIR> and idom rewrite-camel-case-props <DIR> to update your idom.html.* calls to the new syntaxpython manage.py migrate to create the new Django-IDOM database entriesidom client will automatically configure itself to debug mode depending on settings.py:DEBUG.use_connection hook for returning the browser's active Connection.IDOM_CACHE is now configurable within settings.py to whatever cache name you wish.manage.py migrate after installing IDOM.idom.html.*...snake_case. For example className now becomes class_name.key=... is now declared within the props dict (rather than as a kwarg).component template tag now supports both positional and keyword arguments.component template tag now supports non-serializable arguments.IDOM_WS_MAX_RECONNECT_TIMEOUT setting has been renamed to IDOM_RECONNECT_MAX.django_idom.hooks.use_websocket has been removed. The similar replacement is django_idom.hooks.use_connection.django_idom.types.IdomWebsocket has been removed. The similar replacement is django_idom.types.Connection.settings.py:CACHE['idom'] is no longer used by default. The name of the cache back-end must now be specified with the IDOM_CACHE setting.view_to_component will now retain the contents of a <head> tag when rendering.production rather than development.use_query will now utilize field.related_name when postprocessing many-to-one relationships.settings.py:DEBUG.use_query would not recursively fetch many-to-one relationships.options: QueryOptions parameter to use_query to allow for configuration of this hook.use_query will recursively prefetch all many-to-many or many-to-one relationships to prevent SynchronousOnlyOperation exceptions.django_idom.hooks._fetch_lazy_fields has been deleted. The equivalent replacement is django_idom.utils.django_query_postprocessor.channels version is now 4.0.0.view_to_component callable to have request argument be optional.view_to_component to represent it as a decorator with parenthesis (such as @view_to_component(compatibility=True))view_to_component when using compatibility=True.key=... parameter on all prefabricated components.use_origin hook for returning the browser's location.origin.view_to_component now returns a Callable, instead of directly returning a Component. Check the docs for new usage info.use_mutation and use_query will now log any query failures.use_mutation to have refetch=None, as the docs suggest is possible.use_query will now prefetch all fields to prevent SynchronousOnlyOperation exceptions.view_to_component, django_css, and django_js type hints will now display like normal functions.auth_required decorator to prevent your components from rendering to unauthenticated users.use_query hook for fetching database values.use_mutation hook for modifying database values.view_to_component utility to convert legacy Django views to IDOM components.playwright instead of seleniumdjango_css and django_js components to defer loading CSS & JS files until needed.use_websocket, use_scope, and use_location are now available within the django_idom.hooks module.idom_component template tag has been renamed to componentwebsocket parameter for components has been removed. Functionally, it is replaced with django_idom.hooks.use_websocket.idom.core.proto caused by IDOM 0.37.2divname = ... parameter to IDOM HTTP paths for use with django.urls.reverse()IdomWebsocketdjango_idom/ parent folder0.36.04.03.8IDOM_WEB_MODULES_PATH has been replaced with Django include(...)IDOM_WS_MAX_RECONNECT_DELAY has been renamed to IDOM_WS_MAX_RECONNECT_TIMEOUTidom_web_modules cache back-end has been renamed to idomThe format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
settings.py:REACTPY_PRERENDER can be set to True to enable this behavior by default{% component "..." prerender="True" %}reactpy_django.utils.ComponentPreloader to reactpy_django.utils.RootComponentFinder.Suspicious position of 'reactpy_django' in INSTALLED_APPS) has been added.REACTPY_DEFAULT_QUERY_POSTPROCESSOR to None.REACTPY_RECONNECT_INTERVALREACTPY_RECONNECT_MAX_INTERVALREACTPY_RECONNECT_MAX_RETRIESREACTPY_RECONNECT_BACKOFF_MULTIPLIER1.0.2.args/kwargs if settings.py:DEBUG is enabled.@reactpy/client version to 0.3.14.2.settings.py:REACTPY_RECONNECT_MAX is removed. See the docs for the new REACTPY_RECONNECT_* settings.REACTPY_DEFAULT_HOSTS setting can round-robin a list of ReactPy rendering hosts.host argument has been added to the component template tag to force components to render on a specific host.reactpy_django.utils.register_component function can manually register root components.reactpy_django.REACTPY_WEBSOCKET_PATH is deprecated. The identical replacement is REACTPY_WEBSOCKET_ROUTE.settings.py:REACTPY_WEBSOCKET_URL is deprecated. The similar replacement is REACTPY_URL_PREFIX.REACTPY_WEBSOCKET_URL doesn't end with a slash) has been removed. ReactPy now automatically handles slashes.REACTPY_WEBSOCKET_URL doesn't start with an alphanumeric character) has been removed. ReactPy now automatically handles this scenario.channels is not in settings.py:INSTALLED_APPS) has been removed. Newer versions of channels do not require installation via INSTALLED_APPS to receive an ASGI web server.orjson resulting in an ~6% overall performance improvement.asyncio event loops are now patched via nest_asyncio, resulting in an ~10% overall performance improvement. This has no performance impact if you are running your web server with uvloop.REACTPY_WEBSOCKET_URL always generates a warning if unset.assert f is self._write_fut would be raised by uvicorn when REACTPY_BACKHAUL_THREAD = True.daphne when REACTPY_BACKHAUL_THREAD = True.REACTPY_BACKHAUL_THREAD now defaults to False.REACTPY_BACKHAUL_THREAD setting to enable/disable threading behavior.settings.py:REACTPY_DATABASE, reactpy_django.database.Router must now be registered in settings.py:DATABASE_ROUTERS.3.9settings.py:DEBUG is enabled.component template tag from causing the whole template to fail to render.DEBUG mode.REACTPY_AUTH_BACKEND setting to allow for custom authentication backends.SessionMiddlewareStack is now optional.AuthMiddlewareStack is now optional.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.mutate argument on reactpy_django.hooks.use_mutation has been renamed to mutation.django-reactpy database entries are no longer cleaned during Django application startup. Instead, it will occur on webpage loads if REACTPY_RECONNECT_MAX seconds has elapsed since the last cleaning.django-idom has been renamed to reactpy-django! Please note that all references to the word idom in your code should be changed to reactpy. See the docs for more details.This is Django-IDOM's biggest update yet!
To upgrade from previous version you will need to...
django-idom >= 3.0.0idom rewrite-keys <DIR> and idom rewrite-camel-case-props <DIR> to update your idom.html.* calls to the new syntaxpython manage.py migrate to create the new Django-IDOM database entriesidom client will automatically configure itself to debug mode depending on settings.py:DEBUG.use_connection hook for returning the browser's active Connection.IDOM_CACHE is now configurable within settings.py to whatever cache name you wish.manage.py migrate after installing IDOM.idom.html.*...snake_case. For example className now becomes class_name.key=... is now declared within the props dict (rather than as a kwarg).component template tag now supports both positional and keyword arguments.component template tag now supports non-serializable arguments.IDOM_WS_MAX_RECONNECT_TIMEOUT setting has been renamed to IDOM_RECONNECT_MAX.django_idom.hooks.use_websocket has been removed. The similar replacement is django_idom.hooks.use_connection.django_idom.types.IdomWebsocket has been removed. The similar replacement is django_idom.types.Connection.settings.py:CACHE['idom'] is no longer used by default. The name of the cache back-end must now be specified with the IDOM_CACHE setting.view_to_component will now retain the contents of a <head> tag when rendering.production rather than development.use_query will now utilize field.related_name when postprocessing many-to-one relationships.settings.py:DEBUG.use_query would not recursively fetch many-to-one relationships.options: QueryOptions parameter to use_query to allow for configuration of this hook.use_query will recursively prefetch all many-to-many or many-to-one relationships to prevent SynchronousOnlyOperation exceptions.django_idom.hooks._fetch_lazy_fields has been deleted. The equivalent replacement is django_idom.utils.django_query_postprocessor.channels version is now 4.0.0.view_to_component callable to have request argument be optional.view_to_component to represent it as a decorator with parenthesis (such as @view_to_component(compatibility=True))view_to_component when using compatibility=True.key=... parameter on all prefabricated components.use_origin hook for returning the browser's location.origin.view_to_component now returns a Callable, instead of directly returning a Component. Check the docs for new usage info.use_mutation and use_query will now log any query failures.use_mutation to have refetch=None, as the docs suggest is possible.use_query will now prefetch all fields to prevent SynchronousOnlyOperation exceptions.view_to_component, django_css, and django_js type hints will now display like normal functions.auth_required decorator to prevent your components from rendering to unauthenticated users.use_query hook for fetching database values.use_mutation hook for modifying database values.view_to_component utility to convert legacy Django views to IDOM components.playwright instead of seleniumdjango_css and django_js components to defer loading CSS & JS files until needed.use_websocket, use_scope, and use_location are now available within the django_idom.hooks module.idom_component template tag has been renamed to componentwebsocket parameter for components has been removed. Functionally, it is replaced with django_idom.hooks.use_websocket.idom.core.proto caused by IDOM 0.37.2divname = ... parameter to IDOM HTTP paths for use with django.urls.reverse()IdomWebsocketdjango_idom/ parent folder0.36.04.03.8IDOM_WEB_MODULES_PATH has been replaced with Django include(...)IDOM_WS_MAX_RECONNECT_DELAY has been renamed to IDOM_WS_MAX_RECONNECT_TIMEOUTidom_web_modules cache back-end has been renamed to idomYou will need to set up a Python environment to develop ReactPy-Django.
Note
Looking to contribute features that are not Django specific?
Everything within the reactpy-django repository must be specific to Django integration. Check out the ReactPy Core documentation to contribute general features such as components, hooks, and events.
If you plan to make code changes to this repository, you will need to install the following dependencies first:
Once done, you should clone this repository:
git clone https://github.com/reactive-python/reactpy-django.git
+ Code - ReactPy-Django Code
Overview¶
You will need to set up a Python environment to develop ReactPy-Django.
Note
Looking to contribute features that are not Django specific?
Everything within the reactpy-django repository must be specific to Django integration. Check out the ReactPy Core documentation to contribute general features such as components, hooks, and events.
Creating an environment¶
If you plan to make code changes to this repository, you will need to install the following dependencies first:
- Python 3.9+
- Git
- NPM for installing and managing Javascript
Once done, you should clone this repository:
git clone https://github.com/reactive-python/reactpy-django.git
cd reactpy-django
Then, by running the command below you can:
- Install an editable version of the Python code
- Download, build, and install Javascript dependencies
pip install -e . -r requirements.txt --verbose --upgrade
Pitfall
Some of our development dependencies require a C++ compiler, which is not installed by default on Windows.
If you receive errors related to this during installation, follow the instructions in your console errors.
Finally, to verify that everything is working properly, you can manually run the test web server.
cd tests
@@ -9,4 +9,4 @@
python manage.py test
Running Django test web server¶
If you want to manually run the Django test application, you can use the following command:
cd tests
python manage.py runserver
-
Last update: September 16, 2023 Authors:
\ No newline at end of file
+You will need to set up a Python environment to create, test, and preview docs changes.
If you plan to make changes to this documentation, you will need to install the following dependencies first:
Once done, you should clone this repository:
git clone https://github.com/reactive-python/reactpy-django.git
+ Docs - ReactPy-Django Docs
Overview¶
You will need to set up a Python environment to create, test, and preview docs changes.
Modifying Docs¶
If you plan to make changes to this documentation, you will need to install the following dependencies first:
Once done, you should clone this repository:
git clone https://github.com/reactive-python/reactpy-django.git
cd reactpy-django
Then, by running the command below you can:
- Install an editable version of the documentation
- Self-host a test server for the documentation
pip install -r requirements.txt --upgrade
Finally, to verify that everything is working properly, you can manually run the docs preview web server.
mkdocs serve
-
Navigate to http://127.0.0.1:8000 to view a preview of the documentation.
GitHub Pull Request¶
Now, you can create/modify the ReactPy-Django source code, and Pull Request (PR) your changes to our GitHub repository.
To learn how to create GitHub PRs, click here.
Last update: September 16, 2023 Authors:
\ No newline at end of file
+Navigate to http://127.0.0.1:8000 to view a preview of the documentation.
Now, you can create/modify the ReactPy-Django source code, and Pull Request (PR) your changes to our GitHub repository.
To learn how to create GitHub PRs, click here.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
If you want to add some interactivity to your existing Django project, you don't have to rewrite it in ReactPy. Use ReactPy-Django to add ReactPy to your existing stack, and render interactive components anywhere.
Note
These docs assumes you have already created a Django project, which involves creating and installing at least one Django app.
If do not have a Django project, check out this 9 minute YouTube tutorial created by IDG TECHtalk.
Run the following command to install reactpy-django in your Python environment.
pip install reactpy-django
+ Add ReactPy to a Django Project - ReactPy-Django Add ReactPy to a Django Project
Overview¶
If you want to add some interactivity to your existing Django project, you don't have to rewrite it in ReactPy. Use ReactPy-Django to add ReactPy to your existing stack, and render interactive components anywhere.
Note
These docs assumes you have already created a Django project, which involves creating and installing at least one Django app.
If do not have a Django project, check out this 9 minute YouTube tutorial created by IDG TECHtalk.
Step 1: Install from PyPI¶
Run the following command to install reactpy-django in your Python environment.
pip install reactpy-django
Step 2: Configure settings.py¶
Add "reactpy_django" to INSTALLED_APPS in your settings.py file.
1
2
3
@@ -100,4 +100,4 @@
{% component "example_project.my_app.components.hello_world" recipient="World" %}
</body>
</html>
-
Last update: September 16, 2023 Authors:
\ No newline at end of file
+ Components are one of the core concepts of ReactPy. They are the foundation upon which you build user interfaces (UI), which makes them the perfect place to start your journey!
Note
If you have reached this point, you should have already installed ReactPy-Django through the previous steps.
You will now need to pick at least one Django app to start using ReactPy-Django on.
For the following examples, we will assume the following:
my_app, which was created by Django's startapp command.my_app directly into your Django project folder (./example_project/my_app). This is common for small projects.ReactPy-Django has no project structure requirements. Organize everything as you wish, just like any Django project.
You will need a file to start creating ReactPy components.
We recommend creating a components.py file within your chosen Django app to start out. For this example, the file path will look like this: ./example_project/my_app/components.py.
Within this file, you can define your component functions using ReactPy's @component decorator.
1 + Now you can navigate to your Django project URL that contains a ReactPy component, such as If you copy-pasted our example component, you will now see your component display "Hello World". Do not use |
1 + |
<head>?Traditionally, JavaScript is loaded in your <head> using Django's {% static %} template tag.
However, to help improve webpage load times you can use this django_js component to defer loading your JavaScript until it is needed.
Decorator functions can be used within your components.py to help simplify development.
You can limit access to a component to users with a specific auth_attribute by using this decorator (with or without parentheses).
By default, this decorator checks if the user is logged in and not deactivated (is_active).
This decorator is commonly used to selectively render a component only if a user is_staff or is_superuser.
1 + |
Prefabricated hooks can be used within your components.py to help simplify development.
Note
Looking for standard React hooks?
This package only contains Django specific hooks. Standard hooks can be found within reactive-python/reactpy.
This hook is used read data from the Django ORM.
The query function you provide must return either a Model or QuerySet.
1 + |
Parameters
None
Returns
| Type | Description |
|---|---|
str | None | A string containing the browser's current origin, obtained from WebSocket or HTTP headers (if available). |
These are ReactPy-Django's default settings values. You can modify these values in your Django project's settings.py to change the behavior of ReactPy.
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.
REACTPY_URL_PREFIX¶Default: "reactpy/"
Example Value(s): "rp/", "render/reactpy/"
The prefix used for all ReactPy WebSocket and HTTP URLs.
REACTPY_DEFAULT_QUERY_POSTPROCESSOR¶Default: "reactpy_django.utils.django_query_postprocessor"
Example Value(s): "example_project.postprocessor", None
Dotted path to the default reactpy_django.hooks.use_query postprocessor function.
Postprocessor functions can be async or sync. Here is an example of a sync postprocessor function:
def postprocessor(data):
+ Settings - ReactPy-Django Settings
Overview¶
These are ReactPy-Django's default settings values. You can modify these values in your Django project's settings.py to change the behavior of ReactPy.
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¶
REACTPY_URL_PREFIX¶
Default: "reactpy/"
Example Value(s): "rp/", "render/reactpy/"
The prefix used for all ReactPy WebSocket and HTTP URLs.
REACTPY_DEFAULT_QUERY_POSTPROCESSOR¶
Default: "reactpy_django.utils.django_query_postprocessor"
Example Value(s): "example_project.postprocessor", None
Dotted path to the global default reactpy_django.hooks.use_query postprocessor function.
Postprocessor functions can be async or sync. Here is an example of a sync postprocessor function:
def postprocessor(data):
del data["foo"]
return data
Set REACTPY_DEFAULT_QUERY_POSTPROCESSOR to None to disable the default postprocessor.
REACTPY_AUTH_BACKEND¶
Default: "django.contrib.auth.backends.ModelBackend"
Example Value(s): "example_project.auth.MyModelBackend"
Dotted path to the Django authentication backend to use for ReactPy components. This is only needed if:
- You are using
AuthMiddlewareStack and... - You are using Django's
AUTHENTICATION_BACKENDS setting and... - Your Django user model does not define a
backend attribute.
Performance Settings¶
REACTPY_DATABASE¶
Default: "default"
Example Value(s): "my-reactpy-database"
Multiprocessing-safe database used by ReactPy, typically for session data.
If configuring this value, it is mandatory to enable our database router like such:
DATABASE_ROUTERS = ["reactpy_django.database.Router", ...]
-
REACTPY_CACHE¶
Default: "default"
Example Value(s): "my-reactpy-cache"
Cache used by ReactPy, typically for file operations.
We recommend configuring redis, python-diskcache, or LocMemCache.
REACTPY_BACKHAUL_THREAD¶
Default: False
Example Value(s): True
Configures whether ReactPy components are rendered in a dedicated thread.
This setting allows the web server to process other traffic during ReactPy rendering. Vastly improves throughput with web servers such as hypercorn and uvicorn.
REACTPY_DEFAULT_HOSTS¶
Default: None
Example Value(s): ["localhost:8000", "localhost:8001", "localhost:8002/subdir"]
The default host(s) that can render your ReactPy components.
ReactPy will use these hosts in a round-robin fashion, allowing for easy distributed computing.
You can use the host argument in your template tag to manually override this default.
REACTPY_PRERENDER¶
Default: False
Example Value(s): True
Configures whether to pre-render your components, which enables SEO compatibility and reduces perceived latency.
During pre-rendering, there are some key differences in behavior:
- Only the component's first render is pre-rendered.
- All
connection related hooks use HTTP. html.script elements are executed twice (pre-render and post-render).- The component will be non-interactive until a WebSocket connection is formed.
You can use the prerender argument in your template tag to manually override this default.
Stability Settings¶
REACTPY_RECONNECT_INTERVAL¶
Default: 750
Example Value(s): 100, 2500, 6000
Milliseconds between client reconnection attempts.
REACTPY_RECONNECT_BACKOFF_MULTIPLIER¶
Default: 1.25
Example Value(s): 1, 1.5, 3
On each reconnection attempt, the REACTPY_RECONNECT_INTERVAL will be multiplied by this value to increase the time between attempts.
You can keep time between each reconnection the same by setting this to 1.
REACTPY_RECONNECT_MAX_INTERVAL¶
Default: 60000
Example Value(s): 10000, 25000, 900000
Maximum milliseconds between client reconnection attempts.
This allows setting an upper bound on how high REACTPY_RECONNECT_BACKOFF_MULTIPLIER can increase the time between reconnection attempts.
REACTPY_RECONNECT_MAX_RETRIES¶
Default: 150
Example Value(s): 0, 5, 300
Maximum number of reconnection attempts before the client gives up.
REACTPY_SESSION_MAX_AGE¶
Default: 259200
Example Value(s): 0, 60, 96000
Maximum seconds to store ReactPy component sessions.
ReactPy sessions include data such as *args and **kwargs passed into your {% component %} template tag.
Use 0 to not store any session data.
Last update: September 16, 2023 Authors:
\ No newline at end of file
+REACTPY_CACHE¶Default: "default"
Example Value(s): "my-reactpy-cache"
Cache used by ReactPy, typically for file operations.
We recommend configuring redis, python-diskcache, or LocMemCache.
REACTPY_BACKHAUL_THREAD¶Default: False
Example Value(s): True
Configures whether ReactPy components are rendered in a dedicated thread.
This setting allows the web server to process other traffic during ReactPy rendering. Vastly improves throughput with web servers such as hypercorn and uvicorn.
REACTPY_DEFAULT_HOSTS¶Default: None
Example Value(s): ["localhost:8000", "localhost:8001", "localhost:8002/subdir"]
The default host(s) that can render your ReactPy components.
ReactPy will use these hosts in a round-robin fashion, allowing for easy distributed computing.
You can use the host argument in your template tag to manually override this default.
REACTPY_PRERENDER¶Default: False
Example Value(s): True
Configures whether to pre-render your components, which enables SEO compatibility and reduces perceived latency.
During pre-rendering, there are some key differences in behavior:
connection related hooks use HTTP.html.script elements are executed twice (pre-render and post-render).You can use the prerender argument in your template tag to manually override this default.
REACTPY_RECONNECT_INTERVAL¶Default: 750
Example Value(s): 100, 2500, 6000
Milliseconds between client reconnection attempts.
REACTPY_RECONNECT_BACKOFF_MULTIPLIER¶Default: 1.25
Example Value(s): 1, 1.5, 3
On each reconnection attempt, the REACTPY_RECONNECT_INTERVAL will be multiplied by this value to increase the time between attempts.
You can keep time between each reconnection the same by setting this to 1.
REACTPY_RECONNECT_MAX_INTERVAL¶Default: 60000
Example Value(s): 10000, 25000, 900000
Maximum milliseconds between client reconnection attempts.
This allows setting an upper bound on how high REACTPY_RECONNECT_BACKOFF_MULTIPLIER can increase the time between reconnection attempts.
REACTPY_RECONNECT_MAX_RETRIES¶Default: 150
Example Value(s): 0, 5, 300
Maximum number of reconnection attempts before the client gives up.
REACTPY_SESSION_MAX_AGE¶Default: 259200
Example Value(s): 0, 60, 96000
Maximum seconds to store ReactPy component sessions.
ReactPy sessions include data such as *args and **kwargs passed into your {% component %} template tag.
Use 0 to not store any session data.
Django template tags can be used within your HTML templates to provide ReactPy features.
This template tag can be used to insert any number of ReactPy components onto your page.
1 + |
Utility functions provide various miscellaneous functionality. These are typically not used, but are available for advanced use cases.
This is the default postprocessor for the use_query hook.
This postprocessor is designed to avoid Django's SynchronousOnlyException by recursively fetching all fields within a Model or QuerySet to prevent lazy execution.
1 + |
MyAppConfig.ready()You should always call register_component within a Django MyAppConfig.ready() method. This ensures you will retain multiprocessing compatibility, such as with ASGI web server workers.
You typically will not need to use this function.
For security reasons, ReactPy requires all root components to be registered. However, all components contained within Django templates are automatically registered.
This function is needed when you have configured your host to a dedicated Django rendering application that doesn't have templates.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
"},{"location":"about/changelog/#unreleased","title":"Unreleased","text":""},{"location":"about/changelog/#added","title":"Added","text":"settings.py:REACTPY_PRERENDER can be set to True to enable this behavior by default{% component \"...\" prerender=\"True\" %}reactpy_django.utils.ComponentPreloader to reactpy_django.utils.RootComponentFinder.Suspicious position of 'reactpy_django' in INSTALLED_APPS) has been added.REACTPY_DEFAULT_QUERY_POSTPROCESSOR to None.REACTPY_RECONNECT_INTERVALREACTPY_RECONNECT_MAX_INTERVALREACTPY_RECONNECT_MAX_RETRIESREACTPY_RECONNECT_BACKOFF_MULTIPLIER1.0.2.args/kwargs if settings.py:DEBUG is enabled.@reactpy/client version to 0.3.14.2.settings.py:REACTPY_RECONNECT_MAX is removed. See the docs for the new REACTPY_RECONNECT_* settings.REACTPY_DEFAULT_HOSTS setting can round-robin a list of ReactPy rendering hosts.host argument has been added to the component template tag to force components to render on a specific host.reactpy_django.utils.register_component function can manually register root components.reactpy_django.REACTPY_WEBSOCKET_PATH is deprecated. The identical replacement is REACTPY_WEBSOCKET_ROUTE.settings.py:REACTPY_WEBSOCKET_URL is deprecated. The similar replacement is REACTPY_URL_PREFIX.REACTPY_WEBSOCKET_URL doesn't end with a slash) has been removed. ReactPy now automatically handles slashes.REACTPY_WEBSOCKET_URL doesn't start with an alphanumeric character) has been removed. ReactPy now automatically handles this scenario.channels is not in settings.py:INSTALLED_APPS) has been removed. Newer versions of channels do not require installation via INSTALLED_APPS to receive an ASGI web server.orjson resulting in an ~6% overall performance improvement.asyncio event loops are now patched via nest_asyncio, resulting in an ~10% overall performance improvement. This has no performance impact if you are running your web server with uvloop.REACTPY_WEBSOCKET_URL always generates a warning if unset.assert f is self._write_fut would be raised by uvicorn when REACTPY_BACKHAUL_THREAD = True.daphne when REACTPY_BACKHAUL_THREAD = True.REACTPY_BACKHAUL_THREAD now defaults to False.REACTPY_BACKHAUL_THREAD setting to enable/disable threading behavior.settings.py:REACTPY_DATABASE, reactpy_django.database.Router must now be registered in settings.py:DATABASE_ROUTERS.3.9settings.py:DEBUG is enabled.component template tag from causing the whole template to fail to render.DEBUG mode.REACTPY_AUTH_BACKEND setting to allow for custom authentication backends.SessionMiddlewareStack is now optional.AuthMiddlewareStack is now optional.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.mutate argument on reactpy_django.hooks.use_mutation has been renamed to mutation.django-reactpy database entries are no longer cleaned during Django application startup. Instead, it will occur on webpage loads if REACTPY_RECONNECT_MAX seconds has elapsed since the last cleaning.django-idom has been renamed to reactpy-django! Please note that all references to the word idom in your code should be changed to reactpy. See the docs for more details.This is Django-IDOM's biggest update yet!
To upgrade from previous version you will need to...
django-idom >= 3.0.0idom rewrite-keys <DIR> and idom rewrite-camel-case-props <DIR> to update your idom.html.* calls to the new syntaxpython manage.py migrate to create the new Django-IDOM database entriesidom client will automatically configure itself to debug mode depending on settings.py:DEBUG.use_connection hook for returning the browser's active Connection.IDOM_CACHE is now configurable within settings.py to whatever cache name you wish.manage.py migrate after installing IDOM.idom.html.*...snake_case. For example className now becomes class_name.key=... is now declared within the props dict (rather than as a kwarg).component template tag now supports both positional and keyword arguments.component template tag now supports non-serializable arguments.IDOM_WS_MAX_RECONNECT_TIMEOUT setting has been renamed to IDOM_RECONNECT_MAX.django_idom.hooks.use_websocket has been removed. The similar replacement is django_idom.hooks.use_connection.django_idom.types.IdomWebsocket has been removed. The similar replacement is django_idom.types.Connection.settings.py:CACHE['idom'] is no longer used by default. The name of the cache back-end must now be specified with the IDOM_CACHE setting.view_to_component will now retain the contents of a <head> tag when rendering.production rather than development.use_query will now utilize field.related_name when postprocessing many-to-one relationships.settings.py:DEBUG.use_query would not recursively fetch many-to-one relationships.options: QueryOptions parameter to use_query to allow for configuration of this hook.use_query will recursively prefetch all many-to-many or many-to-one relationships to prevent SynchronousOnlyOperation exceptions.django_idom.hooks._fetch_lazy_fields has been deleted. The equivalent replacement is django_idom.utils.django_query_postprocessor.channels version is now 4.0.0.view_to_component callable to have request argument be optional.view_to_component to represent it as a decorator with parenthesis (such as @view_to_component(compatibility=True))view_to_component when using compatibility=True.key=... parameter on all prefabricated components.use_origin hook for returning the browser's location.origin.view_to_component now returns a Callable, instead of directly returning a Component. Check the docs for new usage info.use_mutation and use_query will now log any query failures.use_mutation to have refetch=None, as the docs suggest is possible.use_query will now prefetch all fields to prevent SynchronousOnlyOperation exceptions.view_to_component, django_css, and django_js type hints will now display like normal functions.auth_required decorator to prevent your components from rendering to unauthenticated users.use_query hook for fetching database values.use_mutation hook for modifying database values.view_to_component utility to convert legacy Django views to IDOM components.playwright instead of seleniumdjango_css and django_js components to defer loading CSS & JS files until needed.use_websocket, use_scope, and use_location are now available within the django_idom.hooks module.idom_component template tag has been renamed to componentwebsocket parameter for components has been removed. Functionally, it is replaced with django_idom.hooks.use_websocket.idom.core.proto caused by IDOM 0.37.2divname = ... parameter to IDOM HTTP paths for use with django.urls.reverse()IdomWebsocketdjango_idom/ parent folder0.36.04.03.8IDOM_WEB_MODULES_PATH has been replaced with Django include(...)IDOM_WS_MAX_RECONNECT_DELAY has been renamed to IDOM_WS_MAX_RECONNECT_TIMEOUTidom_web_modules cache back-end has been renamed to idomYou will need to set up a Python environment to develop ReactPy-Django.
Note
Looking to contribute features that are not Django specific?
Everything within the reactpy-django repository must be specific to Django integration. Check out the ReactPy Core documentation to contribute general features such as components, hooks, and events.
If you plan to make code changes to this repository, you will need to install the following dependencies first:
Once done, you should clone this repository:
git clone https://github.com/reactive-python/reactpy-django.git\ncd reactpy-django\nThen, by running the command below you can:
pip install -e . -r requirements.txt --verbose --upgrade\nPitfall
Some of our development dependencies require a C++ compiler, which is not installed by default on Windows.
If you receive errors related to this during installation, follow the instructions in your console errors.
Finally, to verify that everything is working properly, you can manually run the test web server.
cd tests\npython manage.py runserver\nNavigate to http://127.0.0.1:8000 to see if the tests are rendering correctly.
Now, you can create/modify the ReactPy-Django source code, and Pull Request (PR) your changes to our GitHub repository.
To learn how to create GitHub PRs, click here.
"},{"location":"about/code/#running-the-full-test-suite","title":"Running the full test suite","text":"Note
This repository uses Nox to run tests. For a full test of available scripts run nox -l.
By running the command below you can run the full test suite:
nox -s test\nOr, if you want to run the tests in the background:
nox -s test -- --headless\nIf you want to only run our Django tests in your current environment, you can use the following command:
cd tests\npython manage.py test\nIf you want to manually run the Django test application, you can use the following command:
cd tests\npython manage.py runserver\nYou will need to set up a Python environment to create, test, and preview docs changes.
"},{"location":"about/docs/#modifying-docs","title":"Modifying Docs","text":"If you plan to make changes to this documentation, you will need to install the following dependencies first:
Once done, you should clone this repository:
git clone https://github.com/reactive-python/reactpy-django.git\ncd reactpy-django\nThen, by running the command below you can:
pip install -r requirements.txt --upgrade\nFinally, to verify that everything is working properly, you can manually run the docs preview web server.
mkdocs serve\nNavigate to http://127.0.0.1:8000 to view a preview of the documentation.
Now, you can create/modify the ReactPy-Django source code, and Pull Request (PR) your changes to our GitHub repository.
To learn how to create GitHub PRs, click here.
"},{"location":"learn/add-reactpy-to-a-django-project/","title":"Add ReactPy to a Django Project","text":""},{"location":"learn/add-reactpy-to-a-django-project/#overview","title":"Overview","text":"If you want to add some interactivity to your existing Django project, you don't have to rewrite it in ReactPy. Use ReactPy-Django to add ReactPy to your existing stack, and render interactive components anywhere.
Note
These docs assumes you have already created a Django project, which involves creating and installing at least one Django app.
If do not have a Django project, check out this 9 minute YouTube tutorial created by IDG TECHtalk.
"},{"location":"learn/add-reactpy-to-a-django-project/#step-1-install-from-pypi","title":"Step 1: Install from PyPI","text":"Run the following command to install reactpy-django in your Python environment.
pip install reactpy-django\nsettings.py","text":"Add \"reactpy_django\" to INSTALLED_APPS in your settings.py file.
INSTALLED_APPS = [\n ...,\n \"reactpy_django\",\n]\nReactPy-Django requires Django ASGI and Django Channels WebSockets.
If you have not enabled ASGI on your Django project yet, here is a summary of the django and channels installation docs:
channels[daphne]Add \"daphne\" to INSTALLED_APPS.
INSTALLED_APPS = [\n \"daphne\",\n ...,\n]\nSet your ASGI_APPLICATION variable.
ASGI_APPLICATION = \"example_project.asgi.application\"\nReactPy's has additional configuration available to fit a variety of use cases.
See the ReactPy settings documentation to learn more.
"},{"location":"learn/add-reactpy-to-a-django-project/#step-3-configure-urlspy","title":"Step 3: Configureurls.py","text":"Add ReactPy HTTP paths to your urlpatterns in your urls.py file.
from django.urls import include, path\n\nurlpatterns = [\n ...,\n path(\"reactpy/\", include(\"reactpy_django.http.urls\")),\n]\nasgi.py","text":"Register ReactPy's WebSocket using REACTPY_WEBSOCKET_ROUTE in your asgi.py file.
import os\n\nfrom django.core.asgi import get_asgi_application\n\n# Ensure DJANGO_SETTINGS_MODULE is set properly based on your project name!\nos.environ.setdefault(\"DJANGO_SETTINGS_MODULE\", \"example_project.settings\")\n\n# Fetch ASGI application before importing dependencies that require ORM models.\ndjango_asgi_app = get_asgi_application()\n\n\nfrom channels.routing import ProtocolTypeRouter, URLRouter # noqa: E402\nfrom reactpy_django import REACTPY_WEBSOCKET_ROUTE # noqa: E402\n\napplication = ProtocolTypeRouter(\n {\n \"http\": django_asgi_app,\n \"websocket\": URLRouter([REACTPY_WEBSOCKET_ROUTE]),\n }\n)\nAuthMiddlewareStack and SessionMiddlewareStack (Optional) There are many situations where you need to access the Django User or Session objects within ReactPy components. For example, if you want to:
User that is currently logged inUserSession objectIn these situations will need to ensure you are using AuthMiddlewareStack and/or SessionMiddlewareStack.
from channels.auth import AuthMiddlewareStack # noqa: E402\nfrom channels.sessions import SessionMiddlewareStack # noqa: E402\n\napplication = ProtocolTypeRouter(\n {\n \"http\": django_asgi_app,\n \"websocket\": SessionMiddlewareStack(\n AuthMiddlewareStack(\n URLRouter(\n [REACTPY_WEBSOCKET_ROUTE],\n )\n )\n ),\n }\n)\nasgi.py? If you do not have an asgi.py, follow the channels installation guide.
Run Django's migrate command to initialize ReactPy-Django's database table.
python manage.py migrate\nRun Django's check command to verify if ReactPy was set up correctly.
python manage.py check\nThe next step will show you how to create your first ReactPy component.
Prefer a quick summary? Read the At a Glance section below.
At a Glance: Your First Component
my_app/components.py
You will need a file to define your ReactPy components. We recommend creating a components.py file within your chosen Django app to start out. Within this file, we will create a simple hello_world component.
from reactpy import component, html\n\n@component\ndef hello_world(recipient: str):\n return html.h1(f\"Hello {recipient}!\")\nmy_app/templates/my-template.html
In your Django app's HTML template, you can now embed your ReactPy component using the component template tag. Within this tag, you will need to type in the dotted path to the component.
Additionally, you can pass in args and kwargs into your component function. After reading the code below, pay attention to how the function definition for hello_world (from the previous example) accepts a recipient argument.
{% load reactpy %}\n<!DOCTYPE html>\n<html>\n <body>\n{% component \"example_project.my_app.components.hello_world\" recipient=\"World\" %}\n </body>\n</html>\nComponents are one of the core concepts of ReactPy. They are the foundation upon which you build user interfaces (UI), which makes them the perfect place to start your journey!
Note
If you have reached this point, you should have already installed ReactPy-Django through the previous steps.
"},{"location":"learn/your-first-component/#selecting-a-django-app","title":"Selecting a Django App","text":"You will now need to pick at least one Django app to start using ReactPy-Django on.
For the following examples, we will assume the following:
my_app, which was created by Django's startapp command.my_app directly into your Django project folder (./example_project/my_app). This is common for small projects.ReactPy-Django has no project structure requirements. Organize everything as you wish, just like any Django project.
"},{"location":"learn/your-first-component/#defining-a-component","title":"Defining a component","text":"You will need a file to start creating ReactPy components.
We recommend creating a components.py file within your chosen Django app to start out. For this example, the file path will look like this: ./example_project/my_app/components.py.
Within this file, you can define your component functions using ReactPy's @component decorator.
from reactpy import component, html\n\n@component\ndef hello_world(recipient: str):\n return html.h1(f\"Hello {recipient}!\")\nYou have full freedom in naming/placement of your files and functions.
We recommend creating a components.py for small Django apps. If your app has a lot of components, you should consider breaking them apart into individual modules such as components/navbar.py.
Ultimately, components are referenced by Python dotted path in my-template.html (see next step). This path must be valid to Python's importlib.
While not all components need to be decorated, there are a few features this decorator adds to your components.
In your Django app's HTML template, you can now embed your ReactPy component using the {% component %} template tag. Within this tag, you will need to type in the dotted path to the component.
Additionally, you can pass in args and kwargs into your component function. After reading the code below, pay attention to how the function definition for hello_world (from the previous step) accepts a recipient argument.
{% load reactpy %}\n<!DOCTYPE html>\n<html>\n <body>\n{% component \"example_project.my_app.components.hello_world\" recipient=\"World\" %}\n </body>\n</html>\nThe ReactPy component finder (reactpy_django.utils.RootComponentFinder) requires that your component path is a string.
Do not use Django template/context variables for the component path. Failure to follow this warning can result in unexpected behavior, such as components that will not render.
For example, do not do the following:
my-template.htmlviews.py<!-- This is good -->\n{% component \"example_project.my_app.components.hello_world\" recipient=\"World\" %}\n\n<!-- This is bad -->\n{% component my_variable recipient=\"World\" %}\nfrom django.shortcuts import render\n\n\ndef example_view(request):\n context_vars = {\"my_variable\": \"example_project.my_app.components.hello_world\"}\n return render(request, \"my-template.html\", context_vars)\nYou can add as many components to a webpage as needed by using the template tag multiple times. Retrofitting legacy sites to use ReactPy will typically involve many components on one page.
my-template.html{% load reactpy %}\n<!DOCTYPE html>\n<html>\n <body>\n <h1>{% component \"example_project.my_app.components.my_title\" %}</h1>\n <p>{% component \"example_project.my_app_2.components.goodbye_world\" class=\"bold small-font\" %}</p>\n{% component \"example_project.my_app_3.components.simple_button\" %}\n </body>\n</html>\nPlease note that components separated like this will not be able to interact with each other, except through database queries.
Additionally, in scenarios where you are trying to create a Single Page Application (SPA) within Django, you will only have one component within your <body> tag.
If you do not have a ./templates/ folder in your Django app, you can simply create one! Keep in mind, templates within this folder will not be detected by Django unless you add the corresponding Django app to settings.py:INSTALLED_APPS.
Within your Django app's views.py file, you will need to create a view function to render the HTML template my-template.html (from the previous step).
from django.shortcuts import render\n\n\ndef index(request):\n return render(request, \"my-template.html\")\nWe will add this new view into your urls.py and define what URL it should be accessible at.
from django.urls import path\nfrom example import views\n\nurlpatterns = [\n path(\"example/\", views.index),\n]\nFor 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.
Once you reach that point, we recommend creating an individual urls.py within each of your Django apps.
Then, within your Django project's urls.py you will use Django's include function to link it all together.
To test your new Django view, run the following command to start up a development web server.
python manage.py runserver\nNow you can navigate to your Django project URL that contains a 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\".
Do not usemanage.py runserver for production This command is only intended for development purposes. For production deployments make sure to read Django's documentation.
"},{"location":"learn/your-first-component/#learn-more","title":"Learn more","text":"Congratulations! If you followed the previous steps, you have now created a \"Hello World\" component using ReactPy-Django!
Deep Dive
The docs you are reading only covers our Django integration. To learn more, check out one of the following links:
Additionally, the vast majority of tutorials/guides you find for ReactJS can be applied to ReactPy.
"},{"location":"reference/components/","title":"Components","text":""},{"location":"reference/components/#overview","title":"Overview","text":"We supply some pre-designed that components can be used to help simplify development.
"},{"location":"reference/components/#view-to-component","title":"View To Component","text":"Convert any Django view into a ReactPy component by using this decorator. Compatible with Function Based Views and Class Based Views. Views can be sync or async.
components.pyfrom django.http import HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component\ndef hello_world_view(request):\n return HttpResponse(\"Hello World!\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(),\n )\nParameters
Name Type Description Defaultview Callable | View The view function or class to convert. N/A compatibility bool If True, the component will be rendered in an iframe. When using compatibility mode tranforms, strict_parsing, request, args, and kwargs arguments will be ignored. False transforms Sequence[Callable[[VdomDict], Any]] A list of functions that transforms the newly generated VDOM. The functions will be called on each VDOM node. tuple strict_parsing bool If True, an exception will be generated if the HTML does not perfectly adhere to HTML5. True Returns
Type Description_ViewComponentConstructor A function that takes request, *args, key, **kwargs and returns a ReactPy component. All parameters are directly provided to your view, besides key which is used by ReactPy. Potential information exposure when using compatibility = True When using compatibility mode, ReactPy automatically exposes a URL to your view.
It is your responsibility to ensure privileged information is not leaked via this method.
You must implement a method to ensure only authorized users can access your view. This can be done via directly writing conditionals into your view, or by adding decorators such as user_passes_test to your views. For example...
from django.contrib.auth.decorators import user_passes_test\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component(compatibility=True)\n@user_passes_test(lambda u: u.is_superuser) # type: ignore[union-attr]\ndef example_view(request):\n ...\nfrom django.contrib.auth.decorators import user_passes_test\nfrom django.utils.decorators import method_decorator\nfrom django.views.generic import TemplateView\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component(compatibility=True)\n@method_decorator(user_passes_test(lambda u: u.is_superuser), name=\"dispatch\") # type: ignore[union-attr]\nclass ExampleView(TemplateView):\n ...\nThere are currently several limitations of using view_to_component that may be resolved in a future version.
GET.<a href='example/'></a>) click events.Please note these limitations do not exist when using compatibility mode.
You can simply pass your Class Based View directly into view_to_component.
from django.http import HttpResponse\nfrom django.views import View\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\nclass HelloWorldView(View):\n def get(self, request):\n return HttpResponse(\"Hello World!\")\n\n\nvtc = view_to_component(HelloWorldView)\n\n\n@component\ndef my_component():\n return html.div(\n vtc(),\n )\nIn order to convert external views, you can utilize view_to_component as a function, rather than a decorator.
from example.views import example_view\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\nexample_vtc = view_to_component(example_view)\n\n\n@component\ndef my_component():\n return html.div(\n example_vtc(),\n )\nrequest, args, and kwargs to a view? Request
You can use the request parameter to provide the view a custom request object.
from django.http import HttpRequest, HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\nexample_request = HttpRequest()\nexample_request.method = \"PUT\"\n\n\n@view_to_component\ndef hello_world_view(request):\n return HttpResponse(f\"Hello World! {request.method}\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(\n example_request,\n ),\n )\nargs and kwargs
You can use the args and kwargs parameters to provide positional and keyworded arguments to a view.
from django.http import HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component\ndef hello_world_view(request, arg1, arg2, key1=None, key2=None):\n return HttpResponse(f\"Hello World! {arg1} {arg2} {key1} {key2}\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(\n None, # Your request object (optional)\n \"value_1\",\n \"value_2\",\n key1=\"abc\",\n key2=\"123\",\n ),\n )\nstrict_parsing, compatibility, and transforms? strict_parsing
By default, an exception will be generated if your view's HTML does not perfectly adhere to HTML5.
However, there are some circumstances where you may not have control over the original HTML, so you may be unable to fix it. Or you may be relying on non-standard HTML tags such as <my-tag> Hello World </my-tag>.
In these scenarios, you may want to rely on best-fit parsing by setting the strict_parsing parameter to False.
from django.http import HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component(strict_parsing=False)\ndef hello_world_view(request):\n return HttpResponse(\"<my-tag> Hello World </my-tag>\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(),\n )\nNote: Best-fit parsing is designed to be similar to how web browsers would handle non-standard or broken HTML.
compatibility
For views that rely on HTTP responses other than GET (such as PUT, POST, PATCH, etc), you should consider using compatibility mode to render your view within an iframe.
Any view can be rendered within compatibility mode. However, the transforms, strict_parsing, request, args, and kwargs arguments do not apply to compatibility mode.
from django.http import HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component(compatibility=True)\ndef hello_world_view(request):\n return HttpResponse(\"Hello World!\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(),\n )\nNote: By default the compatibility iframe is unstyled, and thus won't look pretty until you add some CSS.
transforms
After your view has been turned into VDOM (python dictionaries), view_to_component will call your transforms functions on every VDOM node.
This allows you to modify your view prior to rendering.
For example, if you are trying to modify the text of a node with a certain id, you can create a transform like such:
from django.http import HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\ndef example_transform(vdom):\n attributes = vdom.get(\"attributes\")\n if attributes and attributes.get(\"id\") == \"hello-world\":\n vdom[\"children\"][0] = \"Good Bye World!\"\n\n\n@view_to_component(transforms=[example_transform])\ndef hello_world_view(request):\n return HttpResponse(\"<div id='hello-world'> Hello World! <div>\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(),\n )\nAllows you to defer loading a CSS stylesheet until a component begins rendering. This stylesheet must be stored within Django's static files.
components.pyfrom reactpy import component, html\nfrom reactpy_django.components import django_css\n\n\n@component\ndef my_component():\n return html.div(\n django_css(\"css/buttons.css\"),\n html.button(\"My Button!\"),\n )\nParameters
Name Type Description Defaultstatic_path str The path to the static file. This path is identical to what you would use on a static template tag. N/A key Key | None A key to uniquely identify this component which is unique amongst a component's immediate siblings None Returns
Type DescriptionComponent A ReactPy component. Should I put django_css at the top of my HTML? Yes, if the stylesheet contains styling for your component.
Can I load static CSS usinghtml.link instead? While you can load stylesheets with html.link, keep in mind that loading this way does not ensure load order. Thus, your stylesheet will be loaded after your component is displayed. This would likely cause unintended visual behavior, so use this at your own discretion.
Here's an example on what you should avoid doing for Django static files:
from django.templatetags.static import static\nfrom reactpy import component, html\n\n\n@component\ndef my_component():\n return html.div(\n html.link({\"rel\": \"stylesheet\", \"href\": static(\"css/buttons.css\")}),\n html.button(\"My Button!\"),\n )\ndjango_css can only be used with local static files.
For external CSS, substitute django_css with html.link.
from reactpy import component, html\n\n\n@component\ndef my_component():\n return html.div(\n html.link(\n {\"rel\": \"stylesheet\", \"href\": \"https://example.com/external-styles.css\"}\n ),\n html.button(\"My Button!\"),\n )\n<head>? Traditionally, stylesheets are loaded in your <head> using the {% load static %} template tag.
To help improve webpage load times, you can use the django_css component to defer loading your stylesheet until it is needed.
Allows you to defer loading JavaScript until a component begins rendering. This JavaScript must be stored within Django's static files.
components.pyfrom reactpy import component, html\nfrom reactpy_django.components import django_js\n\n\n@component\ndef my_component():\n return html.div(\n html.button(\"My Button!\"),\n django_js(\"js/scripts.js\"),\n )\nParameters
Name Type Description Defaultstatic_path str The path to the static file. This path is identical to what you would use on a static template tag. N/A key Key | None A key to uniquely identify this component which is unique amongst a component's immediate siblings None Returns
Type DescriptionComponent A ReactPy component. Should I put django_js at the bottom of my HTML? Yes, if your scripts are reliant on the contents of the component.
Can I load static JavaScript usinghtml.script instead? While you can load JavaScript with html.script, keep in mind that loading this way does not ensure load order. Thus, your JavaScript will likely be loaded at an arbitrary time after your component is displayed.
Here's an example on what you should avoid doing for Django static files:
from django.templatetags.static import static\nfrom reactpy import component, html\n\n\n@component\ndef my_component():\n return html.div(\n html.script({\"src\": static(\"js/scripts.js\")}),\n html.button(\"My Button!\"),\n )\ndjango_js can only be used with local static files.
For external JavaScript, substitute django_js with html.script.
from reactpy import component, html\n\n\n@component\ndef my_component():\n return html.div(\n html.script({\"src\": \"https://example.com/external-scripts.js\"}),\n html.button(\"My Button!\"),\n )\n<head>? Traditionally, JavaScript is loaded in your <head> using the {% load static %} template tag.
To help improve webpage load times, you can use the django_js component to defer loading your JavaScript until it is needed.
Decorator functions can be used within your components.py to help simplify development.
You can limit access to a component to users with a specific auth_attribute by using this decorator (with or without parentheses).
By default, this decorator checks if the user is logged in and not deactivated (is_active).
This decorator is commonly used to selectively render a component only if a user is_staff or is_superuser.
from reactpy import component, html\nfrom reactpy_django.decorators import auth_required\n\n\n@component\n@auth_required\ndef my_component():\n return html.div(\"I am logged in!\")\nParameters
Name Type Description Defaultauth_attribute str The value to check within the user object. This is checked via getattr(scope[\"user\"], auth_attribute). \"is_active\" fallback ComponentType | VdomDict | None The component or reactpy.html snippet to render if the user is not authenticated. None Returns
Type Description #!python Component` A ReactPy component. #!python VdomDict| A#!python reactpy.html` snippet. #!python None` No component render. How do I render a different component if authentication fails? You can use a component with the fallback argument, as seen below.
from reactpy import component, html\nfrom reactpy_django.decorators import auth_required\n\n\n@component\ndef my_component_fallback():\n return html.div(\"I am NOT logged in!\")\n\n\n@component\n@auth_required(fallback=my_component_fallback)\ndef my_component():\n return html.div(\"I am logged in!\")\nreactpy.html snippet if authentication fails? You can use a reactpy.html snippet with the fallback argument, as seen below.
from reactpy import component, html\nfrom reactpy_django.decorators import auth_required\n\n\n@component\n@auth_required(fallback=html.div(\"I am NOT logged in!\"))\ndef my_component():\n return html.div(\"I am logged in!\")\nis_staff? You can do this by setting auth_attribute=\"is_staff\", as seen blow.
from reactpy import component, html\nfrom reactpy_django.decorators import auth_required\n\n\n@component\n@auth_required(auth_attribute=\"is_staff\")\ndef my_component():\n return html.div(\"I am logged in!\")\nYou will need to be using a custom user model within your Django instance.
For example, if your user model has the field is_really_cool ...
from django.contrib.auth.models import AbstractBaseUser\n\n\nclass CustomUserModel(AbstractBaseUser):\n @property\n def is_really_cool(self):\n return True\n... then you would do the following within your decorator:
components.pyfrom reactpy import component, html\nfrom reactpy_django.decorators import auth_required\n\n\n@component\n@auth_required(auth_attribute=\"is_really_cool\")\ndef my_component():\n return html.div(\"I am logged in!\")\n Prefabricated hooks can be used within your components.py to help simplify development.
Note
Looking for standard React hooks?
This package only contains Django specific hooks. Standard hooks can be found within reactive-python/reactpy.
This hook is used read data from the Django ORM.
The query function you provide must return either a Model or QuerySet.
from example.models import TodoItem\nfrom reactpy import component, html\nfrom reactpy_django.hooks import use_query\n\n\ndef get_items():\n return TodoItem.objects.all()\n\n\n@component\ndef todo_list():\n item_query = use_query(get_items)\n\n if item_query.loading:\n rendered_items = html.h2(\"Loading...\")\n elif item_query.error or not item_query.data:\n rendered_items = html.h2(\"Error when loading!\")\n else:\n rendered_items = html.ul([html.li(item, key=item) for item in item_query.data])\n\n return html.div(\"Rendered items: \", rendered_items)\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nParameters
Name Type Description Defaultoptions QueryOptions | None An optional QueryOptions object that can modify how the query is executed. None query Callable[_Params, _Result | None] A callable that returns a Django Model or QuerySet. N/A *args _Params.args Positional arguments to pass into query. N/A **kwargs _Params.kwargs Keyword arguments to pass into query. N/A Returns
Type DescriptionQuery[_Result | None] An object containing loading/error states, your data (if the query has successfully executed), and a refetch callable that can be used to re-run the query. How can I provide arguments to my query function? *args and **kwargs can be provided to your query function via use_query parameters.
from reactpy import component\nfrom reactpy_django.hooks import use_query\n\n\ndef example_query(value: int, other_value: bool = False):\n ...\n\n\n@component\ndef my_component():\n query = use_query(\n example_query,\n 123,\n other_value=True,\n )\n\n return str(query.data)\nget_items in the example return TodoItem.objects.all()? This was a technical design decision to based on Apollo's useQuery hook, but ultimately helps avoid Django's SynchronousOnlyOperation exceptions.
The use_query hook ensures the provided Model or QuerySet executes all deferred/lazy queries safely prior to reaching your components.
QueryOptions to customize fetching behavior? thread_sensitive
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 docs for more information.
This setting only applies to sync query functions, and will be ignored for async functions.
components.pyfrom reactpy import component\nfrom reactpy_django.hooks import use_query\nfrom reactpy_django.types import QueryOptions\n\n\ndef execute_thread_safe_operation():\n\"\"\"This is an example query function that does some thread-safe operation.\"\"\"\n pass\n\n\n@component\ndef my_component():\n query = use_query(\n QueryOptions(thread_sensitive=False),\n execute_thread_safe_operation,\n )\n\n if query.loading or query.error:\n return None\n\n return str(query.data)\npostprocessor
By default, automatic recursive fetching of ManyToMany or ForeignKey fields is enabled within the default QueryOptions.postprocessor. This is needed to prevent SynchronousOnlyOperation exceptions when accessing these fields within your ReactPy components.
However, if you...
use_query with a different ORM... 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.
from reactpy import component\nfrom reactpy_django.hooks import use_query\nfrom reactpy_django.types import QueryOptions\n\n\ndef execute_io_intensive_operation():\n\"\"\"This is an example query function that does something IO intensive.\"\"\"\n pass\n\n\n@component\ndef my_component():\n query = use_query(\n QueryOptions(postprocessor=None),\n execute_io_intensive_operation,\n )\n\n if query.loading or query.error:\n return None\n\n return str(query.data)\nIf you wish to create a custom postprocessor, you will need to create a callable.
The first argument of postprocessor must be the query data. All proceeding arguments are optional postprocessor_kwargs (see below). This postprocessor must return the modified data.
from reactpy import component\nfrom reactpy_django.hooks import use_query\nfrom reactpy_django.types import QueryOptions\n\n\ndef my_postprocessor(data, example_kwarg=True):\n if example_kwarg:\n return data\n\n return dict(data)\n\n\ndef execute_io_intensive_operation():\n\"\"\"This is an example query function that does something IO intensive.\"\"\"\n pass\n\n\n@component\ndef my_component():\n query = use_query(\n QueryOptions(\n postprocessor=my_postprocessor,\n postprocessor_kwargs={\"example_kwarg\": False},\n ),\n execute_io_intensive_operation,\n )\n\n if query.loading or query.error:\n return None\n\n return str(query.data)\npostprocessor_kwargs
By default, automatic recursive fetching of ManyToMany or ForeignKey fields is enabled within the default QueryOptions.postprocessor. This is needed to prevent SynchronousOnlyOperation exceptions when accessing these fields within your ReactPy components.
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 use_query hook.
You can disable the prefetching behavior of the default postprocessor (located at reactpy_django.utils.django_query_postprocessor) via the QueryOptions.postprocessor_kwargs parameter.
from example.models import TodoItem\nfrom reactpy import component\nfrom reactpy_django.hooks import use_query\nfrom reactpy_django.types import QueryOptions\n\n\ndef get_model_with_relationships():\n\"\"\"This is an example query function that gets `MyModel` which has a ManyToMany field, and\n additionally other models that have formed a ForeignKey association to `MyModel`.\n\n ManyToMany Field: `many_to_many_field`\n ForeignKey Field: `foreign_key_field_set`\n \"\"\"\n return TodoItem.objects.get(id=1)\n\n\n@component\ndef my_component():\n query = use_query(\n QueryOptions(\n postprocessor_kwargs={\"many_to_many\": False, \"many_to_one\": False}\n ),\n get_model_with_relationships,\n )\n\n if query.loading or query.error or not query.data:\n return None\n\n # By disabling `many_to_many` and `many_to_one`, accessing these fields will now\n # generate a `SynchronousOnlyOperation` exception\n return f\"{query.data.many_to_many_field} {query.data.foriegn_key_field_set}\"\nNote: In Django's ORM design, the field name to access foreign keys is postfixed with _set by default.
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.pyfrom channels.db import database_sync_to_async\nfrom example.models import TodoItem\nfrom reactpy import component, html\nfrom reactpy_django.hooks import use_query\n\n\nasync def get_items():\n return await database_sync_to_async(TodoItem.objects.all)()\n\n\n@component\ndef todo_list():\n item_query = use_query(get_items)\n\n if item_query.loading:\n rendered_items = html.h2(\"Loading...\")\n elif item_query.error or not item_query.data:\n rendered_items = html.h2(\"Error when loading!\")\n else:\n rendered_items = html.ul([html.li(item, key=item) for item in item_query.data])\n\n return html.div(\"Rendered items: \", rendered_items)\nDue to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a SynchronousOnlyOperation exception.
These SynchronousOnlyOperation exceptions may be resolved in a future version of Django containing an asynchronous ORM. However, it is best practice to always perform ORM calls in the background via hooks.
This hook is used to create, update, or delete Django ORM objects.
The mutation function you provide should have no return value.
components.pymodels.pyfrom example.models import TodoItem\nfrom reactpy import component, html\nfrom reactpy_django.hooks import use_mutation\n\n\ndef add_item(text: str):\n TodoItem(text=text).save()\n\n\n@component\ndef todo_list():\n item_mutation = use_mutation(add_item)\n\n def submit_event(event):\n if event[\"key\"] == \"Enter\":\n item_mutation.execute(text=event[\"target\"][\"value\"])\n\n if item_mutation.loading:\n mutation_status = html.h2(\"Adding...\")\n elif item_mutation.error:\n mutation_status = html.h2(\"Error when adding!\")\n else:\n mutation_status = html.h2(\"Mutation done.\")\n\n return html.div(\n html.label(\"Add an item:\"),\n html.input({\"type\": \"text\", \"onKeyDown\": submit_event}),\n mutation_status,\n )\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nParameters
Name Type Description Defaultmutate Callable[_Params, bool | None] A callable that performs Django ORM create, update, or delete functionality. If this function returns False, then your refetch function will not be used. N/A refetch Callable[..., Any] | Sequence[Callable[..., Any]] | None A query function (used by the use_query hook) or a sequence of query functions that will be called if the mutation succeeds. This is useful for refetching data after a mutation has been performed. None Returns
Type DescriptionMutation[_Params] An object containing loading/error states, a reset callable that will set loading/error states to defaults, and a execute callable that will run the query. How can I provide arguments to my mutation function? *args and **kwargs can be provided to your mutation function via #!python mutation.execute` parameters.
from reactpy import component\nfrom reactpy_django.hooks import use_mutation\n\n\ndef example_mutation(value: int, other_value: bool = False):\n ...\n\n\n@component\ndef my_component():\n mutation = use_mutation(example_mutation)\n\n mutation.execute(123, other_value=True)\n\n ...\nuse_mutation trigger a refetch of use_query? Yes, use_mutation can queue a refetch of a use_query via the refetch=... argument.
The example below is a merge of the use_query and use_mutation examples above with the addition of a use_mutation(refetch=...) argument.
Please note that any use_query hooks that use get_items will be refetched upon a successful mutation.
from example.models import TodoItem\nfrom reactpy import component, html\nfrom reactpy_django.hooks import use_mutation, use_query\n\n\ndef get_items():\n return TodoItem.objects.all()\n\n\ndef add_item(text: str):\n TodoItem(text=text).save()\n\n\n@component\ndef todo_list():\n item_query = use_query(get_items)\n item_mutation = use_mutation(add_item, refetch=get_items)\n\n def submit_event(event):\n if event[\"key\"] == \"Enter\":\n item_mutation.execute(text=event[\"target\"][\"value\"])\n\n # Handle all possible query states\n if item_query.loading:\n rendered_items = html.h2(\"Loading...\")\n elif item_query.error or not item_query.data:\n rendered_items = html.h2(\"Error when loading!\")\n else:\n rendered_items = html.ul(html.li(item, key=item) for item in item_query.data)\n\n # Handle all possible mutation states\n if item_mutation.loading:\n mutation_status = html.h2(\"Adding...\")\n elif item_mutation.error:\n mutation_status = html.h2(\"Error when adding!\")\n else:\n mutation_status = html.h2(\"Mutation done.\")\n\n return html.div(\n html.label(\"Add an item:\"),\n html.input({\"type\": \"text\", \"onKeyDown\": submit_event}),\n mutation_status,\n rendered_items,\n )\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nuse_mutation try again? Yes, a use_mutation can be re-performed by calling reset() on your use_mutation instance.
For example, take a look at reset_event below.
from example.models import TodoItem\nfrom reactpy import component, html\nfrom reactpy_django.hooks import use_mutation\n\n\ndef add_item(text: str):\n TodoItem(text=text).save()\n\n\n@component\ndef todo_list():\n item_mutation = use_mutation(add_item)\n\n def reset_event(event):\n item_mutation.reset()\n\n def submit_event(event):\n if event[\"key\"] == \"Enter\":\n item_mutation.execute(text=event[\"target\"][\"value\"])\n\n if item_mutation.loading:\n mutation_status = html.h2(\"Adding...\")\n elif item_mutation.error:\n mutation_status = html.button({\"onClick\": reset_event}, \"Error: Try again!\")\n else:\n mutation_status = html.h2(\"Mutation done.\")\n\n return html.div(\n html.label(\"Add an item:\"),\n html.input({\"type\": \"text\", \"onKeyDown\": submit_event}),\n mutation_status,\n )\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nDue to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a SynchronousOnlyOperation exception.
These SynchronousOnlyOperation exceptions may be resolved in a future version of Django containing an asynchronous ORM. However, it is best practice to always perform ORM calls in the background via hooks.
This hook is used to fetch the Django Channels WebSocket.
components.pyfrom reactpy import component, html\nfrom reactpy_django.hooks import use_connection\n\n\n@component\ndef my_component():\n my_connection = use_connection()\n return html.div(str(my_connection))\nParameters
None
Returns
Type DescriptionConnection The component's WebSocket."},{"location":"reference/hooks/#use-scope","title":"Use Scope","text":"This is a shortcut that returns the WebSocket's scope.
from reactpy import component, html\nfrom reactpy_django.hooks import use_scope\n\n\n@component\ndef my_component():\n my_scope = use_scope()\n return html.div(str(my_scope))\nParameters
None
Returns
Type DescriptionMutableMapping[str, Any] The WebSocket's scope."},{"location":"reference/hooks/#use-location","title":"Use Location","text":"This is a shortcut that returns the WebSocket's path.
You can expect this hook to provide strings such as /reactpy/my_path.
from reactpy import component, html\nfrom reactpy_django.hooks import use_location\n\n\n@component\ndef my_component():\n my_location = use_location()\n return html.div(str(my_location))\nParameters
None
Returns
Type DescriptionLocation An object containing the current URL's pathname and search query. This hook's behavior will be changed in a future update This hook will be updated to return the browser's currently active HTTP path. This change will come in alongside ReactPy URL routing support.
Check out reactive-python/reactpy-django#147 for more information.
"},{"location":"reference/hooks/#use-origin","title":"Use Origin","text":"This is a shortcut that returns the WebSocket's origin.
You can expect this hook to provide strings such as http://example.com.
from reactpy import component, html\nfrom reactpy_django.hooks import use_origin\n\n\n@component\ndef my_component():\n my_origin = use_origin()\n return html.div(my_origin or \"No origin\")\nParameters
None
Returns
Type Descriptionstr | None A string containing the browser's current origin, obtained from WebSocket headers (if available)."},{"location":"reference/settings/","title":"Settings","text":""},{"location":"reference/settings/#overview","title":"Overview","text":" These are ReactPy-Django's default settings values. You can modify these values in your Django project's settings.py to change the behavior of ReactPy.
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.
"},{"location":"reference/settings/#general-settings","title":"General Settings","text":""},{"location":"reference/settings/#reactpy_url_prefix","title":"REACTPY_URL_PREFIX","text":"Default: \"reactpy/\"
Example Value(s): \"rp/\", \"render/reactpy/\"
The prefix used for all ReactPy WebSocket and HTTP URLs.
"},{"location":"reference/settings/#reactpy_default_query_postprocessor","title":"REACTPY_DEFAULT_QUERY_POSTPROCESSOR","text":"Default: \"reactpy_django.utils.django_query_postprocessor\"
Example Value(s): \"example_project.postprocessor\", None
Dotted path to the default reactpy_django.hooks.use_query postprocessor function.
Postprocessor functions can be async or sync. Here is an example of a sync postprocessor function:
def postprocessor(data):\n del data[\"foo\"]\n return data\nSet REACTPY_DEFAULT_QUERY_POSTPROCESSOR to None to disable the default postprocessor.
REACTPY_AUTH_BACKEND","text":"Default: \"django.contrib.auth.backends.ModelBackend\"
Example Value(s): \"example_project.auth.MyModelBackend\"
Dotted path to the Django authentication backend to use for ReactPy components. This is only needed if:
AuthMiddlewareStack and...AUTHENTICATION_BACKENDS setting and...backend attribute.REACTPY_DATABASE","text":"Default: \"default\"
Example Value(s): \"my-reactpy-database\"
Multiprocessing-safe database used by ReactPy, typically for session data.
If configuring this value, it is mandatory to enable our database router like such:
DATABASE_ROUTERS = [\"reactpy_django.database.Router\", ...]\nREACTPY_CACHE","text":"Default: \"default\"
Example Value(s): \"my-reactpy-cache\"
Cache used by ReactPy, typically for file operations.
We recommend configuring redis, python-diskcache, or LocMemCache.
REACTPY_BACKHAUL_THREAD","text":"Default: False
Example Value(s): True
Configures whether ReactPy components are rendered in a dedicated thread.
This setting allows the web server to process other traffic during ReactPy rendering. Vastly improves throughput with web servers such as hypercorn and uvicorn.
REACTPY_DEFAULT_HOSTS","text":"Default: None
Example Value(s): [\"localhost:8000\", \"localhost:8001\", \"localhost:8002/subdir\"]
The default host(s) that can render your ReactPy components.
ReactPy will use these hosts in a round-robin fashion, allowing for easy distributed computing.
You can use the host argument in your template tag to manually override this default.
REACTPY_PRERENDER","text":"Default: False
Example Value(s): True
Configures whether to pre-render your components, which enables SEO compatibility and reduces perceived latency.
During pre-rendering, there are some key differences in behavior:
connection related hooks use HTTP.html.script elements are executed twice (pre-render and post-render).You can use the prerender argument in your template tag to manually override this default.
REACTPY_RECONNECT_INTERVAL","text":"Default: 750
Example Value(s): 100, 2500, 6000
Milliseconds between client reconnection attempts.
"},{"location":"reference/settings/#reactpy_reconnect_backoff_multiplier","title":"REACTPY_RECONNECT_BACKOFF_MULTIPLIER","text":"Default: 1.25
Example Value(s): 1, 1.5, 3
On each reconnection attempt, the REACTPY_RECONNECT_INTERVAL will be multiplied by this value to increase the time between attempts.
You can keep time between each reconnection the same by setting this to 1.
REACTPY_RECONNECT_MAX_INTERVAL","text":"Default: 60000
Example Value(s): 10000, 25000, 900000
Maximum milliseconds between client reconnection attempts.
This allows setting an upper bound on how high REACTPY_RECONNECT_BACKOFF_MULTIPLIER can increase the time between reconnection attempts.
REACTPY_RECONNECT_MAX_RETRIES","text":"Default: 150
Example Value(s): 0, 5, 300
Maximum number of reconnection attempts before the client gives up.
"},{"location":"reference/settings/#reactpy_session_max_age","title":"REACTPY_SESSION_MAX_AGE","text":"Default: 259200
Example Value(s): 0, 60, 96000
Maximum seconds to store ReactPy component sessions.
ReactPy sessions include data such as *args and **kwargs passed into your {% component %} template tag.
Use 0 to not store any session data.
Django template tags can be used within your HTML templates to provide ReactPy features.
"},{"location":"reference/template-tag/#component","title":"Component","text":"This template tag can be used to insert any number of ReactPy components onto your page.
my-template.html{% load reactpy %}\n<!DOCTYPE html>\n<html>\n <body>\n{% component \"example_project.my_app.components.hello_world\" recipient=\"World\" %}\n </body>\n</html>\nParameters
Name Type Description Defaultdotted_path str The dotted path to the component to render. N/A *args Any The positional arguments to provide to the component. N/A class str | None The HTML class to apply to the top-level component div. None key Any Force the component's root node to use a specific key value. Using key within a template tag is effectively useless. None host str | None The host to use for the ReactPy connections. If unset, the host will be automatically configured.Example values include: localhost:8000, example.com, example.com/subdir None prerender str If \"True\", the component will pre-rendered, which enables SEO compatibility and reduces perceived latency. \"False\" **kwargs Any The keyword arguments to provide to the component. N/A Returns
Type DescriptionComponent A ReactPy component. Do not use context variables for the component path The ReactPy component finder (reactpy_django.utils.RootComponentFinder) requires that your component path is a string.
Do not use Django template/context variables for the component path. Failure to follow this warning can result in unexpected behavior, such as components that will not render.
For example, do not do the following:
my-template.htmlviews.py<!-- This is good -->\n{% component \"example_project.my_app.components.hello_world\" recipient=\"World\" %}\n\n<!-- This is bad -->\n{% component my_variable recipient=\"World\" %}\nfrom django.shortcuts import render\n\n\ndef example_view(request):\n context_vars = {\"my_variable\": \"example_project.my_app.components.hello_world\"}\n return render(request, \"my-template.html\", context_vars)\nYes! By using the host keyword argument, you can render components from a completely separate ASGI server.
...\n{% component \"example_project.my_app.components.do_something\" host=\"127.0.0.1:8001\" %}\n...\nThis configuration most commonly involves you deploying multiple instances of your project. But, you can also create dedicated Django project(s) that only render specific ReactPy components if you wish.
Here's a couple of things to keep in mind:
origin1.com != origin2.com ) you will need to configure CORS headers on your main application during deployment.*args/**kwargs if your applications share a common database.You can add as many components to a webpage as needed by using the template tag multiple times. Retrofitting legacy sites to use ReactPy will typically involve many components on one page.
my-template.html{% load reactpy %}\n<!DOCTYPE html>\n<html>\n <body>\n <h1>{% component \"example_project.my_app.components.my_title\" %}</h1>\n <p>{% component \"example_project.my_app_2.components.goodbye_world\" class=\"bold small-font\" %}</p>\n{% component \"example_project.my_app_3.components.simple_button\" %}\n </body>\n</html>\nPlease note that components separated like this will not be able to interact with each other, except through database queries.
Additionally, in scenarios where you are trying to create a Single Page Application (SPA) within Django, you will only have one component within your <body> tag.
You can use any combination of *args/**kwargs in your template tag.
{% component \"example_project.my_app.components.frog_greeter\" 123 \"Mr. Froggles\" species=\"Grey Treefrog\" %}\nfrom reactpy import component\n\n\n@component\ndef frog_greeter(number, name, species=\"\"):\n return f\"Hello #{number}, {name} the {species}!\"\nUtility functions provide various miscellaneous functionality. These are typically not used, but are available for advanced use cases.
"},{"location":"reference/utils/#django-query-postprocessor","title":"Django Query Postprocessor","text":"This is the default postprocessor for the use_query hook.
This postprocessor is designed to avoid Django's SynchronousOnlyException by recursively fetching all fields within a Model or QuerySet to prevent lazy execution.
from example.models import TodoItem\nfrom reactpy import component\nfrom reactpy_django.hooks import use_query\nfrom reactpy_django.types import QueryOptions\nfrom reactpy_django.utils import django_query_postprocessor\n\n\ndef get_items():\n return TodoItem.objects.all()\n\n\n@component\ndef todo_list():\n # These `QueryOptions` are functionally equivalent to ReactPy-Django's default values\n item_query = use_query(\n QueryOptions(\n postprocessor=django_query_postprocessor,\n postprocessor_kwargs={\"many_to_many\": True, \"many_to_one\": True},\n ),\n get_items,\n )\n\n return item_query.data\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nParameters
Name Type Description Defaultdata QuerySet | Model The Model or QuerySet to recursively fetch fields from. N/A many_to_many bool Whether or not to recursively fetch ManyToManyField relationships. True many_to_one bool Whether or not to recursively fetch ForeignKey relationships. True Returns
Type DescriptionQuerySet | Model The Model or QuerySet with all fields fetched."},{"location":"reference/utils/#register-component","title":"Register Component","text":"This function is used manually register a root component with ReactPy.
apps.pyfrom django.apps import AppConfig\nfrom reactpy_django.utils import register_component\n\n\nclass ExampleConfig(AppConfig):\n def ready(self):\n # Add components to the ReactPy component registry when Django is ready\n register_component(\"example_project.my_app.components.hello_world\")\nMyAppConfig.ready() You should always call register_component within a Django MyAppConfig.ready() method. This ensures you will retain multiprocessing compatibility, such as with ASGI web server workers.
You typically will not need to use this function.
For security reasons, ReactPy does not allow non-registered components to be root components. However, all components contained within Django templates are automatically considered root components.
This is typically only needed when you have a dedicated Django application as a rendering server that doesn't have templates, such as when modifying the template tag host argument. On this dedicated rendering server, you would need to manually register your components.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
"},{"location":"about/changelog/#unreleased","title":"Unreleased","text":""},{"location":"about/changelog/#added","title":"Added","text":"settings.py:REACTPY_PRERENDER can be set to True to enable this behavior by default{% component \"...\" prerender=\"True\" %}reactpy_django.utils.ComponentPreloader to reactpy_django.utils.RootComponentFinder.Suspicious position of 'reactpy_django' in INSTALLED_APPS) has been added.REACTPY_DEFAULT_QUERY_POSTPROCESSOR to None.REACTPY_RECONNECT_INTERVALREACTPY_RECONNECT_MAX_INTERVALREACTPY_RECONNECT_MAX_RETRIESREACTPY_RECONNECT_BACKOFF_MULTIPLIER1.0.2.args/kwargs if settings.py:DEBUG is enabled.@reactpy/client version to 0.3.14.2.settings.py:REACTPY_RECONNECT_MAX is removed. See the docs for the new REACTPY_RECONNECT_* settings.REACTPY_DEFAULT_HOSTS setting can round-robin a list of ReactPy rendering hosts.host argument has been added to the component template tag to force components to render on a specific host.reactpy_django.utils.register_component function can manually register root components.reactpy_django.REACTPY_WEBSOCKET_PATH is deprecated. The identical replacement is REACTPY_WEBSOCKET_ROUTE.settings.py:REACTPY_WEBSOCKET_URL is deprecated. The similar replacement is REACTPY_URL_PREFIX.REACTPY_WEBSOCKET_URL doesn't end with a slash) has been removed. ReactPy now automatically handles slashes.REACTPY_WEBSOCKET_URL doesn't start with an alphanumeric character) has been removed. ReactPy now automatically handles this scenario.channels is not in settings.py:INSTALLED_APPS) has been removed. Newer versions of channels do not require installation via INSTALLED_APPS to receive an ASGI web server.orjson resulting in an ~6% overall performance improvement.asyncio event loops are now patched via nest_asyncio, resulting in an ~10% overall performance improvement. This has no performance impact if you are running your web server with uvloop.REACTPY_WEBSOCKET_URL always generates a warning if unset.assert f is self._write_fut would be raised by uvicorn when REACTPY_BACKHAUL_THREAD = True.daphne when REACTPY_BACKHAUL_THREAD = True.REACTPY_BACKHAUL_THREAD now defaults to False.REACTPY_BACKHAUL_THREAD setting to enable/disable threading behavior.settings.py:REACTPY_DATABASE, reactpy_django.database.Router must now be registered in settings.py:DATABASE_ROUTERS.3.9settings.py:DEBUG is enabled.component template tag from causing the whole template to fail to render.DEBUG mode.REACTPY_AUTH_BACKEND setting to allow for custom authentication backends.SessionMiddlewareStack is now optional.AuthMiddlewareStack is now optional.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.mutate argument on reactpy_django.hooks.use_mutation has been renamed to mutation.django-reactpy database entries are no longer cleaned during Django application startup. Instead, it will occur on webpage loads if REACTPY_RECONNECT_MAX seconds has elapsed since the last cleaning.django-idom has been renamed to reactpy-django! Please note that all references to the word idom in your code should be changed to reactpy. See the docs for more details.This is Django-IDOM's biggest update yet!
To upgrade from previous version you will need to...
django-idom >= 3.0.0idom rewrite-keys <DIR> and idom rewrite-camel-case-props <DIR> to update your idom.html.* calls to the new syntaxpython manage.py migrate to create the new Django-IDOM database entriesidom client will automatically configure itself to debug mode depending on settings.py:DEBUG.use_connection hook for returning the browser's active Connection.IDOM_CACHE is now configurable within settings.py to whatever cache name you wish.manage.py migrate after installing IDOM.idom.html.*...snake_case. For example className now becomes class_name.key=... is now declared within the props dict (rather than as a kwarg).component template tag now supports both positional and keyword arguments.component template tag now supports non-serializable arguments.IDOM_WS_MAX_RECONNECT_TIMEOUT setting has been renamed to IDOM_RECONNECT_MAX.django_idom.hooks.use_websocket has been removed. The similar replacement is django_idom.hooks.use_connection.django_idom.types.IdomWebsocket has been removed. The similar replacement is django_idom.types.Connection.settings.py:CACHE['idom'] is no longer used by default. The name of the cache back-end must now be specified with the IDOM_CACHE setting.view_to_component will now retain the contents of a <head> tag when rendering.production rather than development.use_query will now utilize field.related_name when postprocessing many-to-one relationships.settings.py:DEBUG.use_query would not recursively fetch many-to-one relationships.options: QueryOptions parameter to use_query to allow for configuration of this hook.use_query will recursively prefetch all many-to-many or many-to-one relationships to prevent SynchronousOnlyOperation exceptions.django_idom.hooks._fetch_lazy_fields has been deleted. The equivalent replacement is django_idom.utils.django_query_postprocessor.channels version is now 4.0.0.view_to_component callable to have request argument be optional.view_to_component to represent it as a decorator with parenthesis (such as @view_to_component(compatibility=True))view_to_component when using compatibility=True.key=... parameter on all prefabricated components.use_origin hook for returning the browser's location.origin.view_to_component now returns a Callable, instead of directly returning a Component. Check the docs for new usage info.use_mutation and use_query will now log any query failures.use_mutation to have refetch=None, as the docs suggest is possible.use_query will now prefetch all fields to prevent SynchronousOnlyOperation exceptions.view_to_component, django_css, and django_js type hints will now display like normal functions.auth_required decorator to prevent your components from rendering to unauthenticated users.use_query hook for fetching database values.use_mutation hook for modifying database values.view_to_component utility to convert legacy Django views to IDOM components.playwright instead of seleniumdjango_css and django_js components to defer loading CSS & JS files until needed.use_websocket, use_scope, and use_location are now available within the django_idom.hooks module.idom_component template tag has been renamed to componentwebsocket parameter for components has been removed. Functionally, it is replaced with django_idom.hooks.use_websocket.idom.core.proto caused by IDOM 0.37.2divname = ... parameter to IDOM HTTP paths for use with django.urls.reverse()IdomWebsocketdjango_idom/ parent folder0.36.04.03.8IDOM_WEB_MODULES_PATH has been replaced with Django include(...)IDOM_WS_MAX_RECONNECT_DELAY has been renamed to IDOM_WS_MAX_RECONNECT_TIMEOUTidom_web_modules cache back-end has been renamed to idomYou will need to set up a Python environment to develop ReactPy-Django.
Note
Looking to contribute features that are not Django specific?
Everything within the reactpy-django repository must be specific to Django integration. Check out the ReactPy Core documentation to contribute general features such as components, hooks, and events.
If you plan to make code changes to this repository, you will need to install the following dependencies first:
Once done, you should clone this repository:
git clone https://github.com/reactive-python/reactpy-django.git\ncd reactpy-django\nThen, by running the command below you can:
pip install -e . -r requirements.txt --verbose --upgrade\nPitfall
Some of our development dependencies require a C++ compiler, which is not installed by default on Windows.
If you receive errors related to this during installation, follow the instructions in your console errors.
Finally, to verify that everything is working properly, you can manually run the test web server.
cd tests\npython manage.py runserver\nNavigate to http://127.0.0.1:8000 to see if the tests are rendering correctly.
Now, you can create/modify the ReactPy-Django source code, and Pull Request (PR) your changes to our GitHub repository.
To learn how to create GitHub PRs, click here.
"},{"location":"about/code/#running-the-full-test-suite","title":"Running the full test suite","text":"Note
This repository uses Nox to run tests. For a full test of available scripts run nox -l.
By running the command below you can run the full test suite:
nox -s test\nOr, if you want to run the tests in the background:
nox -s test -- --headless\nIf you want to only run our Django tests in your current environment, you can use the following command:
cd tests\npython manage.py test\nIf you want to manually run the Django test application, you can use the following command:
cd tests\npython manage.py runserver\nYou will need to set up a Python environment to create, test, and preview docs changes.
"},{"location":"about/docs/#modifying-docs","title":"Modifying Docs","text":"If you plan to make changes to this documentation, you will need to install the following dependencies first:
Once done, you should clone this repository:
git clone https://github.com/reactive-python/reactpy-django.git\ncd reactpy-django\nThen, by running the command below you can:
pip install -r requirements.txt --upgrade\nFinally, to verify that everything is working properly, you can manually run the docs preview web server.
mkdocs serve\nNavigate to http://127.0.0.1:8000 to view a preview of the documentation.
Now, you can create/modify the ReactPy-Django source code, and Pull Request (PR) your changes to our GitHub repository.
To learn how to create GitHub PRs, click here.
"},{"location":"about/license/","title":"License","text":""},{"location":"about/license/#the-mit-license-mit","title":"The MIT License (MIT)","text":""},{"location":"about/license/#copyright-c-reactive-python-and-affiliates","title":"Copyright (c) Reactive Python and affiliates.","text":"Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"},{"location":"learn/add-reactpy-to-a-django-project/","title":"Add ReactPy to a Django Project","text":""},{"location":"learn/add-reactpy-to-a-django-project/#overview","title":"Overview","text":"If you want to add some interactivity to your existing Django project, you don't have to rewrite it in ReactPy. Use ReactPy-Django to add ReactPy to your existing stack, and render interactive components anywhere.
Note
These docs assumes you have already created a Django project, which involves creating and installing at least one Django app.
If do not have a Django project, check out this 9 minute YouTube tutorial created by IDG TECHtalk.
"},{"location":"learn/add-reactpy-to-a-django-project/#step-1-install-from-pypi","title":"Step 1: Install from PyPI","text":"Run the following command to install reactpy-django in your Python environment.
pip install reactpy-django\nsettings.py","text":"Add \"reactpy_django\" to INSTALLED_APPS in your settings.py file.
INSTALLED_APPS = [\n ...,\n \"reactpy_django\",\n]\nReactPy-Django requires Django ASGI and Django Channels WebSockets.
If you have not enabled ASGI on your Django project yet, here is a summary of the django and channels installation docs:
channels[daphne]Add \"daphne\" to INSTALLED_APPS.
INSTALLED_APPS = [\n \"daphne\",\n ...,\n]\nSet your ASGI_APPLICATION variable.
ASGI_APPLICATION = \"example_project.asgi.application\"\nReactPy's has additional configuration available to fit a variety of use cases.
See the ReactPy settings documentation to learn more.
"},{"location":"learn/add-reactpy-to-a-django-project/#step-3-configure-urlspy","title":"Step 3: Configureurls.py","text":"Add ReactPy HTTP paths to your urlpatterns in your urls.py file.
from django.urls import include, path\n\nurlpatterns = [\n ...,\n path(\"reactpy/\", include(\"reactpy_django.http.urls\")),\n]\nasgi.py","text":"Register ReactPy's WebSocket using REACTPY_WEBSOCKET_ROUTE in your asgi.py file.
import os\n\nfrom django.core.asgi import get_asgi_application\n\n# Ensure DJANGO_SETTINGS_MODULE is set properly based on your project name!\nos.environ.setdefault(\"DJANGO_SETTINGS_MODULE\", \"example_project.settings\")\n\n# Fetch ASGI application before importing dependencies that require ORM models.\ndjango_asgi_app = get_asgi_application()\n\n\nfrom channels.routing import ProtocolTypeRouter, URLRouter # noqa: E402\nfrom reactpy_django import REACTPY_WEBSOCKET_ROUTE # noqa: E402\n\napplication = ProtocolTypeRouter(\n {\n \"http\": django_asgi_app,\n \"websocket\": URLRouter([REACTPY_WEBSOCKET_ROUTE]),\n }\n)\nAuthMiddlewareStack and SessionMiddlewareStack (Optional) There are many situations where you need to access the Django User or Session objects within ReactPy components. For example, if you want to:
User that is currently logged inUserSession objectIn these situations will need to ensure you are using AuthMiddlewareStack and/or SessionMiddlewareStack.
from channels.auth import AuthMiddlewareStack # noqa: E402\nfrom channels.sessions import SessionMiddlewareStack # noqa: E402\n\napplication = ProtocolTypeRouter(\n {\n \"http\": django_asgi_app,\n \"websocket\": SessionMiddlewareStack(\n AuthMiddlewareStack(\n URLRouter(\n [REACTPY_WEBSOCKET_ROUTE],\n )\n )\n ),\n }\n)\nasgi.py? If you do not have an asgi.py, follow the channels installation guide.
Run Django's migrate command to initialize ReactPy-Django's database table.
python manage.py migrate\nRun Django's check command to verify if ReactPy was set up correctly.
python manage.py check\nThe next step will show you how to create your first ReactPy component.
Prefer a quick summary? Read the At a Glance section below.
At a Glance: Your First Component
my_app/components.py
You will need a file to define your ReactPy components. We recommend creating a components.py file within your chosen Django app to start out. Within this file, we will create a simple hello_world component.
from reactpy import component, html\n\n@component\ndef hello_world(recipient: str):\n return html.h1(f\"Hello {recipient}!\")\nmy_app/templates/my-template.html
In your Django app's HTML template, you can now embed your ReactPy component using the component template tag. Within this tag, you will need to type in the dotted path to the component.
Additionally, you can pass in args and kwargs into your component function. After reading the code below, pay attention to how the function definition for hello_world (from the previous example) accepts a recipient argument.
{% load reactpy %}\n<!DOCTYPE html>\n<html>\n <body>\n{% component \"example_project.my_app.components.hello_world\" recipient=\"World\" %}\n </body>\n</html>\nComponents are one of the core concepts of ReactPy. They are the foundation upon which you build user interfaces (UI), which makes them the perfect place to start your journey!
Note
If you have reached this point, you should have already installed ReactPy-Django through the previous steps.
"},{"location":"learn/your-first-component/#selecting-a-django-app","title":"Selecting a Django App","text":"You will now need to pick at least one Django app to start using ReactPy-Django on.
For the following examples, we will assume the following:
my_app, which was created by Django's startapp command.my_app directly into your Django project folder (./example_project/my_app). This is common for small projects.ReactPy-Django has no project structure requirements. Organize everything as you wish, just like any Django project.
"},{"location":"learn/your-first-component/#defining-a-component","title":"Defining a component","text":"You will need a file to start creating ReactPy components.
We recommend creating a components.py file within your chosen Django app to start out. For this example, the file path will look like this: ./example_project/my_app/components.py.
Within this file, you can define your component functions using ReactPy's @component decorator.
from reactpy import component, html\n\n@component\ndef hello_world(recipient: str):\n return html.h1(f\"Hello {recipient}!\")\nYou have full freedom in naming/placement of your files and functions.
We recommend creating a components.py for small Django apps. If your app has a lot of components, you should consider breaking them apart into individual modules such as components/navbar.py.
Ultimately, components are referenced by Python dotted path in my-template.html (see next step). This path must be valid to Python's importlib.
While not all components need to be decorated, there are a few features this decorator adds to your components.
In your Django app's HTML template, you can now embed your ReactPy component using the {% component %} template tag. Within this tag, you will need to type in the dotted path to the component.
Additionally, you can pass in args and kwargs into your component function. After reading the code below, pay attention to how the function definition for hello_world (from the previous step) accepts a recipient argument.
{% load reactpy %}\n<!DOCTYPE html>\n<html>\n <body>\n{% component \"example_project.my_app.components.hello_world\" recipient=\"World\" %}\n </body>\n</html>\nThe ReactPy component finder requires that your component path is a string.
Do not use Django template/context variables for the component path. Failure to follow this warning can result in unexpected behavior, such as components that will not render.
For example, do not do the following:
my-template.htmlviews.py<!-- This is good -->\n{% component \"example_project.my_app.components.hello_world\" recipient=\"World\" %}\n\n<!-- This is bad -->\n{% component my_variable recipient=\"World\" %}\nfrom django.shortcuts import render\n\n\ndef example_view(request):\n context_vars = {\"my_variable\": \"example_project.my_app.components.hello_world\"}\n return render(request, \"my-template.html\", context_vars)\nYou can add as many components to a webpage as needed by using the template tag multiple times. Retrofitting legacy sites to use ReactPy will typically involve many components on one page.
my-template.html{% load reactpy %}\n<!DOCTYPE html>\n<html>\n <body>\n <h1>{% component \"example_project.my_app.components.my_title\" %}</h1>\n <p>{% component \"example_project.my_app_2.components.goodbye_world\" class=\"bold small-font\" %}</p>\n{% component \"example_project.my_app_3.components.simple_button\" %}\n </body>\n</html>\nPlease note that components separated like this will not be able to interact with each other, except through database queries.
Additionally, in scenarios where you are trying to create a Single Page Application (SPA) within Django, you will only have one component within your <body> tag.
If you do not have a ./templates/ folder in your Django app, you can simply create one! Keep in mind, templates within this folder will not be detected by Django unless you add the corresponding Django app to settings.py:INSTALLED_APPS.
Within your Django app's views.py file, you will need to create a view function to render the HTML template my-template.html (from the previous step).
from django.shortcuts import render\n\n\ndef index(request):\n return render(request, \"my-template.html\")\nWe will add this new view into your urls.py and define what URL it should be accessible at.
from django.urls import path\nfrom example import views\n\nurlpatterns = [\n path(\"example/\", views.index),\n]\nFor 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.
Once you reach that point, we recommend creating an individual urls.py within each of your Django apps.
Then, within your Django project's urls.py you will use Django's include function to link it all together.
To test your new Django view, run the following command to start up a development web server.
python manage.py runserver\nNow you can navigate to your Django project URL that contains a 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\".
Do not usemanage.py runserver for production This command is only intended for development purposes. For production deployments make sure to read Django's documentation.
"},{"location":"learn/your-first-component/#learn-more","title":"Learn more","text":"Congratulations! If you followed the previous steps, you have now created a \"Hello World\" component using ReactPy-Django!
Deep Dive
The docs you are reading only covers our Django integration. To learn more, check out one of the following links:
Additionally, the vast majority of tutorials/guides you find for ReactJS can be applied to ReactPy.
"},{"location":"reference/components/","title":"Components","text":""},{"location":"reference/components/#overview","title":"Overview","text":"We supply some pre-designed that components can be used to help simplify development.
"},{"location":"reference/components/#view-to-component","title":"View To Component","text":"Convert any Django view into a ReactPy component by using this decorator. Compatible with Function Based Views and Class Based Views. Views can be sync or async.
components.pyfrom django.http import HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component\ndef hello_world_view(request):\n return HttpResponse(\"Hello World!\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(),\n )\nParameters
Name Type Description Defaultview Callable | View The view function or class to convert. N/A compatibility bool If True, the component will be rendered in an iframe. When using compatibility mode tranforms, strict_parsing, request, args, and kwargs arguments will be ignored. False transforms Sequence[Callable[[VdomDict], Any]] A list of functions that transforms the newly generated VDOM. The functions will be called on each VDOM node. tuple strict_parsing bool If True, an exception will be generated if the HTML does not perfectly adhere to HTML5. True Returns
Type Description_ViewComponentConstructor A function that takes request, *args, key, **kwargs and returns a ReactPy component. All parameters are directly provided to your view, besides key which is used by ReactPy. Potential information exposure when using compatibility = True When using compatibility mode, ReactPy automatically exposes a URL to your view.
It is your responsibility to ensure privileged information is not leaked via this method.
You must implement a method to ensure only authorized users can access your view. This can be done via directly writing conditionals into your view, or by adding decorators such as user_passes_test to your views. For example...
from django.contrib.auth.decorators import user_passes_test\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component(compatibility=True)\n@user_passes_test(lambda u: u.is_superuser) # type: ignore[union-attr]\ndef example_view(request):\n ...\nfrom django.contrib.auth.decorators import user_passes_test\nfrom django.utils.decorators import method_decorator\nfrom django.views.generic import TemplateView\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component(compatibility=True)\n@method_decorator(user_passes_test(lambda u: u.is_superuser), name=\"dispatch\") # type: ignore[union-attr]\nclass ExampleView(TemplateView):\n ...\nThere are currently several limitations of using view_to_component that may be resolved in a future version.
GET.<a href='example/'></a>) click events.Please note these limitations do not exist when using compatibility mode.
You can simply pass your Class Based View directly into view_to_component.
from django.http import HttpResponse\nfrom django.views import View\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\nclass HelloWorldView(View):\n def get(self, request):\n return HttpResponse(\"Hello World!\")\n\n\nvtc = view_to_component(HelloWorldView)\n\n\n@component\ndef my_component():\n return html.div(\n vtc(),\n )\nIn order to convert external views, you can utilize view_to_component as a function, rather than a decorator.
from example.views import example_view\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\nexample_vtc = view_to_component(example_view)\n\n\n@component\ndef my_component():\n return html.div(\n example_vtc(),\n )\nrequest, args, and kwargs to a view? Request
You can use the request parameter to provide the view a custom request object.
from django.http import HttpRequest, HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\nexample_request = HttpRequest()\nexample_request.method = \"PUT\"\n\n\n@view_to_component\ndef hello_world_view(request):\n return HttpResponse(f\"Hello World! {request.method}\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(\n example_request,\n ),\n )\nargs and kwargs
You can use the args and kwargs parameters to provide positional and keyworded arguments to a view.
from django.http import HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component\ndef hello_world_view(request, arg1, arg2, key1=None, key2=None):\n return HttpResponse(f\"Hello World! {arg1} {arg2} {key1} {key2}\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(\n None, # Your request object (optional)\n \"value_1\",\n \"value_2\",\n key1=\"abc\",\n key2=\"123\",\n ),\n )\nstrict_parsing, compatibility, and transforms? strict_parsing
By default, an exception will be generated if your view's HTML does not perfectly adhere to HTML5.
However, there are some circumstances where you may not have control over the original HTML, so you may be unable to fix it. Or you may be relying on non-standard HTML tags such as <my-tag> Hello World </my-tag>.
In these scenarios, you may want to rely on best-fit parsing by setting the strict_parsing parameter to False.
from django.http import HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component(strict_parsing=False)\ndef hello_world_view(request):\n return HttpResponse(\"<my-tag> Hello World </my-tag>\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(),\n )\nNote: Best-fit parsing is designed to be similar to how web browsers would handle non-standard or broken HTML.
compatibility
For views that rely on HTTP responses other than GET (such as PUT, POST, PATCH, etc), you should consider using compatibility mode to render your view within an iframe.
Any view can be rendered within compatibility mode. However, the transforms, strict_parsing, request, args, and kwargs arguments do not apply to compatibility mode.
from django.http import HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\n@view_to_component(compatibility=True)\ndef hello_world_view(request):\n return HttpResponse(\"Hello World!\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(),\n )\nNote: By default the compatibility iframe is unstyled, and thus won't look pretty until you add some CSS.
transforms
After your view has been turned into VDOM (python dictionaries), view_to_component will call your transforms functions on every VDOM node.
This allows you to modify your view prior to rendering.
For example, if you are trying to modify the text of a node with a certain id, you can create a transform like such:
from django.http import HttpResponse\nfrom reactpy import component, html\nfrom reactpy_django.components import view_to_component\n\n\ndef example_transform(vdom):\n attributes = vdom.get(\"attributes\")\n if attributes and attributes.get(\"id\") == \"hello-world\":\n vdom[\"children\"][0] = \"Good Bye World!\"\n\n\n@view_to_component(transforms=[example_transform])\ndef hello_world_view(request):\n return HttpResponse(\"<div id='hello-world'> Hello World! <div>\")\n\n\n@component\ndef my_component():\n return html.div(\n hello_world_view(),\n )\nAllows you to defer loading a CSS stylesheet until a component begins rendering. This stylesheet must be stored within Django's static files.
components.pyfrom reactpy import component, html\nfrom reactpy_django.components import django_css\n\n\n@component\ndef my_component():\n return html.div(\n django_css(\"css/buttons.css\"),\n html.button(\"My Button!\"),\n )\nParameters
Name Type Description Defaultstatic_path str The path to the static file. This path is identical to what you would use on Django's {% static %} template tag. N/A key Key | None A key to uniquely identify this component which is unique amongst a component's immediate siblings None Returns
Type DescriptionComponent A ReactPy component. Can I load static CSS using html.link instead? While you can load stylesheets with html.link, keep in mind that loading this way does not ensure load order. Thus, your stylesheet will be loaded after your component is displayed. This would likely cause unintended visual behavior, so use this at your own discretion.
Here's an example on what you should avoid doing for Django static files:
from django.templatetags.static import static\nfrom reactpy import component, html\n\n\n@component\ndef my_component():\n return html.div(\n html.link({\"rel\": \"stylesheet\", \"href\": static(\"css/buttons.css\")}),\n html.button(\"My Button!\"),\n )\ndjango_css can only be used with local static files.
For external CSS, you should use html.link.
from reactpy import component, html\n\n\n@component\ndef my_component():\n return html.div(\n html.link(\n {\"rel\": \"stylesheet\", \"href\": \"https://example.com/external-styles.css\"}\n ),\n html.button(\"My Button!\"),\n )\n<head>? Traditionally, stylesheets are loaded in your <head> using Django's {% static %} template tag.
However, to help improve webpage load times you can use this django_css component to defer loading your stylesheet until it is needed.
Allows you to defer loading JavaScript until a component begins rendering. This JavaScript must be stored within Django's static files.
Pitfall
Be mindful of load order! If your JavaScript relies on the component existing on the page, you must place django_js at the bottom of your component.
from reactpy import component, html\nfrom reactpy_django.components import django_js\n\n\n@component\ndef my_component():\n return html.div(\n html.button(\"My Button!\"),\n django_js(\"js/scripts.js\"),\n )\nParameters
Name Type Description Defaultstatic_path str The path to the static file. This path is identical to what you would use on Django's {% static %} template tag. N/A key Key | None A key to uniquely identify this component which is unique amongst a component's immediate siblings None Returns
Type DescriptionComponent A ReactPy component. Can I load static JavaScript using html.script instead? While you can load JavaScript with html.script, keep in mind that loading this way does not ensure load order. Thus, your JavaScript will likely be loaded at an arbitrary time after your component is displayed.
Here's an example on what you should avoid doing for Django static files:
from django.templatetags.static import static\nfrom reactpy import component, html\n\n\n@component\ndef my_component():\n return html.div(\n html.script({\"src\": static(\"js/scripts.js\")}),\n html.button(\"My Button!\"),\n )\ndjango_js can only be used with local static files.
For external JavaScript, you should use html.script.
from reactpy import component, html\n\n\n@component\ndef my_component():\n return html.div(\n html.script({\"src\": \"https://example.com/external-scripts.js\"}),\n html.button(\"My Button!\"),\n )\n<head>? Traditionally, JavaScript is loaded in your <head> using Django's {% static %} template tag.
However, to help improve webpage load times you can use this django_js component to defer loading your JavaScript until it is needed.
Decorator functions can be used within your components.py to help simplify development.
You can limit component access to users with a specific auth_attribute by using this decorator (with or without parentheses).
By default, this decorator checks if the user is logged in and not deactivated (is_active).
This decorator is commonly used to selectively render a component only if a user is_staff or is_superuser.
from reactpy import component, html\nfrom reactpy_django.decorators import auth_required\n\n\n@component\n@auth_required\ndef my_component():\n return html.div(\"I am logged in!\")\nParameters
Name Type Description Defaultauth_attribute str The value to check within the user object. This is checked via getattr(scope[\"user\"], auth_attribute). \"is_active\" fallback ComponentType | VdomDict | None The component or reactpy.html snippet to render if the user is not authenticated. None Returns
Type Description #!python Component` A ReactPy component. #!python VdomDict| A#!python reactpy.html` snippet. #!python None` No component render. How do I render a different component if authentication fails? You can use a component with the fallback argument, as seen below.
from reactpy import component, html\nfrom reactpy_django.decorators import auth_required\n\n\n@component\ndef my_component_fallback():\n return html.div(\"I am NOT logged in!\")\n\n\n@component\n@auth_required(fallback=my_component_fallback)\ndef my_component():\n return html.div(\"I am logged in!\")\nreactpy.html snippet if authentication fails? You can use a reactpy.html snippet with the fallback argument, as seen below.
from reactpy import component, html\nfrom reactpy_django.decorators import auth_required\n\n\n@component\n@auth_required(fallback=html.div(\"I am NOT logged in!\"))\ndef my_component():\n return html.div(\"I am logged in!\")\nis_staff? You can do this by setting auth_attribute=\"is_staff\", as seen blow.
from reactpy import component, html\nfrom reactpy_django.decorators import auth_required\n\n\n@component\n@auth_required(auth_attribute=\"is_staff\")\ndef my_component():\n return html.div(\"I am logged in!\")\nYou will need to be using a custom user model within your Django instance.
For example, if your user model has the field is_really_cool ...
from django.contrib.auth.models import AbstractBaseUser\n\n\nclass CustomUserModel(AbstractBaseUser):\n @property\n def is_really_cool(self):\n return True\n... then you would do the following within your decorator:
components.pyfrom reactpy import component, html\nfrom reactpy_django.decorators import auth_required\n\n\n@component\n@auth_required(auth_attribute=\"is_really_cool\")\ndef my_component():\n return html.div(\"I am logged in!\")\n Prefabricated hooks can be used within your components.py to help simplify development.
Note
Looking for standard React hooks?
This package only contains Django specific hooks. Standard hooks can be found within reactive-python/reactpy.
This hook is used to execute functions in the background and return the result, typically to read data the Django ORM.
The default postprocessor expects your query function to return a Django Model or QuerySet. The postprocessor needs to be changed to execute other types of queries. Query functions can be sync or async.
from channels.db import database_sync_to_async\nfrom example.models import TodoItem\nfrom reactpy import component, html\nfrom reactpy_django.hooks import use_query\n\n\nasync def get_items():\n return await database_sync_to_async(TodoItem.objects.all)()\n\n\n@component\ndef todo_list():\n item_query = use_query(get_items)\n\n if item_query.loading:\n rendered_items = html.h2(\"Loading...\")\n elif item_query.error or not item_query.data:\n rendered_items = html.h2(\"Error when loading!\")\n else:\n rendered_items = html.ul([html.li(item, key=item) for item in item_query.data])\n\n return html.div(\"Rendered items: \", rendered_items)\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nParameters
Name Type Description Defaultoptions QueryOptions | None An optional QueryOptions object that can modify how the query is executed. None query Callable[_Params, _Result | None] A callable that returns a Django Model or QuerySet. N/A *args _Params.args Positional arguments to pass into query. N/A **kwargs _Params.kwargs Keyword arguments to pass into query. N/A Returns
Type DescriptionQuery[_Result | None] An object containing loading/error states, your data (if the query has successfully executed), and a refetch callable that can be used to re-run the query. How can I provide arguments to my query function? *args and **kwargs can be provided to your query function via use_query parameters.
from reactpy import component\nfrom reactpy_django.hooks import use_query\n\n\ndef example_query(value: int, other_value: bool = False):\n ...\n\n\n@component\ndef my_component():\n query = use_query(\n example_query,\n 123,\n other_value=True,\n )\n\n return str(query.data)\nThis hook accepts a options: QueryOptions parameter that can be used to customize behavior.
Below are the settings that can be modified via these QueryOptions.
thread_sensitive
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 docs for more information.
This setting only applies to sync query functions, and will be ignored for async functions.
components.pyfrom reactpy import component\nfrom reactpy_django.hooks import use_query\nfrom reactpy_django.types import QueryOptions\n\n\ndef execute_thread_safe_operation():\n\"\"\"This is an example query function that does some thread-safe operation.\"\"\"\n pass\n\n\n@component\ndef my_component():\n query = use_query(\n QueryOptions(thread_sensitive=False),\n execute_thread_safe_operation,\n )\n\n if query.loading or query.error:\n return None\n\n return str(query.data)\npostprocessor
By default, automatic recursive fetching of ManyToMany or ForeignKey fields is enabled within the django_query_postprocessor. This is needed to prevent SynchronousOnlyOperation exceptions when accessing these fields within your ReactPy components.
However, if you...
use_query with a different ORM... 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.
from reactpy import component\nfrom reactpy_django.hooks import use_query\nfrom reactpy_django.types import QueryOptions\n\n\ndef execute_io_intensive_operation():\n\"\"\"This is an example query function that does something IO intensive.\"\"\"\n pass\n\n\n@component\ndef my_component():\n query = use_query(\n QueryOptions(postprocessor=None),\n execute_io_intensive_operation,\n )\n\n if query.loading or query.error:\n return None\n\n return str(query.data)\nIf you wish to create a custom postprocessor, you will need to create a callable.
The first argument of postprocessor must be the query data. All proceeding arguments are optional postprocessor_kwargs (see below). This postprocessor must return the modified data.
from reactpy import component\nfrom reactpy_django.hooks import use_query\nfrom reactpy_django.types import QueryOptions\n\n\ndef my_postprocessor(data, example_kwarg=True):\n if example_kwarg:\n return data\n\n return dict(data)\n\n\ndef execute_io_intensive_operation():\n\"\"\"This is an example query function that does something IO intensive.\"\"\"\n pass\n\n\n@component\ndef my_component():\n query = use_query(\n QueryOptions(\n postprocessor=my_postprocessor,\n postprocessor_kwargs={\"example_kwarg\": False},\n ),\n execute_io_intensive_operation,\n )\n\n if query.loading or query.error:\n return None\n\n return str(query.data)\npostprocessor_kwargs
By default, automatic recursive fetching of ManyToMany or ForeignKey fields is enabled within the django_query_postprocessor. This is needed to prevent SynchronousOnlyOperation exceptions when accessing these fields within your ReactPy components.
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 use_query hook.
You can disable the prefetching behavior of the default postprocessor (located at reactpy_django.utils.django_query_postprocessor) via the QueryOptions.postprocessor_kwargs parameter.
from example.models import TodoItem\nfrom reactpy import component\nfrom reactpy_django.hooks import use_query\nfrom reactpy_django.types import QueryOptions\n\n\ndef get_model_with_relationships():\n\"\"\"This is an example query function that gets `MyModel` which has a ManyToMany field, and\n additionally other models that have formed a ForeignKey association to `MyModel`.\n\n ManyToMany Field: `many_to_many_field`\n ForeignKey Field: `foreign_key_field_set`\n \"\"\"\n return TodoItem.objects.get(id=1)\n\n\n@component\ndef my_component():\n query = use_query(\n QueryOptions(\n postprocessor_kwargs={\"many_to_many\": False, \"many_to_one\": False}\n ),\n get_model_with_relationships,\n )\n\n if query.loading or query.error or not query.data:\n return None\n\n # By disabling `many_to_many` and `many_to_one`, accessing these fields will now\n # generate a `SynchronousOnlyOperation` exception\n return f\"{query.data.many_to_many_field} {query.data.foriegn_key_field_set}\"\nNote: In Django's ORM design, the field name to access foreign keys is postfixed with _set by default.
Due to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a SynchronousOnlyOperation exception.
These SynchronousOnlyOperation exceptions may be removed in a future version of Django. However, it is best practice to always perform IO operations (such as ORM queries) via hooks to prevent performance issues.
Yes, a use_mutation can be re-performed by calling reset() on your use_mutation instance.
For example, take a look at reset_event below.
from example.models import TodoItem\nfrom reactpy import component, html\nfrom reactpy_django.hooks import use_mutation\n\n\ndef add_item(text: str):\n TodoItem(text=text).save()\n\n\n@component\ndef todo_list():\n item_mutation = use_mutation(add_item)\n\n def reset_event(event):\n item_mutation.reset()\n\n def submit_event(event):\n if event[\"key\"] == \"Enter\":\n item_mutation.execute(text=event[\"target\"][\"value\"])\n\n if item_mutation.loading:\n mutation_status = html.h2(\"Adding...\")\n elif item_mutation.error:\n mutation_status = html.button({\"onClick\": reset_event}, \"Error: Try again!\")\n else:\n mutation_status = html.h2(\"Mutation done.\")\n\n return html.div(\n html.label(\"Add an item:\"),\n html.input({\"type\": \"text\", \"onKeyDown\": submit_event}),\n mutation_status,\n )\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nTodoItem.objects.all()? This design decision was based on Apollo's useQuery hook, but ultimately helps avoid Django's SynchronousOnlyOperation exceptions.
With the Model or QuerySet your function returns, this hook uses the default postprocessor to ensure that all deferred or lazy fields are executed.
This hook is used to modify data in the background, typically to create/update/delete data from the Django ORM.
Mutation functions can return False to prevent executing your refetch function. All other returns are ignored. Mutation functions can be sync or async.
from example.models import TodoItem\nfrom reactpy import component, html\nfrom reactpy_django.hooks import use_mutation\n\n\nasync def add_item(text: str):\n await TodoItem(text=text).asave()\n\n\n@component\ndef todo_list():\n item_mutation = use_mutation(add_item)\n\n def submit_event(event):\n if event[\"key\"] == \"Enter\":\n item_mutation.execute(text=event[\"target\"][\"value\"])\n\n if item_mutation.loading:\n mutation_status = html.h2(\"Adding...\")\n elif item_mutation.error:\n mutation_status = html.h2(\"Error when adding!\")\n else:\n mutation_status = html.h2(\"Mutation done.\")\n\n return html.div(\n html.label(\"Add an item:\"),\n html.input({\"type\": \"text\", \"onKeyDown\": submit_event}),\n mutation_status,\n )\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nParameters
Name Type Description Defaultmutate Callable[_Params, bool | None] A callable that performs Django ORM create, update, or delete functionality. If this function returns False, then your refetch function will not be used. N/A refetch Callable[..., Any] | Sequence[Callable[..., Any]] | None 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. None Returns
Type DescriptionMutation[_Params] An object containing loading/error states, a reset callable that will set loading/error states to defaults, and a execute callable that will run the query. How can I provide arguments to my mutation function? *args and **kwargs can be provided to your mutation function via #!python mutation.execute` parameters.
from reactpy import component\nfrom reactpy_django.hooks import use_mutation\n\n\ndef example_mutation(value: int, other_value: bool = False):\n ...\n\n\n@component\ndef my_component():\n mutation = use_mutation(example_mutation)\n\n mutation.execute(123, other_value=True)\n\n ...\nThis hook accepts a options: MutationOptions parameter that can be used to customize behavior.
Below are the settings that can be modified via these MutationOptions.
thread_sensitive
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 docs for more information.
This setting only applies to sync query functions, and will be ignored for async functions.
components.pyfrom reactpy import component, html\nfrom reactpy_django.hooks import use_mutation\nfrom reactpy_django.types import MutationOptions\n\n\ndef execute_thread_safe_mutation():\n\"\"\"This is an example mutation function that does some thread-safe operation.\"\"\"\n pass\n\n\n@component\ndef my_component():\n item_mutation = use_mutation(\n MutationOptions(thread_sensitive=False),\n execute_thread_safe_mutation,\n )\n\n def submit_event(event):\n if event[\"key\"] == \"Enter\":\n item_mutation.execute(text=event[\"target\"][\"value\"])\n\n if item_mutation.loading or item_mutation.error:\n mutation_status = html.h2(\"Doing something...\")\n elif item_mutation.error:\n mutation_status = html.h2(\"Error!\")\n else:\n mutation_status = html.h2(\"Done.\")\n\n return html.div(\n html.input({\"type\": \"text\", \"onKeyDown\": submit_event}),\n mutation_status,\n )\nDue to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a SynchronousOnlyOperation exception.
These SynchronousOnlyOperation exceptions may be removed in a future version of Django. However, it is best practice to always perform IO operations (such as ORM queries) via hooks to prevent performance issues.
Yes, a use_mutation can be re-performed by calling reset() on your use_mutation instance.
For example, take a look at reset_event below.
from example.models import TodoItem\nfrom reactpy import component, html\nfrom reactpy_django.hooks import use_mutation\n\n\ndef add_item(text: str):\n TodoItem(text=text).save()\n\n\n@component\ndef todo_list():\n item_mutation = use_mutation(add_item)\n\n def reset_event(event):\n item_mutation.reset()\n\n def submit_event(event):\n if event[\"key\"] == \"Enter\":\n item_mutation.execute(text=event[\"target\"][\"value\"])\n\n if item_mutation.loading:\n mutation_status = html.h2(\"Adding...\")\n elif item_mutation.error:\n mutation_status = html.button({\"onClick\": reset_event}, \"Error: Try again!\")\n else:\n mutation_status = html.h2(\"Mutation done.\")\n\n return html.div(\n html.label(\"Add an item:\"),\n html.input({\"type\": \"text\", \"onKeyDown\": submit_event}),\n mutation_status,\n )\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nuse_mutation trigger a refetch of use_query? Yes, use_mutation can queue a refetch of a use_query via the refetch=... argument.
The example below is a merge of the use_query and use_mutation examples above with the addition of a use_mutation(refetch=...) argument.
Please note that refetch will cause all use_query hooks that use get_items in the current component tree will be refetched.
from example.models import TodoItem\nfrom reactpy import component, html\nfrom reactpy_django.hooks import use_mutation, use_query\n\n\ndef get_items():\n return TodoItem.objects.all()\n\n\ndef add_item(text: str):\n TodoItem(text=text).save()\n\n\n@component\ndef todo_list():\n item_query = use_query(get_items)\n item_mutation = use_mutation(add_item, refetch=get_items)\n\n def submit_event(event):\n if event[\"key\"] == \"Enter\":\n item_mutation.execute(text=event[\"target\"][\"value\"])\n\n # Handle all possible query states\n if item_query.loading:\n rendered_items = html.h2(\"Loading...\")\n elif item_query.error or not item_query.data:\n rendered_items = html.h2(\"Error when loading!\")\n else:\n rendered_items = html.ul(html.li(item, key=item) for item in item_query.data)\n\n # Handle all possible mutation states\n if item_mutation.loading:\n mutation_status = html.h2(\"Adding...\")\n elif item_mutation.error:\n mutation_status = html.h2(\"Error when adding!\")\n else:\n mutation_status = html.h2(\"Mutation done.\")\n\n return html.div(\n html.label(\"Add an item:\"),\n html.input({\"type\": \"text\", \"onKeyDown\": submit_event}),\n mutation_status,\n rendered_items,\n )\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nThis hook is used to fetch the active connection, which is either a Django WebSocket or a HTTP Request.
components.pyfrom reactpy import component, html\nfrom reactpy_django.hooks import use_connection\n\n\n@component\ndef my_component():\n my_connection = use_connection()\n return html.div(str(my_connection))\nParameters
None
Returns
Type DescriptionConnection The component's WebSocket or HttpRequest."},{"location":"reference/hooks/#use-scope","title":"Use Scope","text":"This is a shortcut that returns the WebSocket or HTTP scope.
components.pyfrom reactpy import component, html\nfrom reactpy_django.hooks import use_scope\n\n\n@component\ndef my_component():\n my_scope = use_scope()\n return html.div(str(my_scope))\nParameters
None
Returns
Type DescriptionMutableMapping[str, Any] The WebSocket's scope."},{"location":"reference/hooks/#use-location","title":"Use Location","text":"This is a shortcut that returns the client's URL path.
You can expect this hook to provide strings such as /reactpy/my_path.
from reactpy import component, html\nfrom reactpy_django.hooks import use_location\n\n\n@component\ndef my_component():\n my_location = use_location()\n return html.div(str(my_location))\nParameters
None
Returns
Type DescriptionLocation An object containing the current URL's pathname and search query. This hook's behavior will be changed in a future update This hook will be updated to return the browser's currently active HTTP path. This change will come in alongside ReactPy URL routing support.
Check out reactive-python/reactpy-django#147 for more information.
"},{"location":"reference/hooks/#use-origin","title":"Use Origin","text":"This is a shortcut that returns the client's origin.
You can expect this hook to provide strings such as http://example.com.
from reactpy import component, html\nfrom reactpy_django.hooks import use_origin\n\n\n@component\ndef my_component():\n my_origin = use_origin()\n return html.div(my_origin or \"No origin\")\nParameters
None
Returns
Type Descriptionstr | None A string containing the browser's current origin, obtained from WebSocket or HTTP headers (if available)."},{"location":"reference/settings/","title":"Settings","text":""},{"location":"reference/settings/#overview","title":"Overview","text":" These are ReactPy-Django's default settings values. You can modify these values in your Django project's settings.py to change the behavior of ReactPy.
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.
"},{"location":"reference/settings/#general-settings","title":"General Settings","text":""},{"location":"reference/settings/#reactpy_url_prefix","title":"REACTPY_URL_PREFIX","text":"Default: \"reactpy/\"
Example Value(s): \"rp/\", \"render/reactpy/\"
The prefix used for all ReactPy WebSocket and HTTP URLs.
"},{"location":"reference/settings/#reactpy_default_query_postprocessor","title":"REACTPY_DEFAULT_QUERY_POSTPROCESSOR","text":"Default: \"reactpy_django.utils.django_query_postprocessor\"
Example Value(s): \"example_project.postprocessor\", None
Dotted path to the global default reactpy_django.hooks.use_query postprocessor function.
Postprocessor functions can be async or sync. Here is an example of a sync postprocessor function:
def postprocessor(data):\n del data[\"foo\"]\n return data\nSet REACTPY_DEFAULT_QUERY_POSTPROCESSOR to None to disable the default postprocessor.
REACTPY_AUTH_BACKEND","text":"Default: \"django.contrib.auth.backends.ModelBackend\"
Example Value(s): \"example_project.auth.MyModelBackend\"
Dotted path to the Django authentication backend to use for ReactPy components. This is only needed if:
AuthMiddlewareStack and...AUTHENTICATION_BACKENDS setting and...backend attribute.REACTPY_DATABASE","text":"Default: \"default\"
Example Value(s): \"my-reactpy-database\"
Multiprocessing-safe database used by ReactPy, typically for session data.
If configuring this value, it is mandatory to enable our database router like such:
DATABASE_ROUTERS = [\"reactpy_django.database.Router\", ...]\nREACTPY_CACHE","text":"Default: \"default\"
Example Value(s): \"my-reactpy-cache\"
Cache used by ReactPy, typically for file operations.
We recommend configuring redis, python-diskcache, or LocMemCache.
REACTPY_BACKHAUL_THREAD","text":"Default: False
Example Value(s): True
Configures whether ReactPy components are rendered in a dedicated thread.
This setting allows the web server to process other traffic during ReactPy rendering. Vastly improves throughput with web servers such as hypercorn and uvicorn.
REACTPY_DEFAULT_HOSTS","text":"Default: None
Example Value(s): [\"localhost:8000\", \"localhost:8001\", \"localhost:8002/subdir\"]
The default host(s) that can render your ReactPy components.
ReactPy will use these hosts in a round-robin fashion, allowing for easy distributed computing.
You can use the host argument in your template tag to manually override this default.
REACTPY_PRERENDER","text":"Default: False
Example Value(s): True
Configures whether to pre-render your components, which enables SEO compatibility and reduces perceived latency.
During pre-rendering, there are some key differences in behavior:
connection related hooks use HTTP.html.script elements are executed twice (pre-render and post-render).You can use the prerender argument in your template tag to manually override this default.
REACTPY_RECONNECT_INTERVAL","text":"Default: 750
Example Value(s): 100, 2500, 6000
Milliseconds between client reconnection attempts.
"},{"location":"reference/settings/#reactpy_reconnect_backoff_multiplier","title":"REACTPY_RECONNECT_BACKOFF_MULTIPLIER","text":"Default: 1.25
Example Value(s): 1, 1.5, 3
On each reconnection attempt, the REACTPY_RECONNECT_INTERVAL will be multiplied by this value to increase the time between attempts.
You can keep time between each reconnection the same by setting this to 1.
REACTPY_RECONNECT_MAX_INTERVAL","text":"Default: 60000
Example Value(s): 10000, 25000, 900000
Maximum milliseconds between client reconnection attempts.
This allows setting an upper bound on how high REACTPY_RECONNECT_BACKOFF_MULTIPLIER can increase the time between reconnection attempts.
REACTPY_RECONNECT_MAX_RETRIES","text":"Default: 150
Example Value(s): 0, 5, 300
Maximum number of reconnection attempts before the client gives up.
"},{"location":"reference/settings/#reactpy_session_max_age","title":"REACTPY_SESSION_MAX_AGE","text":"Default: 259200
Example Value(s): 0, 60, 96000
Maximum seconds to store ReactPy component sessions.
ReactPy sessions include data such as *args and **kwargs passed into your {% component %} template tag.
Use 0 to not store any session data.
Django template tags can be used within your HTML templates to provide ReactPy features.
"},{"location":"reference/template-tag/#component","title":"Component","text":"This template tag can be used to insert any number of ReactPy components onto your page.
my-template.html{% load reactpy %}\n<!DOCTYPE html>\n<html>\n <body>\n{% component \"example_project.my_app.components.hello_world\" recipient=\"World\" %}\n </body>\n</html>\nParameters
Name Type Description Defaultdotted_path str The dotted path to the component to render. N/A *args Any The positional arguments to provide to the component. N/A class str | None The HTML class to apply to the top-level component div. None key Any Force the component's root node to use a specific key value. Using key within a template tag is effectively useless. None host str | None The host to use for the ReactPy connections. If unset, the host will be automatically configured.Example values include: localhost:8000, example.com, example.com/subdir None prerender str If \"True\", the component will pre-rendered, which enables SEO compatibility and reduces perceived latency. \"False\" **kwargs Any The keyword arguments to provide to the component. N/A Returns
Type DescriptionComponent A ReactPy component. Do not use context variables for the component path The ReactPy component finder requires that your component path is a string.
Do not use Django template/context variables for the component path. Failure to follow this warning can result in unexpected behavior, such as components that will not render.
For example, do not do the following:
my-template.htmlviews.py<!-- This is good -->\n{% component \"example_project.my_app.components.hello_world\" recipient=\"World\" %}\n\n<!-- This is bad -->\n{% component my_variable recipient=\"World\" %}\nfrom django.shortcuts import render\n\n\ndef example_view(request):\n context_vars = {\"my_variable\": \"example_project.my_app.components.hello_world\"}\n return render(request, \"my-template.html\", context_vars)\nYes! By using the host keyword argument, you can render components from a completely separate ASGI server.
...\n{% component \"example_project.my_app.components.do_something\" host=\"127.0.0.1:8001\" %}\n...\nThis configuration most commonly involves you deploying multiple instances of your project. But, you can also create dedicated Django project(s) that only render specific ReactPy components if you wish.
Here's a couple of things to keep in mind:
origin1.com != origin2.com ) you will need to configure CORS headers on your main application during deployment.*args/**kwargs if your applications share a common database.You can add as many components to a webpage as needed by using the template tag multiple times. Retrofitting legacy sites to use ReactPy will typically involve many components on one page.
my-template.html{% load reactpy %}\n<!DOCTYPE html>\n<html>\n <body>\n <h1>{% component \"example_project.my_app.components.my_title\" %}</h1>\n <p>{% component \"example_project.my_app_2.components.goodbye_world\" class=\"bold small-font\" %}</p>\n{% component \"example_project.my_app_3.components.simple_button\" %}\n </body>\n</html>\nPlease note that components separated like this will not be able to interact with each other, except through database queries.
Additionally, in scenarios where you are trying to create a Single Page Application (SPA) within Django, you will only have one component within your <body> tag.
You can use any combination of *args/**kwargs in your template tag.
{% component \"example_project.my_app.components.frog_greeter\" 123 \"Mr. Froggles\" species=\"Grey Treefrog\" %}\nfrom reactpy import component\n\n\n@component\ndef frog_greeter(number, name, species=\"\"):\n return f\"Hello #{number}, {name} the {species}!\"\nUtility functions provide various miscellaneous functionality. These are typically not used, but are available for advanced use cases.
"},{"location":"reference/utils/#django-query-postprocessor","title":"Django Query Postprocessor","text":"This is the default postprocessor for the use_query hook.
This postprocessor is designed to avoid Django's SynchronousOnlyException by recursively fetching all fields within a Model or QuerySet to prevent lazy execution.
from example.models import TodoItem\nfrom reactpy import component\nfrom reactpy_django.hooks import use_query\nfrom reactpy_django.types import QueryOptions\nfrom reactpy_django.utils import django_query_postprocessor\n\n\ndef get_items():\n return TodoItem.objects.all()\n\n\n@component\ndef todo_list():\n # These `QueryOptions` are functionally equivalent to ReactPy-Django's default values\n item_query = use_query(\n QueryOptions(\n postprocessor=django_query_postprocessor,\n postprocessor_kwargs={\"many_to_many\": True, \"many_to_one\": True},\n ),\n get_items,\n )\n\n return item_query.data\nfrom django.db.models import CharField, Model\n\n\nclass TodoItem(Model):\n text: CharField = CharField(max_length=255)\nParameters
Name Type Description Defaultdata QuerySet | Model The Model or QuerySet to recursively fetch fields from. N/A many_to_many bool Whether or not to recursively fetch ManyToManyField relationships. True many_to_one bool Whether or not to recursively fetch ForeignKey relationships. True Returns
Type DescriptionQuerySet | Model The Model or QuerySet with all fields fetched."},{"location":"reference/utils/#register-component","title":"Register Component","text":"This function is used manually register a root component with ReactPy.
apps.pyfrom django.apps import AppConfig\nfrom reactpy_django.utils import register_component\n\n\nclass ExampleConfig(AppConfig):\n def ready(self):\n # Add components to the ReactPy component registry when Django is ready\n register_component(\"example_project.my_app.components.hello_world\")\nMyAppConfig.ready() You should always call register_component within a Django MyAppConfig.ready() method. This ensures you will retain multiprocessing compatibility, such as with ASGI web server workers.
You typically will not need to use this function.
For security reasons, ReactPy requires all root components to be registered. However, all components contained within Django templates are automatically registered.
This function is needed when you have configured your host to a dedicated Django rendering application that doesn't have templates.