Introduction

What is djxi?

djxi is a small utility library that solves the HTMX scattering problem in Django projects.

Using HTMX with vanilla Django typically means spreading each partial interaction across three separate files: a URL pattern in urls.py, a handler in views.py, and a template snippet somewhere in templates/. As the number of HTMX-powered interactions grows, so does the cognitive overhead of navigating between those files.

djxi addresses this by introducing the DXEndpointBattery — a class that bundles the URL patterns, handler methods, and template sections for a feature into a single, self-contained unit, following the Locality of Behaviour principle.

Key concepts

DXEndpointBattery

The central class. Inherit from it, set inline_template or template_name, decorate methods with routing decorators, then wire the class into your URLConf with url_patterns().

Named sections (<dx-section>)

Templates are split into named blocks using a custom HTML tag. Each block can be rendered independently via render_section(request, name, context). Sections can embed other sections using <dx-include name="..."/>.

Routing decorators

@dx_get, @dx_post, @dx_put, @dx_patch, @dx_delete, and the generic @dx_action mark methods as URL endpoints. DXEndpointBattery.url_patterns() converts them into Django path() entries you include in your urlpatterns.

battery_prefix

Each battery can declare its own URL prefix via the battery_prefix class attribute, avoiding the need to repeat the prefix in every urls.py.

Async handlers

Battery methods defined with async def are served as proper ASGI views. arender_section() provides an awaitable counterpart to render_section().

Permission hooks

requires_auth, login_url, and check_permissions() gate access to all endpoints on a battery without needing per-view decorators.

HTMX header helpers

The optional middleware attaches request.htmx (read HX-* request headers) and response.htmx (set HX-* response headers) to every request/response pair. All response setters support fluent chaining.

Django messages integration

Django’s built-in messaging framework is wired into every response via HTMX hx-swap-oob injection so flash messages work without a full page reload.

Testing utilities

djxi.testing ships DXRequestFactory (middleware-aware), standalone assertion helpers, and DXBatteryTestCase to make battery tests concise and self-contained.

djxi_routes command

python manage.py djxi_routes prints a table of every registered battery route — useful for debugging URL configuration.

Compatibility

  • Python 3.8 – 3.12

  • Django 4.2, 5.2, 6.0

  • HTMX 2.x and 4.x (selected via DX_HTMX_VERSION)

  • Fully typed: ships py.typed for PEP 561 compliance