djhtmx 1.2.6__py3-none-any.whl

djhtmx/testing.py

@@ -0,0 +1,194 @@
+from collections import defaultdict
+from collections.abc import Callable, Iterable
+from functools import reduce
+from typing import Any, ParamSpec, TypeVar
+from urllib.parse import urlparse
+
+from django.contrib.auth.models import AnonymousUser
+from django.test import Client
+from lxml import html
+from pygments import highlight
+from pygments.formatters import TerminalTrueColorFormatter
+from pygments.lexers import HtmlLexer
+
+from . import json
+from .commands import PushURL, ReplaceURL, SendHtml
+from .component import Destroy, DispatchDOMEvent, Focus, HtmxComponent, Open, Redirect
+from .introspection import parse_request_data
+from .repo import Repository, Session, signer
+from .utils import get_params
+
+P = ParamSpec("P")
+TPComponent = TypeVar("TPComponent", bound=HtmxComponent)
+
+
+class Htmx:
+    def __init__(self, client: Client):
+        self.client = client
+
+    def navigate_to(self, url: str, *args, **kwargs):
+        kwargs.setdefault("follow", True)
+        response = self.client.get(url, *args, **kwargs)
+        assert 200 <= response.status_code < 300
+        self.path = response.request["PATH_INFO"]
+        self.query_string = response.request["QUERY_STRING"]
+
+        self.dom = html.fromstring(response.content)
+        session_id = reduce(
+            lambda session, element: (
+                session or json.loads(element.attrib["hx-headers"]).get("HX-Session")
+            ),
+            self.dom.cssselect("[hx-headers]"),
+            None,
+        )
+        assert session_id, "Can't find djhtmx session id"
+        session_id = signer.unsign(session_id)
+
+        self.repo = Repository(
+            user=response.context.get("user") or AnonymousUser(),
+            session=Session(session_id),
+            params=get_params(self.query_string),
+        )
+
+    def get_component_by_type(self, component_type: type[TPComponent]) -> TPComponent:
+        [component] = self.repo.get_components_by_names(component_type.__name__)
+        return component  # type: ignore
+
+    def get_components_by_type(self, component_type: type[TPComponent]) -> Iterable[TPComponent]:
+        return self.repo.get_components_by_names(component_type.__name__)  # type: ignore
+
+    def get_component_by_id(self, component_id: str):
+        component = self.repo.get_component_by_id(component_id)
+        assert isinstance(component, HtmxComponent)
+        return component
+
+    def type(self, selector: str | html.HtmlElement, text: str, clear=False):
+        """Sets the value of an input, by "typing" in to it"""
+        element = self._select(selector)
+        if (
+            element.tag == "input" and element.attrib.get("type", "text") == "text"
+        ) or element.tag == "textarea":
+            if clear:
+                element.attrib["value"] = text
+            else:
+                element.attrib["value"] = element.attrib.get("value", "") + text
+        else:
+            assert False, f"Can't type in element {element}"
+
+    def find_by_text(self, text: str) -> html.HtmlElement:
+        return self.dom.xpath(f"//*[text()='{text}']")
+
+    def select(self, selector: str) -> list[html.HtmlElement]:
+        return self.dom.cssselect(selector)
+
+    def print(self, element: html.HtmlElement):
+        print(
+            highlight(
+                html.tostring(element, pretty_print=True, encoding="unicode"),
+                HtmlLexer(),
+                TerminalTrueColorFormatter(),
+            )
+        )
+
+    def _select(self, selector: str | html.HtmlElement) -> html.HtmlElement:
+        if isinstance(selector, str):
+            [element] = self.dom.cssselect(selector)
+        else:
+            element = selector
+        return element
+
+    def trigger(self, selector: str | html.HtmlElement):
+        element = self._select(selector)
+
+        # mutate in case of a checkbox and radios
+        match element.tag, element.attrib.get("type"):
+            case "input", "checkbox":
+                if "checked" in element.attrib:
+                    element.attrib.pop("checked")
+                else:
+                    element.attrib["checked"] = ""
+            case "input", "radio":
+                if name := element.attrib.get("name"):
+                    for radio in self.dom.cssselect(f'input[type=radio][name="{name}"]'):
+                        radio.attrib.pop("checked", None)
+                element.attrib["checked"] = ""
+            case _:
+                pass
+
+        [_, component_id, event_handler] = element.attrib["hx-post"].rsplit("/", 2)
+
+        # gather values
+        vals = defaultdict(list)
+        if include := element.attrib.get("hx-include"):
+            for element in self.dom.cssselect(include):
+                name = element.attrib["name"]
+                value = element.attrib.get("value", "")
+                match element.tag, element.attrib.get("type"):
+                    case _, "checkbox":
+                        if "checked" in element.attrib:
+                            vals[name].append(value or "on")
+                    case _, "radio":
+                        if "checked" in element.attrib:
+                            vals[name].append(value)
+                    case "select", _:
+                        for option in element.cssselect("option[selected]"):
+                            vals[name].append(option.attrib.get("value", ""))
+                    case _, _:
+                        vals[name].append(value)
+
+        vals |= json.loads(element.attrib.get("hx-vals", "{}"))
+        self.dispatch_event(component_id, event_handler, parse_request_data(vals))
+
+    def send(self, method: Callable[P, Any], *args: P.args, **kwargs: P.kwargs):
+        assert not args, "All parameters have to be passed by name"
+        self.dispatch_event(method.__self__.id, method.__name__, kwargs)  # type: ignore
+
+    def dispatch_event(self, component_id: str, event_handler: str, kwargs: dict[str, Any]):
+        commands = self.repo.dispatch_event(component_id, event_handler, kwargs)
+        navigate_to_url = None
+        for command in commands:
+            match command:
+                case SendHtml(content):
+                    incoming = html.fromstring(content)
+                    oob: str = incoming.attrib["hx-swap-oob"]
+                    if oob == "true":
+                        target = self.dom.get_element_by_id(incoming.attrib["id"])
+                        if parent := target.getparent():
+                            parent.replace(target, incoming)
+                    elif oob.startswith("beforeend: "):
+                        target_selector = oob.removeprefix("beforeend: ")
+                        [target] = self.dom.cssselect(target_selector)
+                        target.append(incoming.getchildren()[0])
+                    elif oob.startswith("afterbegin: "):
+                        target_selector = oob.removeprefix("afterbegin: ")
+                        [target] = self.dom.cssselect(target_selector)
+                        target.insert(0, incoming.getchildren()[0])
+                    elif oob.startswith("afterend: "):
+                        target_selector = oob.removeprefix("afterend: ")
+                        [target] = self.dom.cssselect(target_selector)
+                        target.addnext(incoming.getchildren()[0])
+                    elif oob.startswith("beforebegin: "):
+                        target_selector = oob.removeprefix("afterend: ")
+                        [target] = self.dom.cssselect(target_selector)
+                        target.addprevious(incoming.getchildren()[0])
+                    else:
+                        assert False, "Unknown swap strategy, please define it here"
+
+                case Destroy(component_id):
+                    target = self.dom.get_element_by_id(component_id)
+                    if parent := target.getparent():
+                        parent.remove(target)
+
+                case Redirect(url) | Open(url):
+                    navigate_to_url = url
+
+                case PushURL(url) | ReplaceURL(url):
+                    parsed_url = urlparse(url)
+                    self.path = parsed_url.path
+                    self.query_string = parsed_url.query
+
+                case Focus() | DispatchDOMEvent():
+                    pass
+
+        if navigate_to_url:
+            self.navigate_to(navigate_to_url)

djhtmx/tracing.py

@@ -0,0 +1,52 @@
+import contextlib
+
+from djhtmx import settings
+
+# pragma: no cover
+
+try:
+    import sentry_sdk  # pyright: ignore[reportMissingImports]
+except ImportError:
+    sentry_sdk = None
+
+
+if settings.ENABLE_SENTRY_TRACING and sentry_sdk is not None:
+    sentry_start_span = sentry_sdk.start_span
+
+    @contextlib.contextmanager
+    def _sentry_span(name: str, **tags: str):  # pyright: ignore[reportRedeclaration]
+        with sentry_start_span(op="djhtmx", name=name) as span:
+            for tag, value in tags.items():
+                span.set_tag(tag, value)
+            yield span
+
+else:
+
+    @contextlib.contextmanager
+    def _sentry_span(description, **tags):
+        yield
+
+
+try:
+    import logfire  # pyright: ignore[reportMissingImports]
+except ImportError:
+    logfire = None
+
+
+if settings.ENABLE_LOGFIRE_TRACING and logfire is not None:
+    logfire_span = logfire.span
+
+    def _logfire_span(name: str, **tags):  # pyright: ignore[reportRedeclaration]
+        return logfire_span(name, op="djhtmx", **tags)
+
+else:
+
+    @contextlib.contextmanager
+    def _logfire_span(description, **tags):
+        yield
+
+
+@contextlib.contextmanager
+def tracing_span(name: str, **tags: str):
+    with _sentry_span(name, **tags), _logfire_span(name, **tags):
+        yield

djhtmx/urls.py

@@ -0,0 +1,108 @@
+from functools import partial
+from http import HTTPStatus
+from typing import assert_never
+
+from django.apps import apps
+from django.core.signing import Signer
+from django.http.request import HttpRequest
+from django.http.response import HttpResponse
+from django.urls import path, re_path
+from django.utils.html import format_html
+from django.views.decorators.csrf import csrf_exempt
+
+from .commands import PushURL, ReplaceURL, SendHtml
+from .component import REGISTRY, Destroy, DispatchDOMEvent, Focus, Open, Redirect, Triggers
+from .consumer import Consumer
+from .introspection import parse_request_data
+from .repo import Repository
+from .tracing import tracing_span
+
+signer = Signer()
+
+
+def endpoint(request: HttpRequest, component_name: str, component_id: str, event_handler: str):
+    if "HTTP_HX_SESSION" not in request.META:
+        return HttpResponse("Missing header HX-Session", status=HTTPStatus.BAD_REQUEST)
+
+    with tracing_span(f"{component_name}.{event_handler}"):
+        repo = Repository.from_request(request)
+        content: list[str] = []
+        headers: dict[str, str] = {}
+        triggers = Triggers()
+
+        for command in repo.dispatch_event(
+            component_id,
+            event_handler,
+            parse_request_data(request.POST | request.FILES)  # type: ignore[reportOperatorIssues]
+            | (
+                {"prompt": prompt}
+                if (prompt := request.META.get("HTTP_HX_PROMPT", None)) is not None
+                else {}
+            ),
+        ):
+            # Command loop
+            match command:
+                case Destroy(component_id):
+                    content.append(
+                        format_html(
+                            '<div id="{component_id}" hx-swap-oob="delete"></div>',
+                            component_id=component_id,
+                        )
+                    )
+                case Redirect(url):
+                    headers["HX-Redirect"] = url
+                case Focus(selector):
+                    triggers.after_settle("hxFocus", selector)
+                case Open(url, name, target, rel):
+                    triggers.after_settle(
+                        "hxOpenURL",
+                        {"url": url, "name": name, "target": target, "rel": rel},
+                    )
+                case DispatchDOMEvent(target, event, detail, bubbles, cancelable, composed):
+                    triggers.after_settle(
+                        "hxDispatchDOMEvent",
+                        {
+                            "event": event,
+                            "target": target,
+                            "detail": detail,
+                            "bubbles": bubbles,
+                            "cancelable": cancelable,
+                            "composed": composed,
+                        },
+                    )
+                case SendHtml(html):
+                    content.append(html)
+                case PushURL(url):
+                    headers["HX-Push-Url"] = url
+                case ReplaceURL(url):
+                    headers["HX-Replace-Url"] = url
+                case _ as unreachable:
+                    assert_never(unreachable)
+
+        return HttpResponse("\n\n".join(content), headers=headers | triggers.headers)
+
+
+APP_CONFIGS = sorted(apps.app_configs.values(), key=lambda app_config: -len(app_config.name))
+
+
+def app_name_of_component(cls: type):
+    cls_module = cls.__module__
+    for app_config in APP_CONFIGS:
+        if cls_module.startswith(app_config.name):
+            return app_config.label
+    return cls_module
+
+
+urlpatterns = [
+    path(
+        f"{app_name_of_component(component)}/{component_name}/<component_id>/<event_handler>",
+        csrf_exempt(partial(endpoint, component_name=component_name)),
+        name=f"djhtmx.{component_name}",
+    )
+    for component_name, component in REGISTRY.items()
+]
+
+
+ws_urlpatterns = [
+    re_path("ws", Consumer.as_asgi(), name="djhtmx.ws"),  # type: ignore
+]

djhtmx/utils.py

@@ -0,0 +1,145 @@
+import contextlib
+import importlib
+import pkgutil
+import typing as t
+from urllib.parse import urlparse
+
+import mmh3
+from channels.db import database_sync_to_async as db  # type: ignore
+from django.apps import apps
+from django.db import models
+from django.http.request import HttpRequest, QueryDict
+from uuid6 import uuid7
+
+from . import json
+
+if t.TYPE_CHECKING:
+    T = t.TypeVar("T")
+    P = t.ParamSpec("P")
+
+    def db(f: t.Callable[P, T]) -> t.Callable[P, t.Awaitable[T]]: ...  # noqa: UP047
+
+
+def get_params(obj: HttpRequest | QueryDict | str | None) -> QueryDict:
+    if isinstance(obj, HttpRequest):
+        is_htmx_request = json.loads(obj.META.get("HTTP_HX_REQUEST", "false"))
+        if is_htmx_request:
+            return QueryDict(
+                urlparse(obj.META["HTTP_HX_CURRENT_URL"]).query,
+                mutable=True,
+            )
+        else:
+            qd = QueryDict(None, mutable=True)
+            qd.update(obj.GET)
+            return qd
+    elif isinstance(obj, QueryDict):
+        qd = QueryDict(None, mutable=True)
+        qd.update(obj)  # type: ignore
+        return qd
+    elif isinstance(obj, str):
+        return QueryDict(
+            query_string=urlparse(obj).query if obj else None,
+            mutable=True,
+        )
+    else:
+        return QueryDict(None, mutable=True)
+
+
+def get_instance_subscriptions(
+    obj: models.Model,
+    actions: t.Sequence[str] = ("created", "updated", "deleted"),
+):
+    """Get the subscriptions to actions of a single instance of a model.
+
+    This won't return model-level subscriptions.
+
+    The `actions` is the set of actions to subscribe to, including any possible relation (e.g
+    'users.deleted').  If actions is empty, return only instance-level subscription.
+
+    """
+    cls = type(obj)
+    app = cls._meta.app_label
+    name = cls._meta.model_name
+    prefix = f"{app}.{name}.{obj.pk}"
+    if not actions:
+        return {prefix}
+    else:
+        return {f"{prefix}.{action}" for action in actions}
+
+
+def get_model_subscriptions(
+    obj: type[models.Model] | models.Model,
+    actions: t.Sequence[str | None] = (),
+) -> set[str]:
+    """Get the subscriptions to actions of the model.
+
+    If the `obj` is an instance of the model, return all the subscriptions
+    from actions.  If `obj` is just the model class, return the top-level
+    subscription.
+
+    The `actions` is the set of actions to subscribe to, including any
+    possible relation (e.g 'users.deleted').
+
+    """
+    actions = actions or (None,)
+    if isinstance(obj, models.Model):
+        cls = type(obj)
+        instance = obj
+    else:
+        cls = obj
+        instance = None
+    app = cls._meta.app_label
+    name = cls._meta.model_name
+    model_prefix = f"{app}.{name}"
+    prefix = f"{model_prefix}.{instance.pk}" if instance else model_prefix
+    result = {(f"{prefix}.{action}" if action else prefix) for action in actions}
+    return result
+
+
+def generate_id():
+    return f"hx-{uuid7().hex}"
+
+
+def compact_hash(value: str) -> str:
+    """Return a SHA1 using a base with 64+ symbols"""
+    # this returns a signed 32 bit number, we convert it to unsigned with `& 0xffffffff`
+    hashed_value = mmh3.hash(value) & 0xFFFFFFFF
+
+    # Convert the integer to the custom base
+    base_len = len(_BASE)
+    encoded = []
+    while hashed_value > 0:
+        hashed_value, rem = divmod(hashed_value, base_len)
+        encoded.append(_BASE[rem])
+
+    return "".join(encoded)
+
+
+# The order of the base is random so that it doesn't match anything out there.
+# The symbols are chosen to avoid extra encoding in the URL and HTML, and
+# allowed in plain CSS selectors.
+_BASE = "ZmBeUHhTgusXNW_Y1b05KPiFcQJD86joqnIRE7Lfkrdp3AOMCvltSwzVG9yxa42"
+
+
+def autodiscover_htmx_modules():
+    """
+    Auto-discover HTMX modules in Django apps.
+
+    This discovers both:
+    - htmx.py files (like standard autodiscover_modules("htmx"))
+    - All Python files under htmx/ directories in apps (recursively)
+    """
+
+    def _import_modules_recursively(module_name):
+        """Recursively import a module and all its submodules."""
+        with contextlib.suppress(ImportError):
+            module = importlib.import_module(module_name)
+
+            # If this is a package, recursively import all modules in it
+            if hasattr(module, "__path__"):
+                for _finder, submodule_name, _is_pkg in pkgutil.iter_modules(module.__path__):
+                    _import_modules_recursively(f"{module_name}.{submodule_name}")
+
+    for app_config in apps.get_app_configs():
+        # Import htmx module and all its submodules recursively
+        _import_modules_recursively(f"{app_config.name}.htmx")