CitryElement
class
Intermediate representation of a component invocation.
Created by Component(). Holds the component class and the
kwargs/slots that were passed. Rendering is deferred until
.render() is called.
Attributes
comp_cls
- The Component subclass to render.
kwargs
- The keyword arguments passed to the component.
slots
- The slot fills passed to the component. Filled from either
channel: the reserved slots= kwarg when composing from Python
(MyComp(title="x", slots={...})), or the collected <c-fill>
tags / implicit default body when composed by a parent template.
Values are raw inputs here (strings, functions, elements, Slots);
they normalize to Slot instances when the component instance is
created at render time.
component_tag_client_bindings
- The final source-ordered $c-props, Alpine event,
and Citry event contributions captured from a component tag. They
are framework metadata, not Python kwargs.
ownership_invocation_id
- The render-local component call record that
this element will bind to its concrete component instance.
ownership_graph
- The render-local graph that allocated
ownership_invocation_id. Retained explicitly so a lazy value
invoked during another root render cannot bind a graph-local ID
against the wrong graph.
element_morph_metadata
- Private metadata materialized only by the
dynamic ordinary-element built-in.
forward_ownership_invocation
- Whether this element is the transparent
dynamic selector and must forward the invocation to its selected
target instead of consuming it.
render
function
render(template_globals: Mapping[str, Any] | None = None, provides: Mapping[str, Any] | None = None) -> CitryRenderRender this component into a CitryRender.
Each call mints fresh per-instance state (render_id, etc.), so the same CitryElement can be rendered multiple times with distinct identities.
Parameters
template_globals
Mapping[str, Any] | None
- Template variables added for this render. They
reach the whole tree, sit above the Citry instance's globals,
and sit below each component's own template_data.
provides
Mapping[str, Any] | None
- Values the root component and its rendered descendants
may read with inject(). A nested direct render() call
starts a new root and must pass its required values again.
Returns
CitryRender: A ``CitryRender`` with the complete rendered tree. Call
CitryRender
class
The result of rendering a CitryElement (the render-phase output).
Attributes
parts
- Ordered list of str or nested CitryRender fragments.
context
- The CitryContext used to produce this render.
is_component_root
bool
- True for a nontransparent component's whole output.
Transparent whole outputs and interior renders (a <c-if>/<c-for> block, a
nested template, slot-fill content rendered in the enclosing
scope) are False. Serialization uses this to tell a completed
child-component subtree (which becomes its own marked frame) from
content that joins into the surrounding frame; the component on
the context cannot tell these apart, because slot-fill content
carries the context of the component that wrote it, not the one
it renders inside.
is_component_root
attribute
is_component_root: boolWhether this render is the whole output frame of one component.
serialize
function
serialize(deps_strategy: DepsStrategy = 'document', deps_position: DepsPosition = 'smart', csp_nonce: str | None = None, security_csp: SecurityCspMode | None = None, security_javascript: SecurityJavascriptMode | None = None, security_script_integrity: SecurityScriptIntegrityMode | None = None) -> strTurn this render into a final HTML string.
Each component's root element(s) get a data-cid-<id> marker so the
rendered HTML records which component produced which part of the page,
and the JS/CSS collected from the rendered components is placed into the
output per the chosen strategy and position.
Raises RuntimeError if any child component was left unrendered (a
DeferredComponent still in the parts), which can only happen if this
render did not come from render().
CSP warning mode reports incompatibilities without changing the standard-runtime output. Strict mode selects the CSP runtime and rejects incompatible reached-tree or final HTML. JavaScript warning mode inventories client requirements, omit removes Citry-managed executable output while retaining HTML and CSS, and forbid rejects a rendered subtree that requires client behavior.
Parameters
deps_strategy
DepsStrategy
- How to handle the collected JS/CSS.
"document" (default): emit the tags, plus the
client-side dependency manager and the page manifest when
a component needs per-instance browser behavior, including
js_data() scope seeding and $component callbacks."simple": the tags only, no JavaScript runtime. For
static pages and emails; per-instance JS does not run
(CSS variables still work, they are pure CSS)."fragment": HTML meant to be inserted into an
already-loaded page (an HTMX swap, fetch +
innerHTML, ...): nothing is inlined; the output ends
with a JSON manifest of URLs the client-side manager
fetches, each once per page however many fragments need
it. Requires a mounted web integration."ignore": no tags inserted.deps_position
DepsPosition
- Where the tags go (document/simple only).
"smart" (default): into the <c-js>/<c-css>
placeholders when present, else CSS before the first
</head> and JS before the last </body>, else
CSS is prepended and JS appended."prepend" / "append": all tags before/after the
whole output.csp_nonce
str | None
- Raw request nonce to add to structured scripts and
inline styles. The host owns nonce generation and the matching
Content-Security-Policy response header.
security_csp
SecurityCspMode | None
- Override this render's engine-level CSP policy.
security_javascript
SecurityJavascriptMode | None
- Override this render's engine-level
JavaScript delivery policy.
security_script_integrity
SecurityScriptIntegrityMode | None
- Override this render's engine-level
script integrity policy.
serialize_result
function
serialize_result(deps_strategy: DepsStrategy = 'document', deps_position: DepsPosition = 'smart', csp_nonce: str | None = None, security_csp: SecurityCspMode | None = None, security_javascript: SecurityJavascriptMode | None = None, security_script_integrity: SecurityScriptIntegrityMode | None = None) -> SerializedRenderReturn final HTML together with security metadata for those exact bytes.
Arguments and validation match :meth:serialize; this richer method
exposes the host-facing metadata while :meth:serialize returns only
result.html.
SerializedRender
class
Final HTML plus host-facing security metadata for those exact bytes.
SerializedSecurity
class
Security contributions produced by one serialization call.
csp_script_hashes is the deduplicated document-order tuple of quoted
hash sources that a host can add to script-src. It and scripts are
empty when digest-producing security features are disabled.
SerializedScriptSecurity
class
Security metadata for one structured script in serialized output.
digests uses the unquoted SRI form, such as "sha384-...".
provenance states whether Citry computed or verified those bytes.
origin_class_id identifies the component class when one owns the tag.
provenance
attribute
provenance: Literal['citry-computed', 'declared-verified', 'declared-unverified']CitryContext
class
Render-scoped state for a single component render.
Attributes
variables
- The per-component template variables (the template_data
output). Read by nodes when evaluating expressions. Values are
ordinary Python objects; the private mapping stores any Const
promise separately by variable name.
component
- The Component instance currently rendering. Gives a node
access to the component tree (its citry registry for resolving
child component names, and its parent/root linkage). The
current component is stored on the context, so each component render
gets its own CitryContext.
extra
- Tree-wide scratch space for extensions (for example the
collected JS/CSS dependency records). Top-level keys are
namespaced by owner; see the module docstring.
provides
- The provide/inject entries active at this point of the
render. Entries may hold a direct caller value, a frozen keyword-
field payload, or a private blocked marker. Read-only by convention;
Component.provide and Component.unprovide build a new
mapping rather than mutating this one.
CitryTemplate
class
A component's loaded template: the source string, its origin, and its compiled form (once first rendered).
Attributes
source
str
- The template string, after on_template_loaded hooks ran.
origin
str
- Where the template came from, for error messages and debugging.
The absolute file path for a file template, or
"<module file>::<ClassName>" for an inline one.
filepath
Path | None
- The resolved template file, or None when the template
was inlined on the class.
generate
Callable[[], list[BodyItem]] | None
- Internal. The compiled body-generating function; calling it
yields a fresh node list. None until the render pipeline
compiles the template on first render.
used_vars
frozenset[str]
- Internal. Every variable name the template uses, including
in nested tags (the parse-time Template.used_variables). Empty
until compiled. The Const optimization keys its cache only on
these.
declared_slots
tuple[DeclaredSlot, ...]
- Internal. The <c-slot> tags the template declares
(static names only), used to check the component against its
Slots schema. Empty until compiled.
render_compiled_body
function
render_compiled_body(body: CompiledBody, context: CitryContext, variables_overlay: Mapping[str, Any] | None = None) -> CitryRenderRender a protected compiled body with a live host-variable overlay.
collect_compiled_body_fills
function
collect_compiled_body_fills(body: CompiledBody, context: CitryContext, sink: FillSink, variables_overlay: Mapping[str, Any] | None = None) -> NoneCollect fills from a host-selected compiled body against a live overlay.
Placeholder
class
A spot in the output whose final text is supplied at serialize time.
Rendered output is normally text and nested renders, fixed once rendered.
A Placeholder marks a position whose content is only known when the whole
page is serialized: the <c-js> / <c-css> built-ins render one
each, and the dependencies extension fills them with the collected
script/style tags via the on_serialize hook.
Attributes
key
- What belongs at this spot (e.g. "deps:js"). The serializer
reports each occurrence to the on_serialize hook under this
key plus a counter and a private per-serialization identity. An
extension that knows the key supplies the text; an occurrence no
extension fills serializes to nothing. The private identity keeps
cleanup from matching an authored <template c-render-id> with
the same key and counter.
RenderFrame
class
Immutable identity needed to traverse and serialize one render frame.
is_transparent_root
attribute
is_transparent_root: boolTrue for a transparent component's whole output, excluding caller-owned interiors.
from_context
function
from_context(context: CitryContext, is_component_root: bool, is_transparent_root: bool = False) -> RenderFrameSnapshot the identity-bearing portion of one live render context.
const_value
function
Unwrap outer marker layers; leave plain values unchanged and reject marker cycles.
Markup
class
Bases: str
citry.Markup is exactly markupsafe.Markup, re-exported unchanged. Markup(value) trusts the complete value without sanitizing, validating, or escaping anything.
SecurityError
class
Bases: Exception
An expression attempted an operation blocked by the evaluator's sandbox.
The evaluator raises this at evaluation time when a checked variable, attribute, key, callable, or assignment is unsafe.