Pre-release

This release is a pre-release and may not be stable for production use.

dj-hyperview

PyPI - Python Version Django Versions PyPI Downloads Ruff

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 metadata, content negotiation, 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 demonstrates filesystem and database templates, fragment updates, shared caching, custom HXML components, themes, localization, biometrics, and file uploads.

Release maturity

This documentation covers 0.1.0b2, which validates Hyperview 0.111.0. The earlier 0.1.0b1 release used Hyperview 0.110.0. Confirm b2 publication on PyPI before installing it. 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. For a source candidate, confirm publication and the required release checks before installing the registry version.

Requirements

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

Installation

# uv (recommended)
uv add dj-hyperview

# pip
pip install dj-hyperview

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:

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

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

Stored templates execute as Django template code. Template mutations therefore default to superusers only. 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 .

License

dj-hyperview is distributed under the MIT License.

Release files for dj-hyperview 0.1.0b2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dj-hyperview 0.1.0b2
File	Size	Uploaded
dj_hyperview-0.1.0b2.tar.gz	134.2 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dj-hyperview 0.1.0b2
File	Interpreter	ABI	Platform	Reset
dj_hyperview-0.1.0b2-py3-none-any.whl 167.9 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 302.1 kB

Release files / dj_hyperview-0.1.0b2.tar.gz

Download URL	dj_hyperview-0.1.0b2.tar.gz
Size	134.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`43c465236cc31a4e1dda8dbfacbf6f9e80de418685c1355b2b35234c1e8805c9`
BLAKE2b-256 checksum How to use checksums	`4ce30ab521db3dcfc544537180b02361ec0bdd54256668c0fb17825e0eab5d56`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/eamigo86/dj-hyperview
Publishing commit: github.com/eamigo86/dj-hyperview/tree/be3b502f63a2942de34a7336bf592b46c518737c

Workflow

Publishing configuration: github.com/eamigo86/dj-hyperview/blob/be3b502f63a2942de34a7336bf592b46c518737c/.github/workflows/release.yml
Publishing logs: github.com/eamigo86/dj-hyperview/actions/runs/36036756956/attempts/1

Artifact

Subject: dj_hyperview-0.1.0b2.tar.gz
SHA-256 checksum: 43c465236cc31a4e1dda8dbfacbf6f9e80de418685c1355b2b35234c1e8805c9 Verifying attestations

Release files / dj_hyperview-0.1.0b2-py3-none-any.whl

Download URL	dj_hyperview-0.1.0b2-py3-none-any.whl
Size	167.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3dfe0bc6ecf6d7973eccee0cefefad04ddc5a1fec03b799f0eb2307a4ca9051b`
BLAKE2b-256 checksum How to use checksums	`c54b230d1b339ae3aa79e7b707f3584ae4c09d16af2a8a6ed7545fa1a89c78d1`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/eamigo86/dj-hyperview
Publishing commit: github.com/eamigo86/dj-hyperview/tree/be3b502f63a2942de34a7336bf592b46c518737c

Workflow

Publishing configuration: github.com/eamigo86/dj-hyperview/blob/be3b502f63a2942de34a7336bf592b46c518737c/.github/workflows/release.yml
Publishing logs: github.com/eamigo86/dj-hyperview/actions/runs/36036756956/attempts/1

Artifact

Subject: dj_hyperview-0.1.0b2-py3-none-any.whl
SHA-256 checksum: 3dfe0bc6ecf6d7973eccee0cefefad04ddc5a1fec03b799f0eb2307a4ca9051b Verifying attestations