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 <https://htmx.org/essays/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