reactpy_django 5.0.0__py3-none-any.whl

reactpy_django/static/reactpy_django/pyscript-custom.css

@@ -0,0 +1,3 @@
+py-script {
+    display: none;
+}

reactpy_django/static/reactpy_django/pyscript-hide-debug.css

@@ -0,0 +1,3 @@
+.py-error {
+    display: none;
+}

reactpy_django/templates/reactpy/component.html

@@ -0,0 +1,27 @@
+{% load static %}
+
+{% if reactpy_failure and reactpy_debug_mode %}
+<pre>{% firstof reactpy_error "UnknownError" %}: "{% firstof reactpy_dotted_path "UnknownPath" %}"</pre>
+{% endif %}
+
+{% if not reactpy_failure %}
+{% if reactpy_class %}<div id="{{reactpy_uuid}}" class="{{reactpy_class}}"></div>{% endif %}
+{% if not reactpy_class %}<div id="{{reactpy_uuid}}"></div>{% endif %}
+{% if reactpy_prerender_html %}<div id="{{reactpy_uuid}}-prerender">{{reactpy_prerender_html|safe}}</div>{% endif %}
+{% if reactpy_offline_html %}<div id="{{reactpy_uuid}}-offline" hidden>{{reactpy_offline_html|safe}}</div>{% endif %}
+<script type="module" crossorigin="anonymous">
+  import { mountComponent } from "{% static 'reactpy_django/client.js' %}";
+  const mountElement = document.getElementById("{{reactpy_uuid}}");
+  mountComponent(
+    mountElement,
+    "{{reactpy_host}}",
+    "{{reactpy_url_prefix}}",
+    "{{reactpy_component_path}}",
+    "{{reactpy_resolved_web_modules_path}}",
+    Number("{{reactpy_reconnect_interval}}"),
+    Number("{{reactpy_reconnect_max_interval}}"),
+    Number("{{reactpy_reconnect_max_retries}}"),
+    Number("{{reactpy_reconnect_backoff_multiplier}}"),
+  );
+</script>
+{% endif %}

reactpy_django/templates/reactpy/pyscript_component.html

@@ -0,0 +1,2 @@
+<div id="pyscript-{{pyscript_uuid}}" class="pyscript" data-uuid="{{pyscript_uuid}}">{{pyscript_initial_html}}</div>
+<py-script async>{{pyscript_executor}}</py-script>

reactpy_django/templates/reactpy/pyscript_setup.html

@@ -0,0 +1,8 @@
+{% load static %}
+<link rel="stylesheet" href="{% static 'reactpy_django/pyscript/core.css' %}" />
+<link rel="stylesheet" href="{% static 'reactpy_django/pyscript-custom.css' %}" />
+{% if not reactpy_debug_mode %}
+<link rel="stylesheet" href="{% static 'reactpy_django/pyscript-hide-debug.css' %}" />
+{% endif %}
+<script type="module" async crossorigin="anonymous" src="{% static 'reactpy_django/pyscript/core.js' %}"></script>
+<py-script async config='{{pyscript_config}}'>{{pyscript_layout_handler}}</py-script>

reactpy_django/templatetags/reactpy.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+from logging import getLogger
+from uuid import uuid4
+
+from django import template
+from django.http import HttpRequest
+from django.urls import NoReverseMatch, reverse
+from reactpy.core.types import ComponentConstructor, ComponentType, VdomDict
+
+from reactpy_django import config as reactpy_config
+from reactpy_django.exceptions import (
+    ComponentCarrierError,
+    ComponentDoesNotExistError,
+    ComponentParamError,
+    InvalidHostError,
+    OfflineComponentMissing,
+)
+from reactpy_django.utils import (
+    PYSCRIPT_LAYOUT_HANDLER,
+    extend_pyscript_config,
+    prerender_component,
+    render_pyscript_template,
+    save_component_params,
+    strtobool,
+    validate_component_args,
+    validate_host,
+    vdom_or_component_to_string,
+)
+
+try:
+    RESOLVED_WEB_MODULES_PATH = reverse("reactpy:web_modules", args=["/"]).strip("/")
+except NoReverseMatch:
+    RESOLVED_WEB_MODULES_PATH = ""
+register = template.Library()
+_logger = getLogger(__name__)
+
+
+@register.inclusion_tag("reactpy/component.html", takes_context=True)
+def component(
+    context: template.RequestContext,
+    dotted_path: str,
+    *args,
+    host: str | None = None,
+    prerender: str = str(reactpy_config.REACTPY_PRERENDER),
+    offline: str = "",
+    **kwargs,
+):
+    """This tag is used to embed an existing ReactPy component into your HTML template.
+
+    Args:
+        dotted_path: The dotted path to the component to render.
+        *args: The positional arguments to provide to the component.
+
+    Keyword Args:
+        class: The HTML class to apply to the top-level component div.
+        key: Force the component's root node to use a specific key value. Using \
+            key within a template tag is effectively useless.
+        host: The host to use for ReactPy connections. If set to `None`, \
+            the host will be automatically configured. \
+            Example values include: `localhost:8000`, `example.com`, `example.com/subdir`
+        prerender: Configures whether to pre-render this component, which \
+            enables SEO compatibility and reduces perceived latency.
+        offline: The dotted path to the component to render when the client is offline.
+        **kwargs: The keyword arguments to provide to the component.
+
+    Example ::
+
+        {% load reactpy %}
+        <!DOCTYPE html>
+        <html>
+        <body>
+            {% component "example_project.my_app.components.hello_world" recipient="World" %}
+        </body>
+        </html>
+    """
+    request: HttpRequest | None = context.get("request")
+    perceived_host = (request.get_host() if request else "").strip("/")
+    host = (
+        host
+        or (
+            next(reactpy_config.REACTPY_DEFAULT_HOSTS)
+            if reactpy_config.REACTPY_DEFAULT_HOSTS
+            else ""
+        )
+    ).strip("/")
+    is_local = not host or host.startswith(perceived_host)
+    uuid = str(uuid4())
+    class_ = kwargs.pop("class", "")
+    has_args = bool(args or kwargs)
+    user_component: ComponentConstructor | None = None
+    _prerender_html = ""
+    _offline_html = ""
+
+    # Validate the host
+    if host and reactpy_config.REACTPY_DEBUG_MODE:
+        try:
+            validate_host(host)
+        except InvalidHostError as e:
+            return failure_context(dotted_path, e)
+
+    # Fetch the component
+    if is_local:
+        user_component = reactpy_config.REACTPY_REGISTERED_COMPONENTS.get(dotted_path)
+        if not user_component:
+            msg = f"Component '{dotted_path}' is not registered as a root component. "
+            _logger.error(msg)
+            return failure_context(dotted_path, ComponentDoesNotExistError(msg))
+
+    # Validate the component args & kwargs
+    if is_local and reactpy_config.REACTPY_DEBUG_MODE:
+        try:
+            validate_component_args(user_component, *args, **kwargs)
+        except ComponentParamError as e:
+            _logger.error(str(e))
+            return failure_context(dotted_path, e)
+
+    # Store args & kwargs in the database (fetched by our websocket later)
+    if has_args:
+        try:
+            save_component_params(args, kwargs, uuid)
+        except Exception as e:
+            _logger.exception(
+                "An unknown error has occurred while saving component params for '%s'.",
+                dotted_path,
+            )
+            return failure_context(dotted_path, e)
+
+    # Pre-render the component, if requested
+    if strtobool(prerender):
+        if not is_local:
+            msg = "Cannot pre-render non-local components."
+            _logger.error(msg)
+            return failure_context(dotted_path, ComponentDoesNotExistError(msg))
+        if not user_component:
+            msg = "Cannot pre-render component that is not registered."
+            _logger.error(msg)
+            return failure_context(dotted_path, ComponentDoesNotExistError(msg))
+        if not request:
+            msg = (
+                "Cannot pre-render component without a HTTP request. Are you missing the "
+                "request context processor in settings.py:TEMPLATES['OPTIONS']['context_processors']?"
+            )
+            _logger.error(msg)
+            return failure_context(dotted_path, ComponentCarrierError(msg))
+        _prerender_html = prerender_component(
+            user_component, args, kwargs, uuid, request
+        )
+
+    # Fetch the offline component's HTML, if requested
+    if offline:
+        offline_component = reactpy_config.REACTPY_REGISTERED_COMPONENTS.get(offline)
+        if not offline_component:
+            msg = f"Cannot render offline component '{offline}'. It is not registered as a component."
+            _logger.error(msg)
+            return failure_context(dotted_path, OfflineComponentMissing(msg))
+        if not request:
+            msg = (
+                "Cannot render an offline component without a HTTP request. Are you missing the "
+                "request context processor in settings.py:TEMPLATES['OPTIONS']['context_processors']?"
+            )
+            _logger.error(msg)
+            return failure_context(dotted_path, ComponentCarrierError(msg))
+        _offline_html = prerender_component(offline_component, [], {}, uuid, request)
+
+    # Return the template rendering context
+    return {
+        "reactpy_class": class_,
+        "reactpy_uuid": uuid,
+        "reactpy_host": host or perceived_host,
+        "reactpy_url_prefix": reactpy_config.REACTPY_URL_PREFIX,
+        "reactpy_component_path": f"{dotted_path}/{uuid}/{int(has_args)}/",
+        "reactpy_resolved_web_modules_path": RESOLVED_WEB_MODULES_PATH,
+        "reactpy_reconnect_interval": reactpy_config.REACTPY_RECONNECT_INTERVAL,
+        "reactpy_reconnect_max_interval": reactpy_config.REACTPY_RECONNECT_MAX_INTERVAL,
+        "reactpy_reconnect_backoff_multiplier": reactpy_config.REACTPY_RECONNECT_BACKOFF_MULTIPLIER,
+        "reactpy_reconnect_max_retries": reactpy_config.REACTPY_RECONNECT_MAX_RETRIES,
+        "reactpy_prerender_html": _prerender_html,
+        "reactpy_offline_html": _offline_html,
+    }
+
+
+@register.inclusion_tag("reactpy/pyscript_component.html", takes_context=True)
+def pyscript_component(
+    context: template.RequestContext,
+    *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.
+    """
+    if not file_paths:
+        raise ValueError(
+            "At least one file path must be provided to the 'pyscript_component' tag."
+        )
+
+    uuid = uuid4().hex
+    request: HttpRequest | None = context.get("request")
+    initial = vdom_or_component_to_string(initial, request=request, uuid=uuid)
+    executor = render_pyscript_template(file_paths, uuid, root)
+
+    return {
+        "pyscript_executor": executor,
+        "pyscript_uuid": uuid,
+        "pyscript_initial_html": initial,
+    }
+
+
+@register.inclusion_tag("reactpy/pyscript_setup.html")
+def pyscript_setup(
+    *extra_py: str,
+    extra_js: str | dict = "",
+    config: str | dict = "",
+):
+    """
+    Args:
+        extra_py: Dependencies that need to be loaded on the page for \
+            your PyScript components. Each dependency must be contained \
+            within it's own string and written in Python requirements file syntax.
+
+    Kwargs:
+        extra_js: A JSON string or Python dictionary containing a vanilla \
+            JavaScript module URL and the `name: str` to access it within \
+            `pyscript.js_modules.*`.
+        config: A JSON string or Python dictionary containing PyScript \
+            configuration values.
+    """
+    return {
+        "pyscript_config": extend_pyscript_config(extra_py, extra_js, config),
+        "pyscript_layout_handler": PYSCRIPT_LAYOUT_HANDLER,
+        "reactpy_debug_mode": reactpy_config.REACTPY_DEBUG_MODE,
+    }
+
+
+def failure_context(dotted_path: str, error: Exception):
+    return {
+        "reactpy_failure": True,
+        "reactpy_debug_mode": reactpy_config.REACTPY_DEBUG_MODE,
+        "reactpy_dotted_path": dotted_path,
+        "reactpy_error": type(error).__name__,
+    }

reactpy_django/types.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    MutableMapping,
+    NamedTuple,
+    Protocol,
+    Sequence,
+    TypeVar,
+    Union,
+)
+
+from django.http import HttpRequest
+from reactpy.types import Connection
+from typing_extensions import ParamSpec
+
+if TYPE_CHECKING:
+    from reactpy_django.websocket.consumer import ReactpyAsyncWebsocketConsumer
+
+
+FuncParams = ParamSpec("FuncParams")
+Inferred = TypeVar("Inferred")
+ConnectionType = Connection[Union["ReactpyAsyncWebsocketConsumer", HttpRequest]]
+
+
+@dataclass
+class Query(Generic[Inferred]):
+    """Queries generated by the `use_query` hook."""
+
+    data: Inferred
+    loading: bool
+    error: Exception | None
+    refetch: Callable[[], None]
+
+
+@dataclass
+class Mutation(Generic[FuncParams]):
+    """Mutations generated by the `use_mutation` hook."""
+
+    execute: Callable[FuncParams, None]
+    loading: bool
+    error: Exception | None
+    reset: Callable[[], None]
+
+    def __call__(self, *args: FuncParams.args, **kwargs: FuncParams.kwargs) -> None:
+        """Execute the mutation."""
+        self.execute(*args, **kwargs)
+
+
+class AsyncPostprocessor(Protocol):
+    async def __call__(self, data: Any) -> Any: ...
+
+
+class SyncPostprocessor(Protocol):
+    def __call__(self, data: Any) -> Any: ...
+
+
+@dataclass
+class ComponentParams:
+    """Container used for serializing component parameters.
+    This dataclass is pickled & stored in the database, then unpickled when needed."""
+
+    args: Sequence
+    kwargs: MutableMapping[str, Any]
+
+
+class UserData(NamedTuple):
+    query: Query[dict | None]
+    mutation: Mutation[dict]
+
+
+class AsyncMessageReceiver(Protocol):
+    async def __call__(self, message: dict) -> None: ...
+
+
+class AsyncMessageSender(Protocol):
+    async def __call__(self, message: dict) -> None: ...