reactpy_django 5.0.0__py3-none-any.whl

reactpy_django/components.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Callable, Sequence, Union, cast
+from urllib.parse import urlencode
+from uuid import uuid4
+
+from django.contrib.staticfiles.finders import find
+from django.core.cache import caches
+from django.http import HttpRequest
+from django.urls import reverse
+from django.views import View
+from reactpy import component, hooks, html, utils
+from reactpy.types import ComponentType, Key, VdomDict
+
+from reactpy_django.exceptions import ViewNotRegisteredError
+from reactpy_django.html import pyscript
+from reactpy_django.utils import (
+    generate_obj_name,
+    import_module,
+    render_pyscript_template,
+    render_view,
+    vdom_or_component_to_string,
+)
+
+
+def view_to_component(
+    view: Callable | View | str,
+    transforms: Sequence[Callable[[VdomDict], Any]] = (),
+    strict_parsing: bool = True,
+) -> Any:
+    """Converts a Django view to a ReactPy component.
+
+    Keyword Args:
+        view: The view to convert, or the view's dotted path as a string.
+        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 \
+            perfectly adhere to HTML5.
+
+    Returns:
+        A function that takes `request, *args, key, **kwargs` and returns a ReactPy component.
+    """
+
+    def constructor(
+        request: HttpRequest | None = None,
+        *args,
+        key: Key | None = None,
+        **kwargs,
+    ):
+        return _view_to_component(
+            view=view,
+            transforms=transforms,
+            strict_parsing=strict_parsing,
+            request=request,
+            args=args,
+            kwargs=kwargs,
+            key=key,
+        )
+
+    return constructor
+
+
+def view_to_iframe(
+    view: Callable | View | str, extra_props: dict[str, Any] | None = None
+):
+    """
+    Args:
+        view: The view function or class to convert, or the dotted path to the view.
+
+    Keyword Args:
+        extra_props: Additional properties to add to the `iframe` element.
+
+    Returns:
+        A function that takes `*args, key, **kwargs` and returns a ReactPy component.
+    """
+
+    def constructor(
+        *args,
+        key: Key | None = None,
+        **kwargs,
+    ):
+        return _view_to_iframe(
+            view=view, extra_props=extra_props, args=args, kwargs=kwargs, key=key
+        )
+
+    return constructor
+
+
+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 Django's `{% static %}` template tag
+        key: A key to uniquely identify this component which is unique amongst a component's \
+            immediate siblings
+    """
+
+    return _django_css(static_path=static_path, key=key)
+
+
+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 \
+            use on Django's `{% static %}` template tag.
+        key: A key to uniquely identify this component which is unique amongst a component's \
+            immediate siblings
+    """
+
+    return _django_js(static_path=static_path, key=key)
+
+
+def pyscript_component(
+    *file_paths: str,
+    initial: str | VdomDict | ComponentType = "",
+    root: str = "root",
+):
+    """
+    Args:
+        file_paths: File path to your client-side component. If multiple paths are \
+            provided, the contents are automatically merged.
+
+    Kwargs:
+        initial: The initial HTML that is displayed prior to the PyScript component \
+            loads. This can either be a string containing raw HTML, a \
+            `#!python reactpy.html` snippet, or a non-interactive component.
+        root: The name of the root component function.
+    """
+    return _pyscript_component(
+        *file_paths,
+        initial=initial,
+        root=root,
+    )
+
+
+@component
+def _view_to_component(
+    view: Callable | View | str,
+    transforms: Sequence[Callable[[VdomDict], Any]],
+    strict_parsing: bool,
+    request: HttpRequest | None,
+    args: Sequence | None,
+    kwargs: dict | None,
+):
+    """The actual component. Used to prevent pollution of acceptable kwargs keys."""
+    converted_view, set_converted_view = hooks.use_state(
+        cast(Union[VdomDict, None], None)
+    )
+    _args: Sequence = args or ()
+    _kwargs: dict = kwargs or {}
+    if request:
+        _request: HttpRequest = request
+    else:
+        _request = HttpRequest()
+        _request.method = "GET"
+    resolved_view: Callable = import_module(view) if isinstance(view, str) else view  # type: ignore[assignment]
+
+    # Render the view render within a hook
+    @hooks.use_effect(
+        dependencies=[
+            json.dumps(vars(_request), default=lambda x: generate_obj_name(x)),
+            json.dumps([_args, _kwargs], default=lambda x: generate_obj_name(x)),
+        ]
+    )
+    async def async_render():
+        """Render the view in an async hook to avoid blocking the main thread."""
+        # Render the view
+        response = await render_view(resolved_view, _request, _args, _kwargs)
+        set_converted_view(
+            utils.html_to_vdom(
+                response.content.decode("utf-8").strip(),
+                utils.del_html_head_body_transform,
+                *transforms,
+                strict=strict_parsing,
+            )
+        )
+
+    # Return the view if it's been rendered via the `async_render` hook
+    return converted_view
+
+
+@component
+def _view_to_iframe(
+    view: Callable | View | str,
+    extra_props: dict[str, Any] | None,
+    args: Sequence,
+    kwargs: dict,
+) -> VdomDict:
+    """The actual component. Used to prevent pollution of acceptable kwargs keys."""
+    from reactpy_django.config import REACTPY_REGISTERED_IFRAME_VIEWS
+
+    if hasattr(view, "view_class"):
+        view = view.view_class
+    dotted_path = view if isinstance(view, str) else generate_obj_name(view)
+    registered_view = REACTPY_REGISTERED_IFRAME_VIEWS.get(dotted_path)
+
+    if not registered_view:
+        raise ViewNotRegisteredError(
+            f"'{dotted_path}' has not been registered as an iframe! "
+            "Are you sure you called `register_iframe` within a Django `AppConfig.ready` method?"
+        )
+
+    query = kwargs.copy()
+    if args:
+        query["_args"] = args
+    query_string = f"?{urlencode(query, doseq=True)}" if args or kwargs else ""
+    extra_props = extra_props or {}
+    extra_props.pop("src", None)
+
+    return html.iframe(
+        {
+            "src": reverse("reactpy:view_to_iframe", args=[dotted_path]) + query_string,
+            "style": {"border": "none"},
+            "loading": "lazy",
+        }
+        | extra_props
+    )
+
+
+@component
+def _django_css(static_path: str):
+    return html.style(_cached_static_contents(static_path))
+
+
+@component
+def _django_js(static_path: str):
+    return html.script(_cached_static_contents(static_path))
+
+
+def _cached_static_contents(static_path: str) -> str:
+    from reactpy_django.config import REACTPY_CACHE
+
+    # Try to find the file within Django's static files
+    abs_path = find(static_path)
+    if not abs_path:
+        raise FileNotFoundError(
+            f"Could not find static file {static_path} within Django's static files."
+        )
+
+    # Fetch the file from cache, if available
+    last_modified_time = os.stat(abs_path).st_mtime
+    cache_key = f"reactpy_django:static_contents:{static_path}"
+    file_contents: str | None = caches[REACTPY_CACHE].get(
+        cache_key, version=int(last_modified_time)
+    )
+    if file_contents is None:
+        with open(abs_path, encoding="utf-8") as static_file:
+            file_contents = static_file.read()
+        caches[REACTPY_CACHE].delete(cache_key)
+        caches[REACTPY_CACHE].set(
+            cache_key, file_contents, timeout=None, version=int(last_modified_time)
+        )
+
+    return file_contents
+
+
+@component
+def _pyscript_component(
+    *file_paths: str,
+    initial: str | VdomDict | ComponentType = "",
+    root: str = "root",
+):
+    rendered, set_rendered = hooks.use_state(False)
+    uuid = uuid4().hex.replace("-", "")
+    initial = vdom_or_component_to_string(initial, uuid=uuid)
+    executor = render_pyscript_template(file_paths, uuid, root)
+
+    if not rendered:
+        # FIXME: This is needed to properly re-render PyScript during a WebSocket
+        # disconnection / reconnection. There may be a better way to do this in the future.
+        set_rendered(True)
+        return None
+
+    return html._(
+        html.div(
+            {"id": f"pyscript-{uuid}", "className": "pyscript", "data-uuid": uuid},
+            initial,
+        ),
+        pyscript({"async": ""}, executor),
+    )

reactpy_django/config.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from itertools import cycle
+from typing import Callable
+
+from django.conf import settings
+from django.core.cache import DEFAULT_CACHE_ALIAS
+from django.db import DEFAULT_DB_ALIAS
+from django.views import View
+from reactpy.config import REACTPY_DEBUG_MODE as _REACTPY_DEBUG_MODE
+from reactpy.core.types import ComponentConstructor
+
+from reactpy_django.types import (
+    AsyncPostprocessor,
+    SyncPostprocessor,
+)
+from reactpy_django.utils import import_dotted_path
+
+# Non-configurable values
+_REACTPY_DEBUG_MODE.set_current(getattr(settings, "DEBUG"))
+REACTPY_DEBUG_MODE = _REACTPY_DEBUG_MODE.current
+REACTPY_REGISTERED_COMPONENTS: dict[str, ComponentConstructor] = {}
+REACTPY_FAILED_COMPONENTS: set[str] = set()
+REACTPY_REGISTERED_IFRAME_VIEWS: dict[str, Callable | View] = {}
+
+# Configurable through Django settings.py
+REACTPY_URL_PREFIX: str = getattr(
+    settings,
+    "REACTPY_URL_PREFIX",
+    "reactpy/",
+).strip("/")
+REACTPY_SESSION_MAX_AGE: int = getattr(
+    settings,
+    "REACTPY_SESSION_MAX_AGE",
+    259200,  # Default to 3 days
+)
+REACTPY_CACHE: str = getattr(
+    settings,
+    "REACTPY_CACHE",
+    DEFAULT_CACHE_ALIAS,
+)
+REACTPY_DATABASE: str = getattr(
+    settings,
+    "REACTPY_DATABASE",
+    DEFAULT_DB_ALIAS,
+)
+_default_query_postprocessor = getattr(
+    settings,
+    "REACTPY_DEFAULT_QUERY_POSTPROCESSOR",
+    "UNSET",
+)
+REACTPY_DEFAULT_QUERY_POSTPROCESSOR: AsyncPostprocessor | SyncPostprocessor | None
+if _default_query_postprocessor is None:
+    REACTPY_DEFAULT_QUERY_POSTPROCESSOR = None
+else:
+    REACTPY_DEFAULT_QUERY_POSTPROCESSOR = import_dotted_path(
+        "reactpy_django.utils.django_query_postprocessor"
+        if (
+            _default_query_postprocessor == "UNSET"
+            or not isinstance(_default_query_postprocessor, str)
+        )
+        else _default_query_postprocessor
+    )
+REACTPY_AUTH_BACKEND: str | None = getattr(
+    settings,
+    "REACTPY_AUTH_BACKEND",
+    None,
+)
+REACTPY_BACKHAUL_THREAD: bool = getattr(
+    settings,
+    "REACTPY_BACKHAUL_THREAD",
+    False,
+)
+_default_hosts: list[str] | None = getattr(
+    settings,
+    "REACTPY_DEFAULT_HOSTS",
+    None,
+)
+REACTPY_DEFAULT_HOSTS: cycle[str] | None = (
+    cycle([host.strip("/") for host in _default_hosts if isinstance(host, str)])
+    if _default_hosts
+    else None
+)
+REACTPY_RECONNECT_INTERVAL: int = getattr(
+    settings,
+    "REACTPY_RECONNECT_INTERVAL",
+    750,  # Default to 0.75 seconds
+)
+REACTPY_RECONNECT_MAX_INTERVAL: int = getattr(
+    settings,
+    "REACTPY_RECONNECT_MAX_INTERVAL",
+    60000,  # Default to 60 seconds
+)
+REACTPY_RECONNECT_MAX_RETRIES: int = getattr(
+    settings,
+    "REACTPY_RECONNECT_MAX_RETRIES",
+    150,
+)
+REACTPY_RECONNECT_BACKOFF_MULTIPLIER: float | int = getattr(
+    settings,
+    "REACTPY_RECONNECT_BACKOFF_MULTIPLIER",
+    1.25,  # Default to 25% backoff per connection attempt
+)
+REACTPY_PRERENDER: bool = getattr(
+    settings,
+    "REACTPY_PRERENDER",
+    False,
+)
+REACTPY_AUTO_RELOGIN: bool = getattr(
+    settings,
+    "REACTPY_AUTO_RELOGIN",
+    False,
+)
+REACTPY_CLEAN_INTERVAL: int | None = getattr(
+    settings,
+    "REACTPY_CLEAN_INTERVAL",
+    604800,  # Default to 7 days
+)
+REACTPY_CLEAN_SESSIONS: bool = getattr(
+    settings,
+    "REACTPY_CLEAN_SESSIONS",
+    True,
+)
+REACTPY_CLEAN_USER_DATA: bool = getattr(
+    settings,
+    "REACTPY_CLEAN_USER_DATA",
+    True,
+)

reactpy_django/database.py

@@ -0,0 +1,31 @@
+from reactpy_django.config import REACTPY_DATABASE
+
+
+class Router:
+    """
+    A router to control all database operations on models in the
+    auth and contenttypes applications.
+    """
+
+    route_app_labels = {"reactpy_django"}
+
+    def db_for_read(self, model, **hints):
+        """Attempts to read go to REACTPY_DATABASE."""
+        if model._meta.app_label in self.route_app_labels:
+            return REACTPY_DATABASE
+
+    def db_for_write(self, model, **hints):
+        """Attempts to write go to REACTPY_DATABASE."""
+        if model._meta.app_label in self.route_app_labels:
+            return REACTPY_DATABASE
+
+    def allow_relation(self, obj1, obj2, **hints):
+        """Returning `None` only allow relations within the same database.
+        https://docs.djangoproject.com/en/stable/topics/db/multi-db/#limitations-of-multiple-databases
+        """
+        return None
+
+    def allow_migrate(self, db, app_label, model_name=None, **hints):
+        """Make sure ReactPy models only appear in REACTPY_DATABASE."""
+        if app_label in self.route_app_labels:
+            return db == REACTPY_DATABASE

reactpy_django/decorators.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable
+
+from reactpy import component
+from reactpy.core.types import ComponentConstructor
+
+from reactpy_django.exceptions import DecoratorParamError
+from reactpy_django.hooks import use_user
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import AbstractUser
+
+
+
+
+def user_passes_test(
+    test_func: Callable[[AbstractUser], bool],
+    /,
+    fallback: Any | None = None,
+) -> ComponentConstructor:
+    """You can limit component access to users that pass a test function by using this decorator.
+
+    This decorator is inspired by Django's `user_passes_test` decorator, but works with ReactPy components.
+
+    Args:
+        test_func: A function that accepts a `User` returns a boolean.
+        fallback: The content to be rendered if the test fails. Typically is a ReactPy component or \
+            VDOM (`reactpy.html` snippet).
+    """
+
+    def decorator(user_component):
+        @wraps(user_component)
+        def _wrapper(*args, **kwargs):
+            return _user_passes_test(
+                user_component, fallback, test_func, *args, **kwargs
+            )
+
+        return _wrapper
+
+    return decorator
+
+
+@component
+def _user_passes_test(component_constructor, fallback, test_func, *args, **kwargs):
+    """Dedicated component for `user_passes_test` to allow us to always have access to hooks."""
+    user = use_user()
+
+    if test_func(user):
+        # Ensure that the component is a ReactPy component.
+        user_component = component_constructor(*args, **kwargs)
+        if not getattr(user_component, "render", None):
+            raise DecoratorParamError(
+                "`user_passes_test` is not decorating a ReactPy component. "
+                "Did you forget `@user_passes_test` must be ABOVE the `@component` decorator?"
+            )
+
+        # Render the component.
+        return user_component
+
+    # Render the fallback component.
+    # Returns an empty string if fallback is None, since ReactPy currently renders None as a string.
+    # TODO: Remove this fallback when ReactPy can render None properly.
+    return fallback(*args, **kwargs) if callable(fallback) else (fallback or "")

reactpy_django/exceptions.py

@@ -0,0 +1,34 @@
+class ComponentParamError(TypeError):
+    ...
+
+
+class ComponentDoesNotExistError(AttributeError):
+    ...
+
+
+class OfflineComponentMissing(ComponentDoesNotExistError):
+    ...
+
+
+class InvalidHostError(ValueError):
+    ...
+
+
+class ComponentCarrierError(Exception):
+    ...
+
+
+class UserNotFoundError(Exception):
+    ...
+
+
+class ViewNotRegisteredError(AttributeError):
+    ...
+
+
+class ViewDoesNotExistError(AttributeError):
+    ...
+
+
+class DecoratorParamError(TypeError):
+    ...