From 101f768df4710d839c4124a5c094d30803881ee1 Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Mon, 18 Sep 2023 23:04:54 -0700 Subject: [PATCH 01/13] Docs readability enhancements --- docs/includes/orm.md | 4 +- docs/python/use-mutation-thread-sensitive.py | 32 +++++++ docs/python/use-query-async.py | 22 ----- docs/src/reference/components.md | 28 +++--- docs/src/reference/decorators.md | 2 +- docs/src/reference/hooks.md | 96 +++++++++++++------- docs/src/reference/settings.md | 2 +- docs/src/reference/template-tag.md | 2 +- docs/src/reference/utils.md | 4 +- mkdocs.yml | 3 + 10 files changed, 118 insertions(+), 77 deletions(-) create mode 100644 docs/python/use-mutation-thread-sensitive.py delete mode 100644 docs/python/use-query-async.py diff --git a/docs/includes/orm.md b/docs/includes/orm.md index fafb6226..74f966c0 100644 --- a/docs/includes/orm.md +++ b/docs/includes/orm.md @@ -2,12 +2,12 @@ Due to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a `#!python SynchronousOnlyOperation` exception. -These `#!python 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. +These `#!python 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. -By default, automatic recursive fetching of `#!python ManyToMany` or `#!python ForeignKey` fields is enabled within the default `#!python QueryOptions.postprocessor`. This is needed to prevent `#!python SynchronousOnlyOperation` exceptions when accessing these fields within your ReactPy components. +By default, automatic recursive fetching of `#!python ManyToMany` or `#!python ForeignKey` fields is enabled within the `DjangoQueryPostprocessor`. This is needed to prevent `#!python SynchronousOnlyOperation` exceptions when accessing these fields within your ReactPy components. diff --git a/docs/python/use-mutation-thread-sensitive.py b/docs/python/use-mutation-thread-sensitive.py new file mode 100644 index 00000000..ec07377e --- /dev/null +++ b/docs/python/use-mutation-thread-sensitive.py @@ -0,0 +1,32 @@ +from reactpy import component, html +from reactpy_django.hooks import use_mutation +from reactpy_django.types import MutationOptions + + +def execute_thread_safe_mutation(): + """This is an example mutation function that does some thread-safe operation.""" + pass + + +@component +def my_component(): + item_mutation = use_mutation( + MutationOptions(thread_sensitive=False), + execute_thread_safe_mutation, + ) + + def submit_event(event): + if event["key"] == "Enter": + item_mutation.execute(text=event["target"]["value"]) + + if item_mutation.loading or item_mutation.error: + mutation_status = html.h2("Doing something...") + elif item_mutation.error: + mutation_status = html.h2("Error!") + else: + mutation_status = html.h2("Done.") + + return html.div( + html.input({"type": "text", "onKeyDown": submit_event}), + mutation_status, + ) diff --git a/docs/python/use-query-async.py b/docs/python/use-query-async.py deleted file mode 100644 index e546ed59..00000000 --- a/docs/python/use-query-async.py +++ /dev/null @@ -1,22 +0,0 @@ -from channels.db import database_sync_to_async -from example.models import TodoItem -from reactpy import component, html -from reactpy_django.hooks import use_query - - -async def get_items(): - return await database_sync_to_async(TodoItem.objects.all)() - - -@component -def todo_list(): - item_query = use_query(get_items) - - if item_query.loading: - rendered_items = html.h2("Loading...") - elif item_query.error or not item_query.data: - rendered_items = html.h2("Error when loading!") - else: - rendered_items = html.ul([html.li(item, key=item) for item in item_query.data]) - - return html.div("Rendered items: ", rendered_items) diff --git a/docs/src/reference/components.md b/docs/src/reference/components.md index d3f235da..85199f27 100644 --- a/docs/src/reference/components.md +++ b/docs/src/reference/components.md @@ -177,7 +177,7 @@ Allows you to defer loading a CSS stylesheet until a component begins rendering. | Name | Type | Description | Default | | --- | --- | --- | --- | - | `#!python static_path` | `#!python str` | The path to the static file. This path is identical to what you would use on a `static` template tag. | N/A | + | `#!python static_path` | `#!python str` | The path to the static file. This path is identical to what you would use on Django's `#!jinja {% static %}` template tag. | N/A | | `#!python key` | `#!python Key | None` | A key to uniquely identify this component which is unique amongst a component's immediate siblings | `#!python None` | **Returns** @@ -186,10 +186,6 @@ Allows you to defer loading a CSS stylesheet until a component begins rendering. | --- | --- | | `#!python Component` | A ReactPy component. | -??? question "Should I put `#!python django_css` at the top of my HTML?" - - Yes, if the stylesheet contains styling for your component. - ??? question "Can I load static CSS using `#!python html.link` instead?" While you can load stylesheets with `#!python 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. @@ -204,7 +200,7 @@ Allows you to defer loading a CSS stylesheet until a component begins rendering. `#!python django_css` can only be used with local static files. - For external CSS, substitute `#!python django_css` with `#!python html.link`. + For external CSS, you should use `#!python html.link`. ```python {% include "../../python/django-css-external-link.py" %} @@ -212,14 +208,18 @@ Allows you to defer loading a CSS stylesheet until a component begins rendering. ??? question "Why not load my CSS in `#!html `?" - Traditionally, stylesheets are loaded in your `#!html ` using the `#!jinja {% load static %}` template tag. + Traditionally, stylesheets are loaded in your `#!html ` using Django's `#!jinja {% static %}` template tag. - To help improve webpage load times, you can use the `#!python django_css` component to defer loading your stylesheet until it is needed. + However, to help improve webpage load times you can use this `#!python django_css` component to defer loading your stylesheet until it is needed. ## Django JS Allows you to defer loading JavaScript until a component begins rendering. This JavaScript must be stored within [Django's static files](https://docs.djangoproject.com/en/dev/howto/static-files/). +!!! warning "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. + === "components.py" ```python @@ -232,7 +232,7 @@ Allows you to defer loading JavaScript until a component begins rendering. This | Name | Type | Description | Default | | --- | --- | --- | --- | - | `#!python static_path` | `#!python str` | The path to the static file. This path is identical to what you would use on a `static` template tag. | N/A | + | `#!python static_path` | `#!python str` | The path to the static file. This path is identical to what you would use on Django's `#!jinja {% static %}` template tag. | N/A | | `#!python key` | `#!python Key | None` | A key to uniquely identify this component which is unique amongst a component's immediate siblings | `#!python None` | **Returns** @@ -241,10 +241,6 @@ Allows you to defer loading JavaScript until a component begins rendering. This | --- | --- | | `#!python Component` | A ReactPy component. | -??? question "Should I put `#!python django_js` at the bottom of my HTML?" - - Yes, if your scripts are reliant on the contents of the component. - ??? question "Can I load static JavaScript using `#!python html.script` instead?" While you can load JavaScript with `#!python 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. @@ -259,7 +255,7 @@ Allows you to defer loading JavaScript until a component begins rendering. This `#!python django_js` can only be used with local static files. - For external JavaScript, substitute `#!python django_js` with `#!python html.script`. + For external JavaScript, you should use `#!python html.script`. ```python {% include "../../python/django-js-remote-script.py" %} @@ -267,6 +263,6 @@ Allows you to defer loading JavaScript until a component begins rendering. This ??? question "Why not load my JS in `#!html `?" - Traditionally, JavaScript is loaded in your `#!html ` using the `#!jinja {% load static %}` template tag. + Traditionally, JavaScript is loaded in your `#!html ` using Django's `#!jinja {% static %}` template tag. - To help improve webpage load times, you can use the `#!python django_js` component to defer loading your JavaScript until it is needed. + However, to help improve webpage load times you can use this `#!python django_js` component to defer loading your JavaScript until it is needed. diff --git a/docs/src/reference/decorators.md b/docs/src/reference/decorators.md index 59440366..e5650648 100644 --- a/docs/src/reference/decorators.md +++ b/docs/src/reference/decorators.md @@ -10,7 +10,7 @@ Decorator functions can be used within your `components.py` to help simplify dev ## Auth Required -You can limit access to a component to users with a specific `#!python auth_attribute` by using this decorator (with or without parentheses). +You can limit component access to users with a specific `#!python auth_attribute` by using this decorator (with or without parentheses). By default, this decorator checks if the user is logged in and not deactivated (`#!python is_active`). diff --git a/docs/src/reference/hooks.md b/docs/src/reference/hooks.md index 3233a5bb..bdf36cee 100644 --- a/docs/src/reference/hooks.md +++ b/docs/src/reference/hooks.md @@ -16,9 +16,9 @@ Prefabricated hooks can be used within your `components.py` to help simplify dev ## Use Query -This hook is used [read](https://www.sumologic.com/glossary/crud/) data from the Django ORM. +This hook is used [read](https://www.sumologic.com/glossary/crud/) data, typically from the Django ORM. -The query function you provide must return either a `#!python Model` or `#!python QuerySet`. +The [default postprocessor](../reference/utils.md#django-query-postprocessor) expects your query function to return either a Django `#!python Model` or `#!python QuerySet`. The postprocessor needs to be changed to perform other types of queries. Query functions can be sync or async. === "components.py" @@ -59,13 +59,13 @@ The query function you provide must return either a `#!python Model` or `#!pytho {% include "../../python/use-query-args.py" %} ``` -??? question "Why does `#!python get_items` in the example return `#!python TodoItem.objects.all()`?" +??? question "How can I customize this hook's behavior?" - This was a technical design decision to based on [Apollo's `#!javascript useQuery` hook](https://www.apollographql.com/docs/react/data/queries/), but ultimately helps avoid Django's `#!python SynchronousOnlyOperation` exceptions. + This hook accepts a `#!python options = ...` parameter that can be used to customize its behavior. You can provide a `#!python reactpy_django.types.QueryOptions` object to this parameter to customize the hook's behavior. - The `#!python use_query` hook ensures the provided `#!python Model` or `#!python QuerySet` executes all [deferred](https://docs.djangoproject.com/en/dev/ref/models/instances/#django.db.models.Model.get_deferred_fields)/[lazy queries](https://docs.djangoproject.com/en/dev/topics/db/queries/#querysets-are-lazy) safely prior to reaching your components. + Below are the settings that can be modified via `#!python QueryOptions`. -??? question "How can I use `#!python QueryOptions` to customize fetching behavior?" + --- **`#!python thread_sensitive`** @@ -128,27 +128,39 @@ The query function you provide must return either a `#!python Model` or `#!pytho _Note: In Django's ORM design, the field name to access foreign keys is [postfixed with `_set`](https://docs.djangoproject.com/en/dev/topics/db/examples/many_to_one/) by default._ -??? question "Can I define async query functions?" +??? question "Can I make ORM calls without hooks?" + + {% include-markdown "../../includes/orm.md" start="" end="" %} - Async functions are supported by `#!python use_query`. You can use them in the same way as a sync query function. +??? question "Can I make a failed query try again?" - However, be mindful of Django async ORM restrictions. + Yes, a `#!python use_mutation` can be re-performed by calling `#!python reset()` on your `#!python use_mutation` instance. + + For example, take a look at `#!python reset_event` below. === "components.py" ```python - {% include "../../python/use-query-async.py" %} + {% include "../../python/use-mutation-reset.py" %} ``` -??? question "Can I make ORM calls without hooks?" + === "models.py" - {% include-markdown "../../includes/orm.md" start="" end="" %} + ```python + {% include "../../python/example/models.py" %} + ``` + +??? question "Why does the example query function return `#!python TodoItem.objects.all()`?" + + This design decision was based on [Apollo's `#!javascript useQuery` hook](https://www.apollographql.com/docs/react/data/queries/), but ultimately helps avoid Django's `#!python SynchronousOnlyOperation` exceptions. + + With the `#!python Model` or `#!python QuerySet` your function returns, this hook uses the [default postprocessor](../reference/utils.md#django-query-postprocessor) to ensure that all [deferred](https://docs.djangoproject.com/en/dev/ref/models/instances/#django.db.models.Model.get_deferred_fields) or [lazy](https://docs.djangoproject.com/en/dev/topics/db/queries/#querysets-are-lazy) fields are executed. ## Use Mutation -This hook is used to [create, update, or delete](https://www.sumologic.com/glossary/crud/) Django ORM objects. +This hook is used to [create, update, or delete](https://www.sumologic.com/glossary/crud/) data, typically from the Django ORM. -The mutation function you provide should have no return value. +The mutation function you provide should have no return value. Mutation functions can be sync or async. === "components.py" @@ -187,27 +199,31 @@ The mutation function you provide should have no return value. {% include "../../python/use-mutation-args-kwargs.py" %} ``` -??? question "Can `#!python use_mutation` trigger a refetch of `#!python use_query`?" +??? question "How can I customize this hook's behavior?" - Yes, `#!python use_mutation` can queue a refetch of a `#!python use_query` via the `#!python refetch=...` argument. + This hook accepts a `#!python options = ...` parameter that can be used to customize its behavior. You can provide a `#!python reactpy_django.types.MutationOptions` object to this parameter to customize the hook's behavior. - The example below is a merge of the `#!python use_query` and `#!python use_mutation` examples above with the addition of a `#!python use_mutation(refetch=...)` argument. + Below are the settings that can be modified via `#!python MutationOptions`. - Please note that any `#!python use_query` hooks that use `#!python get_items` will be refetched upon a successful mutation. + --- + + **`#!python 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 [`#!python sync_to_async` docs](https://docs.djangoproject.com/en/dev/topics/async/#sync-to-async) docs for more information. + + This setting only applies to sync query functions, and will be ignored for async functions. === "components.py" ```python - {% include "../../python/use-mutation-query-refetch.py" %} + {% include "../../python/use-mutation-thread-sensitive.py" %} ``` - === "models.py" +??? question "Can I make ORM calls without hooks?" - ```python - {% include "../../python/example/models.py" %} - ``` + {% include-markdown "../../includes/orm.md" start="" end="" %} -??? question "Can I make a failed `#!python use_mutation` try again?" +??? question "Can I make a failed mutation try again?" Yes, a `#!python use_mutation` can be re-performed by calling `#!python reset()` on your `#!python use_mutation` instance. @@ -225,13 +241,29 @@ The mutation function you provide should have no return value. {% include "../../python/example/models.py" %} ``` -??? question "Can I make ORM calls without hooks?" +??? question "Can `#!python use_mutation` trigger a refetch of `#!python use_query`?" - {% include-markdown "../../includes/orm.md" start="" end="" %} + Yes, `#!python use_mutation` can queue a refetch of a `#!python use_query` via the `#!python refetch=...` argument. + + The example below is a merge of the `#!python use_query` and `#!python use_mutation` examples above with the addition of a `#!python use_mutation(refetch=...)` argument. + + Please note that `refetch` will cause all `#!python use_query` hooks that use `#!python get_items` in the current component tree will be refetched. + + === "components.py" + + ```python + {% include "../../python/use-mutation-query-refetch.py" %} + ``` + + === "models.py" + + ```python + {% include "../../python/example/models.py" %} + ``` ## Use Connection -This hook is used to fetch the Django Channels [WebSocket](https://channels.readthedocs.io/en/stable/topics/consumers.html#asyncjsonwebsocketconsumer). +This hook is used to fetch the active connection, which is either a Django [WebSocket](https://channels.readthedocs.io/en/stable/topics/consumers.html#asyncjsonwebsocketconsumer) or a [HTTP Request](https://docs.djangoproject.com/en/4.2/ref/request-response/#django.http.HttpRequest). === "components.py" @@ -249,11 +281,11 @@ This hook is used to fetch the Django Channels [WebSocket](https://channels.read | Type | Description | | --- | --- | - | `#!python Connection` | The component's WebSocket. | + | `#!python Connection` | The component's `WebSocket` or `HttpRequest`. | ## Use Scope -This is a shortcut that returns the WebSocket's [`#!python scope`](https://channels.readthedocs.io/en/stable/topics/consumers.html#scope). +This is a shortcut that returns the HTTP or WebSocket [`#!python scope`](https://channels.readthedocs.io/en/stable/topics/consumers.html#scope). === "components.py" @@ -275,7 +307,7 @@ This is a shortcut that returns the WebSocket's [`#!python scope`](https://chann ## Use Location -This is a shortcut that returns the WebSocket's `#!python path`. +This is a shortcut that returns the client's `#!python path`. You can expect this hook to provide strings such as `/reactpy/my_path`. @@ -299,7 +331,7 @@ You can expect this hook to provide strings such as `/reactpy/my_path`. ??? info "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. + This hook will be updated to always 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](https://github.com/reactive-python/reactpy-django/issues/147) for more information. @@ -325,4 +357,4 @@ You can expect this hook to provide strings such as `http://example.com`. | Type | Description | | --- | --- | - | `#!python str | None` | A string containing the browser's current origin, obtained from WebSocket headers (if available). | + | `#!python str | None` | A string containing the browser's current origin, obtained from WebSocket or HTTP headers (if available). | diff --git a/docs/src/reference/settings.md b/docs/src/reference/settings.md index 35f65b6e..46ed7070 100644 --- a/docs/src/reference/settings.md +++ b/docs/src/reference/settings.md @@ -34,7 +34,7 @@ The prefix used for all ReactPy WebSocket and HTTP URLs. **Example Value(s):** `#!python "example_project.postprocessor"`, `#!python None` -Dotted path to the default `#!python reactpy_django.hooks.use_query` postprocessor function. +Dotted path to the global default `#!python reactpy_django.hooks.use_query` postprocessor function. Postprocessor functions can be async or sync. Here is an example of a sync postprocessor function: diff --git a/docs/src/reference/template-tag.md b/docs/src/reference/template-tag.md index 39974eb7..8fdb5695 100644 --- a/docs/src/reference/template-tag.md +++ b/docs/src/reference/template-tag.md @@ -81,7 +81,7 @@ This template tag can be used to insert any number of ReactPy components onto yo Here's a couple of things to keep in mind: 1. If your host address are completely separate ( `origin1.com != origin2.com` ) you will need to [configure CORS headers](https://pypi.org/project/django-cors-headers/) on your main application during deployment. - 2. You will not need to register ReactPy HTTP or WebSocket paths on any applications that do not perform any component rendering. + 2. You will not need to register ReactPy WebSocket or HTTP paths on any applications that do not perform any component rendering. 3. Your component will only be able to access your template tag's `#!python *args`/`#!python **kwargs` if your applications share a common database. diff --git a/docs/src/reference/utils.md b/docs/src/reference/utils.md index e5c10057..85633bdb 100644 --- a/docs/src/reference/utils.md +++ b/docs/src/reference/utils.md @@ -60,6 +60,6 @@ This function is used manually register a root component with ReactPy. 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. + For security reasons, ReactPy requires all root components to be registered. However, all components contained within Django templates are automatically registered. - 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 `#!python host` argument](../reference/template-tag.md#component). On this dedicated rendering server, you would need to manually register your components. + This function is needed when you have configured your [`host`](../reference/template-tag.md#component) to a dedicated Django rendering application that doesn't have templates. On this dedicated rendering server, you would need to manually register your components. diff --git a/mkdocs.yml b/mkdocs.yml index af88f66b..587cf87d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -90,6 +90,9 @@ extra: generator: false version: provider: mike + analytics: + provider: google + property: G-4KFQN2LWBG extra_javascript: - assets/js/main.js From 1785ad1f61d2efc9d5dff6744455d17420f3ceac Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Mon, 18 Sep 2023 23:25:44 -0700 Subject: [PATCH 02/13] hooks rewording --- docs/src/reference/hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/reference/hooks.md b/docs/src/reference/hooks.md index bdf36cee..1aad9bab 100644 --- a/docs/src/reference/hooks.md +++ b/docs/src/reference/hooks.md @@ -181,7 +181,7 @@ The mutation function you provide should have no return value. Mutation function | Name | Type | Description | Default | | --- | --- | --- | --- | | `#!python mutate` | `#!python Callable[_Params, bool | None]` | A callable that performs Django ORM create, update, or delete functionality. If this function returns `#!python False`, then your `#!python refetch` function will not be used. | N/A | - | `#!python refetch` | `#!python Callable[..., Any] | Sequence[Callable[..., Any]] | None` | A `#!python query` function (used by the `#!python use_query` hook) or a sequence of `#!python query` functions that will be called if the mutation succeeds. This is useful for refetching data after a mutation has been performed. | `#!python None` | + | `#!python refetch` | `#!python Callable[..., Any] | Sequence[Callable[..., Any]] | None` | A query function (the function typically provided to your `#!python use_query` hook) or a sequence of query functions that need a `refetch` if the mutation succeeds. This is useful for refetching data after a mutation has been performed. | `#!python None` | **Returns** From 190689dc48892489f91da421dd6f1c80ef39da9a Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 01:43:04 -0700 Subject: [PATCH 03/13] Use async mutation/queries in main examples --- docs/python/use-mutation.py | 4 ++-- docs/python/use-query.py | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/python/use-mutation.py b/docs/python/use-mutation.py index 7c5c94fd..5b6f0e55 100644 --- a/docs/python/use-mutation.py +++ b/docs/python/use-mutation.py @@ -3,8 +3,8 @@ from reactpy_django.hooks import use_mutation -def add_item(text: str): - TodoItem(text=text).save() +async def add_item(text: str): + await TodoItem(text=text).asave() @component diff --git a/docs/python/use-query.py b/docs/python/use-query.py index a8ed8b46..e546ed59 100644 --- a/docs/python/use-query.py +++ b/docs/python/use-query.py @@ -1,10 +1,11 @@ +from channels.db import database_sync_to_async from example.models import TodoItem from reactpy import component, html from reactpy_django.hooks import use_query -def get_items(): - return TodoItem.objects.all() +async def get_items(): + return await database_sync_to_async(TodoItem.objects.all)() @component From 86d90ac333fc93fff15fc240203411235966896b Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 01:43:18 -0700 Subject: [PATCH 04/13] fix postprocessor name --- docs/includes/orm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/orm.md b/docs/includes/orm.md index 74f966c0..58f45477 100644 --- a/docs/includes/orm.md +++ b/docs/includes/orm.md @@ -8,6 +8,6 @@ These `#!python SynchronousOnlyOperation` exceptions may be removed in a future -By default, automatic recursive fetching of `#!python ManyToMany` or `#!python ForeignKey` fields is enabled within the `DjangoQueryPostprocessor`. This is needed to prevent `#!python SynchronousOnlyOperation` exceptions when accessing these fields within your ReactPy components. +By default, automatic recursive fetching of `#!python ManyToMany` or `#!python ForeignKey` fields is enabled within the `django_query_postprocessor`. This is needed to prevent `#!python SynchronousOnlyOperation` exceptions when accessing these fields within your ReactPy components. From 3890298d3b6ac3e6b17b47e45b29f6c0119fb10a Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 01:47:46 -0700 Subject: [PATCH 05/13] fix docstring function descriptions --- src/reactpy_django/components.py | 20 ++++++++++---------- src/reactpy_django/decorators.py | 4 ++-- src/reactpy_django/hooks.py | 8 ++++---- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/src/reactpy_django/components.py b/src/reactpy_django/components.py index 31df3e2e..ceab23d4 100644 --- a/src/reactpy_django/components.py +++ b/src/reactpy_django/components.py @@ -124,16 +124,16 @@ def view_to_component( Keyword Args: view: The view function or class to convert. - compatibility: If True, the component will be rendered in an iframe. - When using compatibility mode `tranforms`, `strict_parsing`, `request`, + compatibility: 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. - transforms: A list of functions that transforms the newly generated VDOM. + transforms: A list of functions that transforms the newly generated VDOM. \ The functions will be called on each VDOM node. - strict_parsing: If True, an exception will be generated if the HTML does not + strict_parsing: If True, an exception will be generated if the HTML does not \ perfectly adhere to HTML5. Returns: - A function that takes `request: HttpRequest | None, *args: Any, key: Key | None, **kwargs: Any` + A function that takes `request: HttpRequest | None, *args: Any, key: Key | None, **kwargs: Any` \ and returns a ReactPy component. """ @@ -172,9 +172,9 @@ def django_css(static_path: str, key: Key | None = None): """Fetches a CSS static file for use within ReactPy. This allows for deferred CSS loading. Args: - static_path: The path to the static file. This path is identical to what you would - use on a `static` template tag. - key: A key to uniquely identify this component which is unique amongst a component's + static_path: The path to the static file. This path is identical to what you would \ + use on Django's `{% static %}` template tag + key: A key to uniquely identify this component which is unique amongst a component's \ immediate siblings """ @@ -190,9 +190,9 @@ def django_js(static_path: str, key: Key | None = None): """Fetches a JS static file for use within ReactPy. This allows for deferred JS loading. Args: - static_path: The path to the static file. This path is identical to what you would + static_path: The path to the static file. This path is identical to what you would \ use on a `static` template tag. - key: A key to uniquely identify this component which is unique amongst a component's + key: A key to uniquely identify this component which is unique amongst a component's \ immediate siblings """ diff --git a/src/reactpy_django/decorators.py b/src/reactpy_django/decorators.py index fc24fdfd..4f3befe2 100644 --- a/src/reactpy_django/decorators.py +++ b/src/reactpy_django/decorators.py @@ -19,8 +19,8 @@ def auth_required( This decorator can be used with or without parentheses. Args: - auth_attribute: The value to check within the user object. - This is checked in the form of `UserModel.`. + auth_attribute: The value to check within the user object. \ + This is checked in the form of `UserModel.`. \ fallback: The component or VDOM (`reactpy.html` snippet) to render if the user is not authenticated. """ diff --git a/src/reactpy_django/hooks.py b/src/reactpy_django/hooks.py index 8115de56..ef76a5e7 100644 --- a/src/reactpy_django/hooks.py +++ b/src/reactpy_django/hooks.py @@ -229,11 +229,11 @@ def use_mutation(*args: Any, **kwargs: Any) -> Mutation[_Params]: """Hook to create, update, or delete Django ORM objects. Args: - mutate: A callable that performs Django ORM create, update, or delete - functionality. If this function returns `False`, then your `refetch` + mutate: A callable that performs Django ORM create, update, or delete \ + functionality. If this function returns `False`, then your `refetch` \ function will not be used. - refetch: 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 + refetch: 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. """ From 61ee5ea7e9753e28b6bc23a7c6ae371266cb6a89 Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 15:26:07 -0700 Subject: [PATCH 06/13] wordsmith --- docs/src/reference/hooks.md | 16 ++++++++-------- docs/src/reference/utils.md | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/src/reference/hooks.md b/docs/src/reference/hooks.md index 1aad9bab..de42fd98 100644 --- a/docs/src/reference/hooks.md +++ b/docs/src/reference/hooks.md @@ -16,9 +16,9 @@ Prefabricated hooks can be used within your `components.py` to help simplify dev ## Use Query -This hook is used [read](https://www.sumologic.com/glossary/crud/) data, typically from the Django ORM. +This hook is used to execute functions in the background and return the result, typically to [read](https://www.sumologic.com/glossary/crud/) data the Django ORM. -The [default postprocessor](../reference/utils.md#django-query-postprocessor) expects your query function to return either a Django `#!python Model` or `#!python QuerySet`. The postprocessor needs to be changed to perform other types of queries. Query functions can be sync or async. +The [default postprocessor](../reference/utils.md#django-query-postprocessor) expects your query function to return either a Django `#!python Model` or `#!python QuerySet`. The postprocessor needs to be changed to execute other types of queries. Query functions can be sync or async. === "components.py" @@ -61,9 +61,9 @@ The [default postprocessor](../reference/utils.md#django-query-postprocessor) ex ??? question "How can I customize this hook's behavior?" - This hook accepts a `#!python options = ...` parameter that can be used to customize its behavior. You can provide a `#!python reactpy_django.types.QueryOptions` object to this parameter to customize the hook's behavior. + This hook accepts a `#!python options: QueryOptions` parameter that can be used to customize behavior. - Below are the settings that can be modified via `#!python QueryOptions`. + Below are the settings that can be modified via these `#!python QueryOptions`. --- @@ -158,7 +158,7 @@ The [default postprocessor](../reference/utils.md#django-query-postprocessor) ex ## Use Mutation -This hook is used to [create, update, or delete](https://www.sumologic.com/glossary/crud/) data, typically from the Django ORM. +This hook is used to modify data in the background, typically to [create/update/delete](https://www.sumologic.com/glossary/crud/) data from the Django ORM. The mutation function you provide should have no return value. Mutation functions can be sync or async. @@ -201,9 +201,9 @@ The mutation function you provide should have no return value. Mutation function ??? question "How can I customize this hook's behavior?" - This hook accepts a `#!python options = ...` parameter that can be used to customize its behavior. You can provide a `#!python reactpy_django.types.MutationOptions` object to this parameter to customize the hook's behavior. + This hook accepts a `#!python options: MutationOptions` parameter that can be used to customize behavior. - Below are the settings that can be modified via `#!python MutationOptions`. + Below are the settings that can be modified via these `#!python MutationOptions`. --- @@ -331,7 +331,7 @@ You can expect this hook to provide strings such as `/reactpy/my_path`. ??? info "This hook's behavior will be changed in a future update" - This hook will be updated to always return the browser's currently active HTTP path. This change will come in alongside ReactPy URL routing support. + 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](https://github.com/reactive-python/reactpy-django/issues/147) for more information. diff --git a/docs/src/reference/utils.md b/docs/src/reference/utils.md index 85633bdb..d9b36462 100644 --- a/docs/src/reference/utils.md +++ b/docs/src/reference/utils.md @@ -62,4 +62,4 @@ This function is used manually register a root component with ReactPy. 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`](../reference/template-tag.md#component) to a dedicated Django rendering application that doesn't have templates. On this dedicated rendering server, you would need to manually register your components. + This function is needed when you have configured your [`host`](../reference/template-tag.md#component) to a dedicated Django rendering application that doesn't have templates. From 97b64a4f541d8eb584fcff1f21f3038b635c80c2 Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 16:41:43 -0700 Subject: [PATCH 07/13] recolor banner --- docs/src/assets/css/banner.css | 15 +++++++++++++++ mkdocs.yml | 1 + 2 files changed, 16 insertions(+) create mode 100644 docs/src/assets/css/banner.css diff --git a/docs/src/assets/css/banner.css b/docs/src/assets/css/banner.css new file mode 100644 index 00000000..b3cb5ef4 --- /dev/null +++ b/docs/src/assets/css/banner.css @@ -0,0 +1,15 @@ +body[data-md-color-scheme="slate"] { + --md-banner-bg-color: #4d4121; + --md-banner-font-color: #fff; +} + +body[data-md-color-scheme="default"] { + --md-banner-bg-color: #ff9; + --md-banner-font-color: #000; +} + +.md-banner--warning { + background-color: var(--md-banner-bg-color); + color: var(--md-banner-font-color); + text-align: center; +} diff --git a/mkdocs.yml b/mkdocs.yml index 587cf87d..666e27d3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -101,6 +101,7 @@ extra_css: - assets/css/main.css - assets/css/button.css - assets/css/admonition.css + - assets/css/banner.css - assets/css/sidebar.css - assets/css/navbar.css - assets/css/table-of-contents.css From 6c764de91aba286e46b522227d637d07d72c9678 Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 16:51:26 -0700 Subject: [PATCH 08/13] remove path from template tag docs --- docs/src/reference/template-tag.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/reference/template-tag.md b/docs/src/reference/template-tag.md index 8fdb5695..6321243b 100644 --- a/docs/src/reference/template-tag.md +++ b/docs/src/reference/template-tag.md @@ -40,7 +40,7 @@ This template tag can be used to insert any number of ReactPy components onto yo ??? warning "Do not use context variables for the component path" - The ReactPy component finder (`#!python reactpy_django.utils.RootComponentFinder`) requires that your component path is a string. + 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. From 572842535a18fdf9b02635c48b2eaaef2d1f317a Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 17:35:00 -0700 Subject: [PATCH 09/13] smithy --- docs/src/reference/hooks.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/src/reference/hooks.md b/docs/src/reference/hooks.md index de42fd98..87630bec 100644 --- a/docs/src/reference/hooks.md +++ b/docs/src/reference/hooks.md @@ -18,7 +18,7 @@ Prefabricated hooks can be used within your `components.py` to help simplify dev This hook is used to execute functions in the background and return the result, typically to [read](https://www.sumologic.com/glossary/crud/) data the Django ORM. -The [default postprocessor](../reference/utils.md#django-query-postprocessor) expects your query function to return either a Django `#!python Model` or `#!python QuerySet`. The postprocessor needs to be changed to execute other types of queries. Query functions can be sync or async. +The [default postprocessor](../reference/utils.md#django-query-postprocessor) expects your query function to `#!python return` a Django `#!python Model` or `#!python QuerySet`. The postprocessor needs to be changed to execute other types of queries. Query functions can be sync or async. === "components.py" @@ -160,7 +160,7 @@ The [default postprocessor](../reference/utils.md#django-query-postprocessor) ex This hook is used to modify data in the background, typically to [create/update/delete](https://www.sumologic.com/glossary/crud/) data from the Django ORM. -The mutation function you provide should have no return value. Mutation functions can be sync or async. +Mutation functions can `#!python return False` to prevent executing your `#!python refetch` function. All other returns are ignored. Mutation functions can be sync or async. === "components.py" @@ -285,7 +285,7 @@ This hook is used to fetch the active connection, which is either a Django [WebS ## Use Scope -This is a shortcut that returns the HTTP or WebSocket [`#!python scope`](https://channels.readthedocs.io/en/stable/topics/consumers.html#scope). +This is a shortcut that returns the WebSocket or HTTP [scope](https://channels.readthedocs.io/en/stable/topics/consumers.html#scope). === "components.py" @@ -307,7 +307,7 @@ This is a shortcut that returns the HTTP or WebSocket [`#!python scope`](https:/ ## Use Location -This is a shortcut that returns the client's `#!python path`. +This is a shortcut that returns the client's URL `#!python path`. You can expect this hook to provide strings such as `/reactpy/my_path`. @@ -337,7 +337,7 @@ You can expect this hook to provide strings such as `/reactpy/my_path`. ## Use Origin -This is a shortcut that returns the WebSocket's `#!python origin`. +This is a shortcut that returns the client's `#!python origin`. You can expect this hook to provide strings such as `http://example.com`. From f45a42c33be772cfeee604dc19710e2cb50013cd Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 17:48:26 -0700 Subject: [PATCH 10/13] match up docstrings to docs --- docs/src/reference/hooks.md | 2 +- src/reactpy_django/components.py | 2 +- src/reactpy_django/hooks.py | 9 +++++---- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/src/reference/hooks.md b/docs/src/reference/hooks.md index 87630bec..c9b3985d 100644 --- a/docs/src/reference/hooks.md +++ b/docs/src/reference/hooks.md @@ -181,7 +181,7 @@ Mutation functions can `#!python return False` to prevent executing your `#!pyth | Name | Type | Description | Default | | --- | --- | --- | --- | | `#!python mutate` | `#!python Callable[_Params, bool | None]` | A callable that performs Django ORM create, update, or delete functionality. If this function returns `#!python False`, then your `#!python refetch` function will not be used. | N/A | - | `#!python refetch` | `#!python Callable[..., Any] | Sequence[Callable[..., Any]] | None` | A query function (the function typically provided to your `#!python use_query` hook) or a sequence of query functions that need a `refetch` if the mutation succeeds. This is useful for refetching data after a mutation has been performed. | `#!python None` | + | `#!python refetch` | `#!python Callable[..., Any] | Sequence[Callable[..., Any]] | None` | A query function (the function you provide to your `#!python use_query` hook) or a sequence of query functions that need a `refetch` if the mutation succeeds. This is useful for refreshing data after a mutation has been performed. | `#!python None` | **Returns** diff --git a/src/reactpy_django/components.py b/src/reactpy_django/components.py index ceab23d4..6884276b 100644 --- a/src/reactpy_django/components.py +++ b/src/reactpy_django/components.py @@ -191,7 +191,7 @@ def django_js(static_path: str, key: Key | None = None): Args: static_path: The path to the static file. This path is identical to what you would \ - use on a `static` template tag. + use on Django's `{% static %}` template tag. key: A key to uniquely identify this component which is unique amongst a component's \ immediate siblings """ diff --git a/src/reactpy_django/hooks.py b/src/reactpy_django/hooks.py index ef76a5e7..2fbdd88f 100644 --- a/src/reactpy_django/hooks.py +++ b/src/reactpy_django/hooks.py @@ -229,12 +229,13 @@ def use_mutation(*args: Any, **kwargs: Any) -> Mutation[_Params]: """Hook to create, update, or delete Django ORM objects. Args: - mutate: A callable that performs Django ORM create, update, or delete \ + mutation: A callable that performs Django ORM create, update, or delete \ functionality. If this function returns `False`, then your `refetch` \ function will not be used. - refetch: 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. + refetch: A query function (the function you provide to your `use_query` \ + hook) or a sequence of query functions that need a `refetch` if the \ + mutation succeeds. This is useful for refreshing data after a mutation \ + has been performed. """ loading, set_loading = use_state(False) From 7c1a8dc0a4cb9f8c346ff1803854a39be7cff06f Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 18:07:20 -0700 Subject: [PATCH 11/13] add license to docs --- LICENSE | 21 --------------------- LICENSE.md | 9 +++++++++ docs/src/about/license.md | 8 ++++++++ mkdocs.yml | 11 +++++++---- 4 files changed, 24 insertions(+), 25 deletions(-) delete mode 100644 LICENSE create mode 100644 LICENSE.md create mode 100644 docs/src/about/license.md diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 2a6bd62d..00000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -The MIT License (MIT) - -Copyright (c) 2021 Ryan S. Morshead - -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. diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..140536d2 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,9 @@ +## The MIT License (MIT) + +#### Copyright (c) Reactive Python Team and affiliates. + +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. diff --git a/docs/src/about/license.md b/docs/src/about/license.md new file mode 100644 index 00000000..15d975db --- /dev/null +++ b/docs/src/about/license.md @@ -0,0 +1,8 @@ +--- +hide: + - toc +--- + +--- + +{% include "../../../LICENSE.md" %} diff --git a/mkdocs.yml b/mkdocs.yml index 666e27d3..63312cd8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,12 +12,14 @@ nav: - Template Tag: reference/template-tag.md - Settings: reference/settings.md - About: - - Contribute: + - Changelog: about/changelog.md + - Contributor Guide: - Code: about/code.md - Docs: about/docs.md - - GitHub Discussions: https://github.com/reactive-python/reactpy-django/discussions - - Discord: https://discord.gg/uNb5P4hA9X - - Changelog: about/changelog.md + - Community: + - GitHub Discussions: https://github.com/reactive-python/reactpy-django/discussions + - Discord: https://discord.gg/uNb5P4hA9X + - License: about/license.md theme: name: material @@ -114,6 +116,7 @@ watch: - mkdocs.yml - README.md - CHANGELOG.md + - LICENSE.md - .mailmap site_name: ReactPy-Django From f7734b57d5ae6f0cfa56a2a8f7fcdd372c23bee8 Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 18:08:11 -0700 Subject: [PATCH 12/13] add sublicense to dictionary --- docs/src/dictionary.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/dictionary.txt b/docs/src/dictionary.txt index d3d2eb25..58f6eeec 100644 --- a/docs/src/dictionary.txt +++ b/docs/src/dictionary.txt @@ -37,3 +37,4 @@ frontends misconfiguration misconfigurations backhaul +sublicense From 3e7c53663e0b3d9e901434702a8a5cc7a2cac6f7 Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Wed, 20 Sep 2023 18:34:59 -0700 Subject: [PATCH 13/13] Auto-generate copyright year --- LICENSE.md | 2 +- docs/src/assets/css/footer.css | 4 ++++ mkdocs.yml | 8 +++++++- 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/LICENSE.md b/LICENSE.md index 140536d2..f5423c3d 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ ## The MIT License (MIT) -#### Copyright (c) Reactive Python Team and affiliates. +#### Copyright (c) Reactive Python and affiliates. 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: diff --git a/docs/src/assets/css/footer.css b/docs/src/assets/css/footer.css index 9dcaca2d..b3408286 100644 --- a/docs/src/assets/css/footer.css +++ b/docs/src/assets/css/footer.css @@ -27,3 +27,7 @@ .legal-footer-right { float: right; } + +.md-copyright__highlight div { + display: inline; +} diff --git a/mkdocs.yml b/mkdocs.yml index 63312cd8..35bb6bb0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -122,7 +122,13 @@ watch: site_name: ReactPy-Django site_author: Archmonger site_description: It's React, but in Python. Now with Django integration. -copyright: Copyright © 2023 Reactive Python.
This project has no affiliation to ReactJS or Meta Platforms, Inc.
+copyright: '© +
+ +Reactive Python and affiliates. +
+This project has no affiliation to ReactJS or Meta Platforms, Inc. +
' repo_url: https://github.com/reactive-python/reactpy-django site_url: https://reactive-python.github.io/reactpy-django repo_name: reactive-python/reactpy-django