reactpy_django 3.8.1__py2.py3-none-any.whl

reactpy_django/components.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Callable, Sequence, Union, cast, overload
+from urllib.parse import urlencode
+from warnings import warn
+
+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 Key, VdomDict
+
+from reactpy_django.exceptions import ViewNotRegisteredError
+from reactpy_django.utils import generate_obj_name, import_module, render_view
+
+
+# Type hints for:
+#   1. example = view_to_component(my_view, ...)
+#   2. @view_to_component
+@overload
+def view_to_component(
+    view: Callable | View | str,
+    compatibility: bool = False,
+    transforms: Sequence[Callable[[VdomDict], Any]] = (),
+    strict_parsing: bool = True,
+) -> Any:
+    ...
+
+
+# Type hints for:
+#   1. @view_to_component(...)
+@overload
+def view_to_component(
+    view: None = ...,
+    compatibility: bool = False,
+    transforms: Sequence[Callable[[VdomDict], Any]] = (),
+    strict_parsing: bool = True,
+) -> Callable[[Callable], Any]:
+    ...
+
+
+def view_to_component(
+    view: Callable | View | str | None = None,
+    compatibility: bool = False,
+    transforms: Sequence[Callable[[VdomDict], Any]] = (),
+    strict_parsing: bool = True,
+) -> Any | Callable[[Callable], 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.
+        compatibility: **DEPRECATED.** Use `view_to_iframe` instead.
+        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 decorator(view: Callable | View | str):
+        if not view:
+            raise ValueError("A view must be provided to `view_to_component`")
+
+        def constructor(
+            request: HttpRequest | None = None,
+            *args,
+            key: Key | None = None,
+            **kwargs,
+        ):
+            return _view_to_component(
+                view=view,
+                compatibility=compatibility,
+                transforms=transforms,
+                strict_parsing=strict_parsing,
+                request=request,
+                args=args,
+                kwargs=kwargs,
+                key=key,
+            )
+
+        return constructor
+
+    if not view:
+        warn(
+            "Using `view_to_component` as a decorator is deprecated. "
+            "This functionality will be removed in a future version.",
+            DeprecationWarning,
+        )
+
+    return decorator(view) if view else decorator
+
+
+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)
+
+
+@component
+def _view_to_component(
+    view: Callable | View | str,
+    compatibility: bool,
+    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."""
+        # Compatibility mode doesn't require a traditional render
+        if compatibility:
+            return
+
+        # 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,
+            )
+        )
+
+    # Render in compatibility mode, if needed
+    if compatibility:
+        # Warn the user that compatibility mode is deprecated
+        warn(
+            "view_to_component(compatibility=True) is deprecated and will be removed in a future version. "
+            "Please use `view_to_iframe` instead.",
+            DeprecationWarning,
+        )
+
+        return view_to_iframe(resolved_view)(*_args, **_kwargs)
+
+    # 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"},
+            "onload": 'javascript:(function(o){o.style.height=o.contentWindow.document.body.scrollHeight+"px";}(this));',
+            "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

reactpy_django/config.py

@@ -0,0 +1,135 @@
+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
+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_REGISTERED_COMPONENTS: dict[str, ComponentConstructor] = {}
+REACTPY_FAILED_COMPONENTS: set[str] = set()
+REACTPY_REGISTERED_IFRAME_VIEWS: dict[str, Callable | View] = {}
+
+
+# Remove in a future release
+REACTPY_WEBSOCKET_URL = getattr(
+    settings,
+    "REACTPY_WEBSOCKET_URL",
+    "reactpy/",
+)
+
+# Configurable through Django settings.py
+REACTPY_URL_PREFIX: str = getattr(
+    settings,
+    "REACTPY_URL_PREFIX",
+    REACTPY_WEBSOCKET_URL,
+).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/dev/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,101 @@
+from __future__ import annotations
+
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable
+from warnings import warn
+
+from reactpy import component
+from reactpy.core.types import ComponentConstructor, ComponentType, VdomDict
+
+from reactpy_django.exceptions import DecoratorParamError
+from reactpy_django.hooks import use_scope, use_user
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import AbstractUser
+
+
+def auth_required(
+    component: Callable | None = None,
+    auth_attribute: str = "is_active",
+    fallback: ComponentType | Callable | VdomDict | None = None,
+) -> Callable:
+    """If the user passes authentication criteria, the decorated component will be rendered.
+    Otherwise, the fallback component will be rendered.
+
+    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>`. \
+        fallback: The component or VDOM (`reactpy.html` snippet) to render if the user is not authenticated.
+    """
+
+    warn(
+        "auth_required is deprecated and will be removed in the next major version. "
+        "An equivalent to this decorator's default is @user_passes_test(lambda user: user.is_active).",
+        DeprecationWarning,
+    )
+
+    def decorator(component):
+        @wraps(component)
+        def _wrapped_func(*args, **kwargs):
+            scope = use_scope()
+
+            if getattr(scope["user"], auth_attribute):
+                return component(*args, **kwargs)
+            return fallback(*args, **kwargs) if callable(fallback) else fallback
+
+        return _wrapped_func
+
+    # Return for @authenticated(...) and @authenticated respectively
+    return decorator if component is None else decorator(component)
+
+
+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):
+    ...