feat: implement HTMX plugin using litestar-htmx (#3837)

* feat: implement `htmx` plugin

* chore: various linting fixes after upgrades

* fix: correct import

* fix: address flaky tests

It looks like `.xml` file extensions are read as `text/xml` instead of `application/xml`.

Trio backend has some flaky tests on for the Server Side Sesssion backends.

* fix: updated documentation

* chore: bump min version

* fix: expose HTMXConfig

.pre-commit-config.yaml

@@ -1,13 +1,13 @@
 default_language_version:
-  python: "3.8"
+  python: "3"
 repos:
   - repo: https://github.com/compilerla/conventional-pre-commit
-    rev: v3.4.0
+    rev: v3.6.0
     hooks:
       - id: conventional-pre-commit
         stages: [commit-msg]
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-ast
       - id: check-case-conflict
@@ -24,7 +24,7 @@ repos:
       - id: unasyncd
         additional_dependencies: ["ruff"]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.6.2"
+    rev: "v0.7.0"
     hooks:
       - id: ruff
         args: ["--fix"]
@@ -43,7 +43,7 @@ repos:
         exclude: "test*|examples*|tools"
         args: ["--use-tuple"]
   - repo: https://github.com/sphinx-contrib/sphinx-lint
-    rev: "v0.9.1"
+    rev: "v1.0.0"
     hooks:
       - id: sphinx-lint
   - repo: local

docs/conf.py

@@ -159,6 +159,7 @@
     (PY_CLASS, "litestar.contrib.sqlalchemy.dto.SQLAlchemyDTO"),
     (PY_CLASS, "litestar.contrib.sqlalchemy.types.BigIntIdentity"),
     (PY_CLASS, "litestar.contrib.sqlalchemy.types.JsonB"),
+    (PY_CLASS, "litestar.contrib.htmx.request.HTMXRequest"),
     (PY_CLASS, "litestar.typing.ParsedType"),
     (PY_METH, "litestar.dto.factory.DTOData.create_instance"),
     (PY_METH, "litestar.dto.interface.DTOInterface.data_to_encodable_type"),

docs/reference/plugins/htmx.rst

@@ -0,0 +1,7 @@
+====
+htmx
+====
+
+
+.. automodule:: litestar.plugins.htmx
+    :members:

docs/reference/plugins/index.rst

@@ -10,6 +10,7 @@ plugins
     :hidden:
 
     flash_messages
+    htmx
     problem_details
     structlog
     sqlalchemy

docs/usage/htmx.rst

@@ -8,16 +8,43 @@ HTMX is a JavaScript library that gives you access to AJAX, CSS Transitions, Web
 This section assumes that you have prior knowledge of HTMX.
 If you want to learn HTMX, we recommend consulting their `official tutorial <https://htmx.org/docs>`_.
 
+HTMXPlugin
+------------
+
+a Litestar plugin ``HTMXPlugin`` is available to easily configure the default request class for all Litestar routes.
+
+.. code-block:: python
+
+    from litestar.plugins.htmx import HTMXPlugin
+    from litestar import Litestar
+
+    from litestar.contrib.jinja import JinjaTemplateEngine
+    from litestar.template.config import TemplateConfig
+
+    from pathlib import Path
+
+    app = Litestar(
+        route_handlers=[get_form],
+        debug=True,
+        plugins=[HTMXPlugin()],
+        template_config=TemplateConfig(
+            directory=Path("litestar_htmx/templates"),
+            engine=JinjaTemplateEngine,
+        ),
+    )
+
+See :class:`~litestar.plugins.htmx.HTMXDetails` for a full list of
+available properties.
+
 HTMXRequest
 ------------
 
 A special :class:`~litestar.connection.Request` class, providing interaction with the
-HTMX client.
+HTMX client.  You can configure this globally by using the ``HTMXPlugin`` or by setting the `request_class` setting on any route, controller, router, or application.
 
 .. code-block:: python
 
-    from litestar.contrib.htmx.request import HTMXRequest
-    from litestar.contrib.htmx.response import HTMXTemplate
+    from litestar.plugins.htmx import HTMXRequest, HTMXTemplate
     from litestar import get, Litestar
     from litestar.response import Template
 
@@ -45,7 +72,7 @@ HTMX client.
         ),
     )
 
-See :class:`~litestar.contrib.htmx.request.HTMXDetails` for a full list of
+See :class:`~litestar.plugins.htmx.HTMXDetails` for a full list of
 available properties.
 
 
@@ -57,11 +84,11 @@ HTMXTemplate Response Classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The most common  use-case for HTMX to render an html page or html snippet. Litestar makes this easy by providing
-an :class:`~litestar.contrib.htmx.response.HTMXTemplate` response:
+an :class:`~litestar.plugins.htmx.HTMXTemplate` response:
 
 .. code-block:: python
 
-    from litestar.contrib.htmx.response import HTMXTemplate
+    from litestar.plugins.htmx import HTMXTemplate
     from litestar.response import Template
 
 
@@ -94,7 +121,7 @@ Litestar supports both of these:
 1 - Responses that don't make any changes to DOM
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use :class:`~litestar.contrib.htmx.response.HXStopPolling` to stop polling for a response.
+Use :class:`~litestar.plugins.htmx.HXStopPolling` to stop polling for a response.
 
 .. code-block:: python
 
@@ -103,7 +130,7 @@ Use :class:`~litestar.contrib.htmx.response.HXStopPolling` to stop polling for a
         ...
         return HXStopPolling()
 
-Use :class:`~litestar.contrib.htmx.response.ClientRedirect` to redirect with a page reload.
+Use :class:`~litestar.plugins.htmx.ClientRedirect` to redirect with a page reload.
 
 .. code-block:: python
 
@@ -112,7 +139,7 @@ Use :class:`~litestar.contrib.htmx.response.ClientRedirect` to redirect with a p
         ...
         return ClientRedirect(redirect_to="/contact-us")
 
-Use :class:`~litestar.contrib.htmx.response.ClientRefresh` to force a full page refresh.
+Use :class:`~litestar.plugins.htmx.ClientRefresh` to force a full page refresh.
 
 .. code-block:: python
 
@@ -124,7 +151,7 @@ Use :class:`~litestar.contrib.htmx.response.ClientRefresh` to force a full page
 2 - Responses that may change DOM
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use :class:`~litestar.contrib.htmx.response.HXLocation` to redirect to a new location without page reload.
+Use :class:`~litestar.plugins.htmx.HXLocation` to redirect to a new location without page reload.
 
 .. note:: This class provides the ability to change ``target``, ``swapping`` method, the sent ``values``, and the ``headers``.
 
@@ -144,7 +171,7 @@ Use :class:`~litestar.contrib.htmx.response.HXLocation` to redirect to a new loc
             values={"val": "one"},
         )  # values to submit with response.
 
-Use :class:`~litestar.contrib.htmx.response.PushUrl` to carry a response and push a url to the browser, optionally updating the ``history`` stack.
+Use :class:`~litestar.plugins.htmx.PushUrl` to carry a response and push a url to the browser, optionally updating the ``history`` stack.
 
 .. note:: If the value for ``push_url`` is set to ``False`` it will prevent updating browser history.
 
@@ -155,7 +182,7 @@ Use :class:`~litestar.contrib.htmx.response.PushUrl` to carry a response and pus
         ...
         return PushUrl(content="Success!", push_url="/about")
 
-Use :class:`~litestar.contrib.htmx.response.ReplaceUrl` to carry a response and replace the url in the browser's ``location`` bar.
+Use :class:`~litestar.plugins.htmx.ReplaceUrl` to carry a response and replace the url in the browser's ``location`` bar.
 
 .. note:: If the value to ``replace_url`` is set to ``False`` it will prevent updating the browser's location.
 
@@ -166,7 +193,7 @@ Use :class:`~litestar.contrib.htmx.response.ReplaceUrl` to carry a response and
         ...
         return ReplaceUrl(content="Success!", replace_url="/contact-us")
 
-Use :class:`~litestar.contrib.htmx.response.Reswap` to carry a response with a possible swap.
+Use :class:`~litestar.plugins.htmx.Reswap` to carry a response with a possible swap.
 
 .. code-block:: python
 
@@ -175,7 +202,7 @@ Use :class:`~litestar.contrib.htmx.response.Reswap` to carry a response with a p
         ...
         return Reswap(content="Success!", method="beforebegin")
 
-Use :class:`~litestar.contrib.htmx.response.Retarget` to carry a response and change the target element.
+Use :class:`~litestar.plugins.htmx.Retarget` to carry a response and change the target element.
 
 .. code-block:: python
 
@@ -184,7 +211,7 @@ Use :class:`~litestar.contrib.htmx.response.Retarget` to carry a response and ch
         ...
         return Retarget(content="Success!", target="#new-target")
 
-Use :class:`~litestar.contrib.htmx.response.TriggerEvent` to carry a response and trigger an event.
+Use :class:`~litestar.plugins.htmx.TriggerEvent` to carry a response and trigger an event.
 
 .. code-block:: python
 

litestar/contrib/htmx/_utils.py

@@ -1,12 +1,22 @@
 from __future__ import annotations
 
-from enum import Enum
-from typing import TYPE_CHECKING, Any, Callable, cast
-from urllib.parse import quote
+from typing import TYPE_CHECKING
 
-from litestar.exceptions import ImproperlyConfiguredException
-from litestar.serialization import encode_json
+from litestar.utils import warn_deprecation
 
+if TYPE_CHECKING:
+    from litestar_htmx._utils import (  # noqa: TCH004
+        HTMXHeaders,
+        get_headers,
+        get_location_headers,
+        get_push_url_header,
+        get_redirect_header,
+        get_refresh_header,
+        get_replace_url_header,
+        get_reswap_header,
+        get_retarget_header,
+        get_trigger_event_headers,
+    )
 __all__ = (
     "HTMXHeaders",
     "get_headers",
@@ -21,128 +31,21 @@
 )
 
 
-if TYPE_CHECKING:
-    from litestar.contrib.htmx.types import (
-        EventAfterType,
-        HtmxHeaderType,
-        LocationType,
-        PushUrlType,
-        ReSwapMethod,
-        TriggerEventType,
-    )
-
-HTMX_STOP_POLLING = 286
-
-
-class HTMXHeaders(str, Enum):
-    """Enum for HTMX Headers"""
-
-    REDIRECT = "HX-Redirect"
-    REFRESH = "HX-Refresh"
-    PUSH_URL = "HX-Push-Url"
-    REPLACE_URL = "HX-Replace-Url"
-    RE_SWAP = "HX-Reswap"
-    RE_TARGET = "HX-Retarget"
-    LOCATION = "HX-Location"
-
-    TRIGGER_EVENT = "HX-Trigger"
-    TRIGGER_AFTER_SETTLE = "HX-Trigger-After-Settle"
-    TRIGGER_AFTER_SWAP = "HX-Trigger-After-Swap"
-
-    REQUEST = "HX-Request"
-    BOOSTED = "HX-Boosted"
-    CURRENT_URL = "HX-Current-URL"
-    HISTORY_RESTORE_REQUEST = "HX-History-Restore-Request"
-    PROMPT = "HX-Prompt"
-    TARGET = "HX-Target"
-    TRIGGER_ID = "HX-Trigger"  # noqa: PIE796
-    TRIGGER_NAME = "HX-Trigger-Name"
-    TRIGGERING_EVENT = "Triggering-Event"
-
-
-def get_trigger_event_headers(trigger_event: TriggerEventType) -> dict[str, Any]:
-    """Return headers for trigger event response."""
-    after_params: dict[EventAfterType, str] = {
-        "receive": HTMXHeaders.TRIGGER_EVENT.value,
-        "settle": HTMXHeaders.TRIGGER_AFTER_SETTLE.value,
-        "swap": HTMXHeaders.TRIGGER_AFTER_SWAP.value,
-    }
-
-    if trigger_header := after_params.get(trigger_event["after"]):
-        return {trigger_header: encode_json({trigger_event["name"]: trigger_event["params"] or {}}).decode()}
-
-    raise ImproperlyConfiguredException(
-        "invalid value for 'after' param- allowed values are 'receive', 'settle' or 'swap'."
-    )
-
-
-def get_redirect_header(url: str) -> dict[str, Any]:
-    """Return headers for redirect response."""
-    return {HTMXHeaders.REDIRECT.value: quote(url, safe="/#%[]=:;$&()+,!?*@'~"), "Location": ""}
-
-
-def get_push_url_header(url: PushUrlType) -> dict[str, Any]:
-    """Return headers for push url to browser history response."""
-    if isinstance(url, str):
-        url = url if url != "False" else "false"
-    elif isinstance(url, bool):
-        url = "false"
-
-    return {HTMXHeaders.PUSH_URL.value: url}
-
-
-def get_replace_url_header(url: PushUrlType) -> dict[str, Any]:
-    """Return headers for replace url in browser tab response."""
-    url = (url if url != "False" else "false") if isinstance(url, str) else "false"
-    return {HTMXHeaders.REPLACE_URL: url}
-
-
-def get_refresh_header(refresh: bool) -> dict[str, Any]:
-    """Return headers for client refresh response."""
-    return {HTMXHeaders.REFRESH.value: "true" if refresh else ""}
-
-
-def get_reswap_header(method: ReSwapMethod) -> dict[str, Any]:
-    """Return headers for change swap method response."""
-    return {HTMXHeaders.RE_SWAP.value: method}
-
-
-def get_retarget_header(target: str) -> dict[str, Any]:
-    """Return headers for change target element response."""
-    return {HTMXHeaders.RE_TARGET.value: target}
-
-
-def get_location_headers(location: LocationType) -> dict[str, Any]:
-    """Return headers for redirect without page-reload response."""
-    if spec := {key: value for key, value in location.items() if value}:
-        return {HTMXHeaders.LOCATION.value: encode_json(spec).decode()}
-    raise ValueError("redirect_to is required parameter.")
+def __getattr__(attr_name: str) -> object:
+    if attr_name in __all__:
+        from litestar_htmx import _utils as utils
 
+        module = "litestar.plugins.htmx._utils"
+        value = globals()[attr_name] = getattr(utils, attr_name)
 
-def get_headers(hx_headers: HtmxHeaderType) -> dict[str, Any]:
-    """Return headers for HTMX responses."""
-    if not hx_headers:
-        raise ValueError("Value for hx_headers cannot be None.")
-    htmx_headers_dict: dict[str, Callable] = {
-        "redirect": get_redirect_header,
-        "refresh": get_refresh_header,
-        "push_url": get_push_url_header,
-        "replace_url": get_replace_url_header,
-        "re_swap": get_reswap_header,
-        "re_target": get_retarget_header,
-        "trigger_event": get_trigger_event_headers,
-        "location": get_location_headers,
-    }
+        warn_deprecation(
+            deprecated_name=f"litestar.contrib.htmx._utils.{attr_name}",
+            version="2.13",
+            kind="import",
+            removal_in="3.0",
+            info=f"importing {attr_name} from 'litestar.contrib.htmx._utils' is deprecated, please import it from '{module}' instead",
+        )
 
-    header: dict[str, Any] = {}
-    response: dict[str, Any]
-    key: str
-    value: Any
+        return value
 
-    for key, value in hx_headers.items():
-        if key in ["redirect", "refresh", "location", "replace_url"]:
-            return cast("dict[str, Any]", htmx_headers_dict[key](value))
-        if value is not None:
-            response = htmx_headers_dict[key](value)
-            header.update(response)
-    return header
+    raise AttributeError(f"module {__name__!r} has no attribute {attr_name!r}")