Skip to content

Rendering API

Stability

Classifications for this surface are recorded in STABILITY.md. Package maturity (Beta/Alpha) is separate from API level (beta / experimental / internal / deferred).

Status: Accepted

Signatures

Generated parameter lists: Autodoc — Page, component, and rendering. This page is the how-to narrative for the framework-neutral render boundary.

The public core rendering boundary is intentionally small:

from hedron_core import RenderContext, RenderMode, RenderResult, RenderSession, render

context = RenderContext.standalone(locale="en", theme="default")
result = render(component, context=context, mode=RenderMode.FRAGMENT)
html_text = result.html

Types

  • NodeLike: the public recursive typing alias for accepted render inputs and component returns, including a component, native HTML node, string, supported sequence, or None.
  • ComponentNode: an opaque protocol implemented by public component and native-node values; objects exposing __hedron_node__() are accepted by render. Concrete normalized serializer nodes stay private.
  • RenderMode: PAGE or FRAGMENT in the phase 0.1 contract shipping in v0.1.0.
  • RenderContext: immutable framework-neutral rendering context. RenderContext.standalone(*, locale="en", theme=None) creates the supported direct-rendering context; framework adapters derive request contexts without storing a raw request, session, or dependency object in it.
  • RenderResult: immutable result with html: str, mode: RenderMode, assets, approved headers, identity_map, diagnostics, and an optional redacted trace. Collection fields are immutable snapshots.
  • RenderSession: request-scoped renderer that preserves identity allocation, diagnostics, cycle detection, and resource accounting across multiple render(...) calls. Each returned RenderResult contains only that call's identity and diagnostic deltas while its trace reports session totals.

render(value, *, context=None, mode=RenderMode.FRAGMENT) -> RenderResult is the advanced framework-neutral entry point. Ordinary application code returns components and lets its framework adapter call render. Cycle detection tracks component instance identity, so nested same-type composition (for example Stack(Stack(...))) is valid while true self-recursion fails with HED-RENDER-0012.

Integrations that render more than one component during a request must create one RenderSession(context) and reuse it. The top-level render(...) function remains a one-shot convenience wrapper around a fresh session.

Passing context=None is equivalent to a default standalone context. Output is Unicode HTML; HTTP adapters alone perform the configured encoding. A result contains no raw secret, request, session, or dependency object. Header metadata is produced only by registered page/fragment policies and is revalidated by the framework adapter.

Stability boundary

Concrete internal text, element, fragment, and boundary node classes are private in 0.x. Applications compose public components and hedron.html primitives rather than constructing serializer nodes directly. The HTML serializer is not a public independent API; it consumes normalized nodes through the rendering engine.

Strings are text and are always escaped. Raw markup requires TrustedHtml and an explicit trusted-HTML primitive. Iterators with hidden I/O are not accepted as node sequences.

Errors

Situation Code / behavior What to do
Self-recursive component cycle HED-RENDER-0012 Break the cycle; nested same-type composition (Stack(Stack(...))) is fine
Raw HTML string without TrustedHtml Rejected Use TrustedHtml.reviewed / .nh3 + html.raw
Iterator / hidden I/O as children Rejected Pass concrete sequences of nodes
Missing production build manifest HED-BUILD-0003 Run hedron build before HEDRON_ENV=production — Troubleshooting

See Error codes.