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.110.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 targets 0.1.0b1, the first beta in the 0.1 line. 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.110.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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dj_hyperview-0.1.0b1.tar.gz (109.0 kB view details)

Uploaded Sep 11, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

dj_hyperview-0.1.0b1-py3-none-any.whl (139.3 kB view details)

Uploaded Sep 11, 2026 Python 3

File details

Details for the file dj_hyperview-0.1.0b1.tar.gz.

File metadata

Download URL: dj_hyperview-0.1.0b1.tar.gz
Upload date: Sep 11, 2026
Size: 109.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for dj_hyperview-0.1.0b1.tar.gz
Algorithm	Hash digest
SHA256	`fff5a737348ea1ddb568f904b8cfc5bf4963eb3ab50aaf63d321bf152a633734`
MD5	`03ec2188272888de59f0ccc23fdb8183`
BLAKE2b-256	`7abebd6e7d8005d0e23c5cdcdea6c27116871b24e84f72514b3d6d766ee92c29`

See more details on using hashes here.

Provenance

The following attestation bundles were made for dj_hyperview-0.1.0b1.tar.gz:

Publisher: release.yml on eamigo86/dj-hyperview

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: dj_hyperview-0.1.0b1.tar.gz
- Subject digest: fff5a737348ea1ddb568f904b8cfc5bf4963eb3ab50aaf63d321bf152a633734
- Sigstore transparency entry: 2789509172
- Sigstore integration time: Sep 11, 2026
Source repository:
- Permalink: eamigo86/dj-hyperview@5d19c22df13e52c5238178f44962806982a7d956
- Branch / Tag: refs/tags/v0.1.0b1
- Owner: https://github.com/eamigo86
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@5d19c22df13e52c5238178f44962806982a7d956
- Trigger Event: push