dj-hyperview

Server-driven Hyperview UI for Django, with every screen owned by your project. Resolve, render, validate, cache, and publish mobile UI from filesystem or database templates without bundling application screens into the package.

• Consumer-owned screens — keep XML and HXML inside the Django project that defines the mobile application.
• Ordered template sources — resolve from configured filesystem directories, the optional database app, or custom source backends with explicit precedence.
• Live database publication — edit validated templates through Django admin and expose committed changes on the next request, with an optional HXML-aware Ace editor.
• Cache consistency — opt into a compatible Django cache backend, including Redis, with source-aware keys and generation-based invalidation. File-based caches are not supported.
• Optional realtime hints — use [realtime] for Redis-backed after-commit SSE invalidation, with exact v1 compatibility and negotiated opaque v2 change metadata. The application still owns authentication, client adaptation and safe screen refresh. Follow the SSE guide.
• Django-native HTTP integration — use lazy template responses, class-based views, validated fragment responses, request detection middleware that attaches claimed client metadata, and standard CSRF protection.
• Fail-closed validation — enforce canonical names, UTF-8, XML safety, configurable resource limits, and automatic XSD 1.1 validation against one corrected Hyperview 0.111.0 schema plus explicit project extensions.

dj-hyperview does not ship application screens, runtime application HXML, mobile components, Redis, or a required database app. Those choices remain under the consumer project's control.

Example application

HyperTodo is the maintained test application for dj-hyperview. It combines a Django backend with an Expo mobile client and exercises filesystem and database templates, Admin editing, fragment updates, custom HXML components, light and dark themes, English and Spanish localization, biometric sign-in, and realtime SSE refresh. Its Redis template cache is enabled only by the backend-run-redis and backend-run-device workflows, and an avatar travels as a base64 form field, not a multipart upload.

Release maturity

This documentation covers 0.1.0b4, which reduces repeated template compilation, rendered-document validation and Admin draft-check work. It retains the security and reliability corrections of 0.1.0b3 and the corrected Hyperview 0.111.0 contract introduced in 0.1.0b2, now with the flatter bundled schema revision r4. The earlier 0.1.0b1 release used Hyperview 0.110.0. Entries under Unreleased in the changelog describe changes that are not part of any release yet. Read the beta compatibility policy and verified scope and deployment limits. The roadmap separates current capabilities from future work. Beta invites integration feedback; it does not guarantee production suitability.

Requirements

• Tested Python: 3.12, 3.13, or 3.14
• Django: 5.2 or 6.1
• lxml: 6.1.3 or newer, below 7
• Hyperview contract (0.1.0b4): 0.111.0

Version 0.1.0b4 requires Python 3.12 or newer without an upper bound. CI tests Python 3.12 through 3.14; newer interpreters are not yet verified.

Installation

# uv (recommended)
uv add dj-hyperview

# pip
pip install dj-hyperview

Register the base Django application:

INSTALLED_APPS = [
    # Your project applications.
    "dj_hyperview",
]

The base app performs no database, cache, or network access during startup. Database-backed templates and admin integration are optional.

Schema validation is automatic: xmlschema is a normal dependency, with no profile or enable flag. The deprecated [schema] extra remains an empty compatibility alias. Install the optional Admin authoring tools separately:

uv add "dj-hyperview[editor]"

The editor adds HXML completion, formatting, and context-free validation of unsaved source. Enable only that editor explicitly:

from django.http import HttpRequest

INSTALLED_APPS = [
    "django_ace",
    "dj_hyperview",
    "dj_hyperview.contrib.database",
]


def can_edit_hyperview(request: HttpRequest) -> bool:
    """Your project's own policy: who may change stored templates."""
    return request.user.has_perm("dj_hyperview_database.change_hyperviewtemplate")


HYPERVIEW = {
    "ADMIN": {
        "EDITOR": True,
        "PERMISSION": can_edit_hyperview,
    },
}

Stored templates execute as Django template code. Template mutations therefore default to superusers only; omit PERMISSION to keep that default. can_edit_hyperview above is your project's own function, not part of the package. ADMIN.PERMISSION may be a callable receiving the current request or a dotted path to one; it must return the literal boolean True to grant add, change, and delete access.

Quick start

Create hyperview/screens/home.xml inside the consumer project:

<?xml version="1.0" encoding="UTF-8"?>
<doc xmlns="https://hyperview.org/hyperview">
  <screen id="home">
    <body>
      <view>
        <text>Hello from Django</text>
      </view>
    </body>
  </screen>
</doc>

Configure the filesystem source in settings.py:

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

HYPERVIEW = {
    "TEMPLATE_DIRS": [BASE_DIR / "hyperview"],
    "SOURCES": [
        {"BACKEND": "dj_hyperview.sources.FileSystemSource"},
    ],
}

Expose the screen through Django's URL configuration:

from django.urls import path

from dj_hyperview import HyperviewTemplateView

urlpatterns = [
    path(
        "hyperview/home/",
        HyperviewTemplateView.as_view(template_name="screens/home.xml"),
        name="hyperview-home",
    ),
]

A request to /hyperview/home/ returns the rendered document as application/vnd.hyperview+xml.

Configuration

All package settings live under the HYPERVIEW dictionary. Sources are queried in declaration order, and the first match wins:

HYPERVIEW = {
    "TEMPLATE_DIRS": [BASE_DIR / "hyperview"],
    "SOURCES": [
        {"BACKEND": "dj_hyperview.contrib.database.sources.DatabaseSource"},
        {"BACKEND": "dj_hyperview.sources.FileSystemSource"},
    ],
}

To publish templates through the database and Django admin, add the optional app and run migrations:

INSTALLED_APPS = [
    # Django applications used by your project.
    "django.contrib.admin",
    "dj_hyperview",
    "dj_hyperview.contrib.database",
]

python manage.py migrate

Caching remains disabled unless a non-empty HYPERVIEW["CACHE"] configuration is supplied. See the configuration and cache guides before enabling a shared backend.

Documentation

📚 Full documentation — including Installation, Quick Start, Mobile Getting Started, Configuration, Filesystem sources, Database and admin, Cache consistency, Security, HTTP responses, Changelog, and the public Python API.

The package is published at PyPI.

Development

See the contributing guide for the quality contract, supported test matrix, and release workflow.

uv sync --all-groups
uv run pytest
uv run ruff check .
uv run ruff format --check .

uv run pytest runs the base profile only. The Admin tests (tests/test_database_admin*.py) need --ds=tests.settings_database_admin and are reported as skipped otherwise. uv run python -m tools.test_matrix --django-version 6.1.1 runs both profiles and enforces the coverage gate.

License

dj-hyperview is distributed under the MIT License.