asgi-htmx 0.1.0

Description:

asgihtmx 0.1.0

asgi-htmx



HTMX integration for ASGI applications. Works with Starlette, FastAPI, Quart -- or any other web framework supporting ASGI that exposes the ASGI scope. Inspired by django-htmx.
Table of contents

Installation
Quickstart
API Reference

Installation
NOTE: This is alpha software. Please be sure to pin your dependencies.
pip install asgi-htmx==0.1.*

Quickstart
First, ensure HTMX is installed.
For example, download a copy of htmx.min.js, add it to your static files, then add the script tag to templates:
<script src="{{ url_for('static', path='/js/htmx.min.js') }}" defer></script>

Now, install HtmxMiddleware onto the ASGI app:


Using Starlette:
from asgi_htmx import HtmxMiddleware
from starlette.middleware import Middleware

app = Starlette(
middleware=[
...,
Middleware(HtmxMiddleware),
...,
],
)



Using FastAPI:
from asgi_htmx import HtmxMiddleware
from fastapi import FastAPI

app = FastAPI()
app.add_middleware(HtmxMiddleware)



You can now access scope["htmx"] (an instance of HtmxDetails) in endpoints:
# `HtmxRequest` makes code editors type-check `request.scope["htmx"]`
from asgi_htmx import HtmxRequest as Request

from .resources import templates

async def home(request: Request):
template = "home.html"
context = {"request": request}

if (htmx := request.scope["htmx"]):
template = "partials/items.html"
context["boosted"] = htmx.boosted # ...

return templates.TemplateResponse(template, context)

See examples for full working example code.
API Reference
HtmxMiddleware
An ASGI middleware that sets scope["htmx"] to an instance of HtmxDetails (scope refers to the ASGI scope).
app = HtmxMiddleware(app)

HtmxDetails
A helper that provides shortcuts for accessing HTMX-specific request headers.
htmx = HtmxDetails(scope)


__bool__() -> bool - Return True if the request was made using HTMX (HX-Request is present), False otherwise.
boosted: bool - Mirrors the HX-Boosted header: True if the request is via an element with the hx-boost attribute.
current_url: str | None - Mirrors the HX-Current-URL header: The current URL of the browser, or None for non-HTMX requests.
history_restore_request: str - Mirrors the HX-History-Restore-Request header: True if the request is for history restoration after a miss in the local history cache.
prompt: str | None - Mirrors HX-Prompt: The user response to hx-prompt if it was used, or None.
target: str | None - Mirrors HX-Target: The id of the target element if it exists, or None.
trigger: str | None - Mirrors HX-Trigger: The id of the trigger element if it exists, or None.
trigger_name: str | None - Mirrors HX-Trigger-Name: The name of the trigger element if it exists, or None.
triggering_event: Any | None - Mirrors Triggering-Event, which is set by the event-header extension: The deserialized JSON representation of the event that triggered the request if it exists, or None.

HtmxRequest
For Starlette-based frameworks, use this instead of the standard starlette.requests.Request so that code editors understand that request.scope["htmx"] contains an HtmxDetails instance:
from asgi_htmx import HtmxRequest as Request

async def home(request: Request):
reveal_type(request.scope["htmx"]) # Revealed type is 'HtmxDetails'

License
MIT
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog.
0.1.0 - 2022-05-30
Initial release
Added

Add HtmxDetails that facilitates working with HX-* request headers.
Add HtmxMiddleware that automatically adds an HtmxDetails instance as scope["htmx"].
Add HtmxRequest that facilitates type hinting request.scope["htmx"] in Starlette-based frameworks.