API Reference¶

Step-by-step SSE guide: setup, negotiated changes, compatibility examples and host responsibilities.

Import documented public objects from dj_hyperview; catalog helpers are in dj_hyperview.schema and text validators are in dj_hyperview.validators. Modules and names beginning with an underscore remain implementation details.

Beta compatibility policy¶

Use the documented public APIs; test your integration before upgrading. 0.1.0b1 starts the 0.1 beta line. This is a prerelease for integration feedback, not a blanket production-readiness guarantee. Entries under Unreleased in the changelog are changes that are not part of any release.

Within the 0.1 beta line, maintainers will preserve the documented public Python imports and call contracts, configuration keys, source protocol, HTTP media types, and versioned schema/SSE contracts. Additive APIs may be introduced; existing documented integrations should not require changes simply to upgrade to the next beta in the same line. Supported Python/Django removals also count as compatibility changes. The verified scope limits what has actually been tested; it is not a guarantee for every deployment.

If an incompatible change is necessary, the same release must:

1. Mark it explicitly as a Breaking change in the changelog.
2. Explain the affected APIs/clients, migration steps and rollback constraints.
3. Include regression tests for the replacement and the retained compatibility path, or for an explicit rejection when that old path cannot remain safe.

Security fixes may require a faster incompatible change without a normal advance deprecation period. They still require a documented security rationale, upgrade guidance and regression tests; unsafe behavior is not preserved merely to keep an old integration working.

This commitment covers the surfaces documented here and in the linked configuration, database services, schema extensions and HTTP guides. Underscore-prefixed internals, cache serialization, Admin DOM/editor internals and test helpers are not extension APIs unless explicitly documented as such. A template revision is a concurrency/cache identity, not a stored history or an application-version selector.

The consumer still owns authentication, authorization, CSRF, business data, routes, native components and capability negotiation. An untrusted client version or mutation marker never grants permissions. SSE v2 requires compatible backend readers and an adapted client; preserve v1 projection during a coordinated rollout or rollback. See the SSE guide.

Resolution and sources¶

A TemplateSource requires only resolve(name), which returns a ResolvedTemplate or None for a source-local miss. The resolver checks the result: its name must equal the requested canonical name and all five fields must be str, otherwise SourceUnavailable is raised instead of using or caching it. Fields that a subclass adds are not checked and are not cached: the cache holds the five. A source may also expose an optional cacheable attribute, False unless declared. The resolver caches a source only when cacheable is exactly True, so a source that does not declare it is read on every lookup. FileSystemSource reports cacheable = True; DatabaseSource reports True only with an explicit using alias. Both report it only while resolve() is their own, so a subclass that overrides resolve() must declare cacheable = True itself. Declare cacheable = True in a custom source only when its output depends solely on the template name and the constructor options, never on ambient state such as the current tenant, user or request. Other subclasses inherit the attribute. See cache consistency.

Rendering and HTTP¶

All package render methods, including compiled templates from get_template() and select_template(), validate final output automatically. engine.backend is the underlying low-level Django backend, not a validated rendering API.

HTTP body construction, assignment, write(), and writelines() validate the complete candidate before changing stored bytes. See HTTP responses for bodyless statuses, HEAD request context, and lazy callback semantics.

Request detection¶

Detection reads client-controlled headers, so it identifies a claimed client and never establishes trust. The middleware adds no Vary header; see Detect Hyperview clients for setup, request.hyperview and caching. A present X-Hyperview-Version header marks the request as Hyperview, but version keeps its value only when it matches [0-9A-Za-z][0-9A-Za-z.+_-]{0,63}; any other value, including an empty one, leaves version as None. An explicit Hyperview media type counts only when Django can parse the Accept header. Django 6.1 refuses to parse a media range longer than 10,000 characters, and the middleware then treats the header as not accepting Hyperview instead of failing the request. Django 5.2 has no such limit and parses the header normally.

Validation and cache¶

XML text safety¶

A rendered document that still contains such a character fails with TemplateValidationError code malformed_xml and a fixed message; nothing is stripped silently. See Security.

Committed template invalidations¶

TemplateInvalidation and template_invalidated are public in dj_hyperview and dj_hyperview.signals. The frozen event has names: frozenset[str] and using: str; construction validates canonical names and snapshots mutable inputs.

from django.dispatch import receiver
from dj_hyperview.signals import template_invalidated


@receiver(template_invalidated)
def templates_changed(sender, event, **kwargs):
    # Map event.names and event.using to application-owned invalidation policy.
    pass

The optional database contribution sends sender=HyperviewTemplate, event=event after commit on the mutation alias. Model saves/deletes, publication services, controlled QuerySet updates/deletes and bulk operations share the existing invalidation scheduler. Renames include old and new names. Empty/irrelevant writes and rollbacks emit nothing; conflict-ignored inserts can conservatively include names that did not change. Multiple callbacks in a transaction are not coalesced.

Cache invalidation runs first; send_robust runs in the same callback's finally, even with caching disabled or a cache exception. Receiver exceptions are isolated by Django; the original cache exception still propagates after the database commit. These are best-effort hints, not durable delivery or proof that content changed. Earlier failing commit callbacks can prevent later callbacks, as in Django itself. No Redis, watcher, filesystem-deploy hook or network transport is enabled. Calling invalidate_templates() directly still only invalidates cache.

Exceptions¶

HyperviewError is the package base exception. Its public specializations are HyperviewConfigurationError, InvalidTemplateName, TemplateNotFound, TemplateValidationError, and SourceUnavailable.

TemplateValidationError exposes the stable code and message fields plus optional one-based line and column coordinates. Its string form never includes rejected source content or internal filesystem paths.

Resource-limit failures use the codes max_bytes, max_depth, max_nodes, max_attributes, and max_unclosed. The first three match the VALIDATION settings of the same names; max_attributes reports the fixed caps of 128 attributes and 8 in-scope namespaces on one element, and of 32 namespace declarations on the path from the root to one element. max_unclosed applies to template source only: it reports a fixed limit on the work that unclosed {{, {% and {# delimiters cost Django's lexer (see Security).

Database publication is an optional contribution with its own service boundary. See Database source and admin for those imports.

Realtime transport (optional)¶

from dj_hyperview.conf import RealtimeSettings, get_settings exposes the normalized HYPERVIEW["REALTIME"] configuration. get_settings().realtime is None when omitted/disabled, or frozen RealtimeSettings(redis_url, namespace). The URL is excluded from repr. An enabled mapping requires exactly REDIS_URL and NAMESPACE; invalid settings produce check dj_hyperview.E022 and raise HyperviewConfigurationError, not a disabled fallback. REALTIME.ALIAS is not supported. Reading these settings neither imports redis-py nor connects. A valid configuration without redis-py installed produces the check warning dj_hyperview.W007.

Import from dj_hyperview.realtime; none of these symbols connects at import:

• INVALIDATION_VERSIONS == (1, 2) lists supported invalidate schemas as an immutable tuple; it does not enable client negotiation automatically.
• RedisBroker(url, namespace) validates immutable server configuration.
• broker.publish_after_commit(event, topics, *, using) captures input and schedules a bounded, best-effort committed hint; return value is None, not a delivery acknowledgement. Invalid inputs raise ValueError before scheduling.
• await broker.subscribe(topics) returns the Subscription protocol only after all ACKs; its first envelope is resync. Transport/setup failures raise RealtimeUnavailable with a fixed message. async for consumes closed envelopes; await subscription.aclose() closes ownership once.
• realtime_asgi(application) wraps the outer Django ASGI application once; this owns request cleanup across synchronous middleware adapters.
• sse_response(async_events, *, aclose) transfers an iterator and explicit owner inside that active scope. None emits a heartbeat comment.

Envelope fields, framing and cooperative cleanup requirements are in HTTP responses. Broker configuration defines URL, namespace, topic, queue and deadline limits. None of these APIs selects users, grants authorization, transports HXML or acknowledges a mobile layout commit.