Extensions

Name of the extension. Lowercase, a valid Python identifier. Determines the attribute the per-component config is reachable under (component.<name>) and, through class_name, the nested class name.

PascalCase name of the per-component nested config class, derived from name at subclass creation (my_extension -> MyExtension).

Base class the per-component nested config inherits from.

CLI commands this extension provides (see ExtensionCommand).

Positive schema version when this extension publishes component metadata.

Whether settled render state from this extension can be replayed.

Experimental

The "payload" mode, where an extension saves its own data with a cached render and restores it on a cache hit, is experimental. It may change in a minor release without a deprecation period. "deny" and "stateless" are stable.

Positive compatibility version for stateless or payload replay.

The Citry instance this extension instance belongs to. Set by the manager when the extension is attached (extensions are per-instance, so the back-reference is unambiguous).

HTTP routes this extension provides, as URLRoute values.

Mounted by the web-integration adapters as part of Citry.urls: a user extension's routes live under ext/<extension name>/; built-in extensions own their paths directly. Override as an attribute or property; handlers can reach engine state through self.citry.

Check the config fields declared for this extension, at declaration time.

Users configure an extension in two places: a component's nested config class (class View: for an extension named "view"), and the engine-wide extensions_defaults setting. Citry calls this method once per declaration:

• At engine construction, with the extension's entry in the extensions_defaults setting (component is None).
• At component class definition, with the fields declared on the component's nested config class, including fields from its user-written base classes (component is the component class).

The base implementation accepts everything: by default an extension's config may hold any fields, even methods. Override it to reject bad fields early, so a typo in a field name fails at startup or at class definition instead of surfacing later as a confusing downstream error. Because both declaration sites are checked, the fields are known-valid by the time the config class is instantiated.

Example

An extension whose config accepts exactly one field:

from citry import Extension

class TimeoutExtension(Extension):
    name = "timeout"

    def validate_config_fields(
        self, fields, *, component=None
    ):
        for name in fields:
            if name != "seconds":
                msg = (
                    f"unknown field {name!r}; "
                    "the only field is 'seconds'"
                )
                raise ValueError(msg)

Parameters

• fields Mapping[str, Any] - The declared fields, mapping field name to declared value. For a nested config class, dunder names, the Config base's members, and citry's own bookkeeping attributes are already filtered out.
• component type[Component] | None - The component class the fields were declared on, or None when the fields come from the extensions_defaults setting.

Raises

• ValueError - When a field is not valid for this extension. Raise it with a message naming the offending field and what is valid; citry prefixes the declaration site (the component and its nested class, or the setting).

Publish this extension's allowlisted metadata for one component.

Citry calls this direct query method only when a caller explicitly requests the extension by name. Override it together with a positive introspection_version. Return an exact built-in dict made only from strict JSON values, or None when this component has no entry. The method must be observational, deterministic, reentrant, and thread-safe; it must not render, load assets, mutate registration, or depend on request state.

Parameters

• ctx ComponentIntrospectionContext - The owning engine, temporary live component class, and its already-built core metadata record. ctx.info.extensions is always empty.

Returns

dict[str, object] | None: An extension-owned JSON object, or ``None``.

Describe template variables supplied by this extension.

Citry calls this observational hook while it captures tooling analysis. Return detached annotations only. Do not render, mutate the component, or depend on request state. The contribution can add known names or report that the extension preserves unenumerated extras, but it cannot change lint severity.

Parameters

• ctx TemplateNamespaceContext - The owning engine and temporary component class.

Returns

TemplateNamespaceContribution | None: Portable namespace metadata, or ``None`` for no contribution.

Called once when this extension instance is created.

Called after a Component class is defined, before it is registered.

Called after a Component class is registered.

Called after a Component class is unregistered.

Called during Citry.clear() after its registry is empty.

Citry calls this hook in the middle of Citry.clear(). Rendering from it raises RuntimeError. Do not make it wait for another thread that renders: that thread can wait for the clear to finish, so both can hang.

Called when a component starts rendering, before template_data.

Inspect or mutate ctx.kwargs / ctx.slots in place. These are the authoritative raw mappings. Citry normalizes Slots and constructs the component's final typed kwargs and slots once all input hooks finish.

Called after template_data; mutate ctx.template_data to add or change template variables.

Called after a component (and its children) rendered. Return new content to replace the output, raise to replace the error, or return None to keep the original.

The content follows the rule of a {{ ... }} value, on static and interactive pages alike: a CitryRender replaces the output, a plain str is shown as text (Citry escapes it), and Markup is inserted as HTML. Never pass user input to the Markup() constructor.

HTML you serialize inside the hook, such as str(ctx.render), is a plain str, so wrap it in Markup before you return it. It does not carry the component's own data-cid-* attribute; Citry adds it to the HTML you return.

Raises

• TypeError - Citry raises it when the hook returns a value of any other type. It is raised as soon as the hook returns, before any later extension runs, and the message names the extension and the component.

Called after a <c-slot> site rendered (a fill, or the fallback).

Return new content to replace the output, or None to keep the original. Raising propagates. As with on_component_rendered, a CitryRender replaces the output, a plain str is shown as text (Citry escapes it), and Markup is inserted as HTML, on static and interactive pages alike.

Raises

• TypeError - Citry raises it when the hook returns a value of any other type, such as a bare Placeholder or component. It is raised before any later extension runs, and the message names the extension and the slot. Return None or the unchanged ctx.result to keep the output.

Called after an HTML element's dynamic attributes resolved to their final dict, before it is formatted into the output. Return a new dict to replace the attributes, or None to keep them.

Fires per element per render, only for elements with at least one dynamic attribute (a c-* value or a c-bind spread).

Raises

• TypeError - Citry raises it when the hook returns a value that is not a mapping, such as a dict, or None, before any later extension runs. The message names the extension.
• VueCodeError - Citry raises VueCodeError when the hook adds an attribute name that Vue would read as code (one starting with v-, :, ., ^, @, or #), or changes the value of such an attribute written in the template. Removing one, or keeping it unchanged, is allowed.

Called when a nested render's output is consumed by an enclosing render (a child component settling into its parent, or an already-rendered value embedded via an expression or slot).

Merge your extension's slice of ctx.child_context.extra into ctx.parent_context.extra, with your own policy (the dependencies extension, for example, appends records preserving order). The core does not merge anything itself.

Export this payload extension's selected strict-JSON contribution.

Experimental

Part of the experimental "payload" render cache mode, where an extension saves its own data with a cached render and restores it on a cache hit. It may change in a minor release without a deprecation period.

Validate a detached payload and return a mutation-free replay contribution.

Experimental

Part of the experimental "payload" render cache mode, where an extension saves its own data with a cached render and restores it on a cache hit. It may change in a minor release without a deprecation period.

Return a stable reason when this extension requires live rendering.

Called at the end of CitryRender.serialize() with the joined HTML.

Return a new string to replace the output (threaded across extensions), or None to keep it. This is where serialize-time work that needs the whole page happens; the dependencies extension places the collected JS/CSS here, using ctx.placeholders for the <c-js>/<c-css> positions.

Raises

• TypeError - Citry raises it when the hook returns a value that is not a str or None, before any later extension runs. The message names the extension.

Describe the fixed Vue plugin installed before an interactive app mounts.

Experimental

This method and the types it takes and returns are experimental. They may change in a minor release without a deprecation period.

Project this extension's selected render records into prepared browser data.

Experimental

This method and the types it takes and returns are experimental. They may change in a minor release without a deprecation period.

Called with a class's template string before it is parsed. Return a new string to modify it.

Citry usually calls this hook once per class, the first time a render needs the template. It can call it again for the same class: once per thread when several threads load the class for the first time at once, and up to three times on each thread when a component on the same Citry instance is reset (by reset_template(), reset_files(), or a hot reload) while the hook runs. Every render gets the same result, so return the same text for the same input, and make any side effect replace what an earlier call did instead of adding to it. The hook runs with no Citry lock held, so it may render other components.

Raises

• TypeError - Citry raises it when the hook returns a value that is not a str or None, before any later extension runs. The message names the extension and the component.

Declare UTF-8 source ranges owned by this extension's host engine.

Citry runs this hook with no Citry lock held. When several threads render a template for the first time at once, each may call it, and every render gets the same result, so return the same ranges for the same source.

Experimental

Part of the experimental API for embedding Citry tags in another template engine. It may change in a minor release without a deprecation period.

Called with a source declaration's source-locale Fluent text before compilation. A parent and children that inherit the same messages share its result.

Return a new string to replace the source. User extensions run in installation order. The built-in i18n extension always runs after those transformations, so it compiles the same final string the asset loader caches.

Citry usually calls this hook once per declaration, the first time a render needs the messages. It can call it again for the same declaration: once per thread when several threads load the messages for the first time at once, and up to three times on each thread when a component on the same Citry instance is reset (by reset_template(), reset_files(), or a hot reload) while the hook runs. Every render gets the same result, so return the same text for the same input, and make any side effect replace what an earlier call did instead of adding to it. The hook runs with no Citry lock held, so it may render other components.

Raises

• TypeError - Citry raises it when the hook returns a value that is not a str or None, before any later extension runs. The message names the extension and the component.

Called with the node list Citry builds from a component's template, before Citry keeps it for later renders. Citry builds one per template and set of Const values. Mutate the list in place or return a new list.

Citry usually calls this hook once per list. It can call it again for the same list: once per thread when several threads render the template for the first time at once, and up to three times on each thread when a component on the same Citry instance is reset or unregistered, or the instance is cleared, while Citry builds the list. Every render gets the same result, so return the same nodes for the same input, and make any side effect replace what an earlier call did instead of adding to it. The hook runs with no Citry lock held, so it may render other components.

Raises

• TypeError - Citry raises it when the hook returns a value that is not a sequence, such as a list, or None, before any later extension runs. A str is not accepted. The message names the extension and the component.

Replace this provider's claims in one independent body list.

The provider must call ctx.mark_resolved exactly once for every claim it handles. Core verifies the ledger before general compiled hooks run.

Like on_template_compiled, this hook runs with no Citry lock held and can run more than once for the same node list; every render gets the same result.

Experimental

Part of the experimental API for embedding Citry tags in another template engine. It may change in a minor release without a deprecation period.

Raises

• TypeError - Citry raises it when the hook returns a value that is not a sequence, such as a list, or None, before any later extension runs. A str is not accepted. The message names the extension and the component.

Called after a component class's loaded template is reset.

Citry calls this hook in the middle of the reset. The hook may render components on the same thread. Do not make it wait for another thread that renders, such as by joining a thread or a future: that thread waits for the reset to finish, so both can hang.

Called with the component's primary JS content (inline or read from js_file). Return a new string to modify it.

Citry usually calls this hook once per class, the first time a render needs the JavaScript. It can call it again for the same class: once per thread when several threads load the class for the first time at once, and up to three times on each thread when a component on the same Citry instance is reset (by reset_template(), reset_files(), or a hot reload) while the hook runs. Every render gets the same result, so return the same text for the same input, and make any side effect replace what an earlier call did instead of adding to it. The hook runs with no Citry lock held, so it may render other components.

Raises

• TypeError - Citry raises it when the hook returns a value that is not a str or None, before any later extension runs. The message names the extension and the component.

Called with the component's primary CSS content (inline or read from css_file). Return a new string to modify it.

Citry usually calls this hook once per class, the first time a render needs the CSS. It can call it again for the same class: once per thread when several threads load the class for the first time at once, and up to three times on each thread when a component on the same Citry instance is reset (by reset_template(), reset_files(), or a hot reload) while the hook runs. Every render gets the same result, so return the same text for the same input, and make any side effect replace what an earlier call did instead of adding to it. The hook runs with no Citry lock held, so it may render other components.

Raises

• TypeError - Citry raises it when the hook returns a value that is not a str or None, before any later extension runs. The message names the extension and the component.

The Component class this config is defined on (bound by the manager).

The owning Component instance.

Raises

• RuntimeError - If this config was created without a component, or the component has been garbage-collected.

Every extension's CLI commands, keyed by extension name (read as Citry.commands).

Built-in extensions come first (they are prepended at construction), then the user's extensions in spec order; only extensions that declare commands appear. Extension names are unique (enforced at construction), so the keys never collide. The CLI reaches a command as citry ext run <extension name> <command name>.

The combined route table of every extension (read as Citry.urls).

Built-in extensions own their paths directly (e.g. the dependencies extension's cache/... and citry.js); a user extension's routes are namespaced under ext/<extension name>/ so they cannot collide with citry's own or each other's.

Dispatch hook name to the extensions that define it, combining the hooks' returned values per result:

• "none": call every extension, ignore returns; return None.
• "first": return the first non-None return (short-circuit).
• "map": thread ctx.<field> - each non-None return replaces it (via dataclasses.replace) and is passed to the next extension; the final field value is returned.

An extension takes part by defining a method called name. name need not be a hook declared on Extension, so an extension can fire its own custom hook for others to implement.

manager.emit("on_render_context_merge", ctx)

manager.emit(
    "on_my_value",
    ctx,
    result="map",
    field="value",
)

manager.emit("on_my_event", ctx, result="first")

Run the on_extension_created hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_extension_created() on your extension instead.

Run the on_component_class_created hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_component_class_created() on your extension instead.

Run the on_component_registered hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_component_registered() on your extension instead.

Run the on_component_unregistered hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_component_unregistered() on your extension instead.

Run the on_citry_cleared hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_citry_cleared() on your extension instead.

Run the on_component_input hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_component_input() on your extension instead.

Run the on_component_data hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_component_data() on your extension instead.

Run the on_render_context_merge hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_render_context_merge() on your extension instead.

Run the on_serialize hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_serialize() on your extension instead.

Thread the rendered output through the extensions; a return replaces the render, a raise replaces the error.

With context (the component's render context), a returned str or Markup becomes a render in that context before the next extension sees it, so a plain str stays text along the chain.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_component_rendered() on your extension instead.

Thread a slot's rendered output through the extensions; a return replaces the result, a raise propagates.

With context (the context of the <c-slot> site), a returned str or Markup becomes a render in that context before the next extension sees it, so a plain str stays text along the chain.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_slot_rendered() on your extension instead.

Whether any installed extension implements the hook name.

Whether this element has an applicable resolved-attributes hook.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release.

Thread an element's resolved attribute dict through the extensions; a return replaces the dict, a raise propagates.

This sits on a per-element per-render hot path, so when no extension implements the hook the dict is returned without building a context.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_attrs_resolved() on your extension instead.

Run the on_template_loaded hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_template_loaded() on your extension instead.

Collect provider spans against one final post-load source string.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_template_foreign_spans() on your extension instead.

Resolve every provider claim, one independently compiled body at a time.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_template_foreign_compiled() on your extension instead.

Run the on_messages_loaded hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_messages_loaded() on your extension instead.

Run the on_template_compiled hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_template_compiled() on your extension instead.

Notify extensions after a component class's template is reset.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_template_reset() on your extension instead.

Run the on_js_loaded hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_js_loaded() on your extension instead.

Run the on_css_loaded hook on every extension that implements it.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. To react to this hook, implement Extension.on_css_loaded() on your extension instead.

Notify extensions that a component class's loaded asset files were reset, so each drops its own per-class state (the dependencies built-in drops its merged result here).

This hook is not declared on the Extension base. An extension receives it by defining a method named on_files_reset. Citry calls it in the middle of the reset. The method may render components on the same thread. Do not make it wait for another thread that renders: that thread waits for the reset to finish, so both can hang.

Internal: Citry calls this method itself. It is not covered by Citry's API stability promise and may change in any release. The on_files_reset method an extension defines is public.

The command name (citry ext run <extension> <name>).

One-line description of the command, shown in --help output.

Positional arguments and options, declared with CommandArg.

Nested commands. A command with subcommands usually has no handle of its own.

Optional customization of how this command appears when nested under a parent.

Runs the command, called with the parsed options as keyword arguments. None (the default) marks a command that only groups subcommands; a real command overrides this with def handle(self, **kwargs).

The engine the command runs against, bound by the runner before handle is called (like Extension.citry). A command's handle reads it to reach the component registry and the installed extensions.

Require live rendering while debug highlighting is enabled.

A positional name ("path") or a list of option flags (["--shout", "-s"]).

The add_argument keywords for this argument, minus name_or_flags.

Citry passes name_or_flags to add_argument positionally, so it is not included here; unset (None) fields are dropped.

The add_parser keywords for this subcommand entry (unset fields dropped).

The Citry instance the component belongs to.

The component whose template holds the element. For <c-element>, this is the lexical owner, not the transparent built-in renderer.

The HTML tag the attributes belong to (e.g. "div").

The resolved attribute dict: class/style already normalized to strings, booleans still True, omitted attributes already absent.

The Citry instance whose registry and engine caches were cleared.

The Citry instance the component class belongs to.

The created Component class.

Return the exact authored bindings for name in component C3 order.

A record whose value is None is an explicit reset, distinct from the name being absent. The classes are the original source objects, even after Citry replaces the component attribute with an effective runtime config class.

Parameters

• name str - The nested declaration name, usually the extension's class_name.

Returns

tuple[NestedClassDeclaration, ...]: The declarations from the component through its bases in C3 order.

The Citry instance the component belongs to.

The Component instance being rendered.

The render-scoped CitryContext for this component's render. Extensions stash tree-wide state in context.extra (for example the dependencies extension's render records); it bubbles up through on_render_context_merge as nested renders are consumed. context.provides is not yet populated when this hook fires.

The template variables from Component.template_data() (mutable).

The JS variables from Component.js_data() (mutable). Citry sends them to the browser as fields on the component's Vue instance, and checks the keys after this hook runs.

The CSS variables from Component.css_data() (mutable). Consumed by the built-in dependencies extension.

The Citry instance the component belongs to.

The Component instance being rendered.

The keyword arguments passed to the component (mutable plain dict).

The slot fills passed to the component (mutable plain dict).

The Citry instance the component was registered with.

The name the component was registered under.

The registered Component class.

The Citry instance the component belongs to.

The Component instance that was rendered.

The rendered output, or None if rendering failed.

The error raised during rendering, or None if it succeeded.

The Citry instance the component was unregistered from.

The name the component was registered under.

The unregistered Component class.

The Citry instance the component class belongs to.

The Component class whose CSS was loaded.

The CSS content (inline or read from css_file).

The Citry instance the extension belongs to.

The created extension instance.

The Citry instance the component class belongs to.

The Component class whose loaded asset files were reset.

The Citry instance the component class belongs to.

The Component class whose JS was loaded.

The JS content (inline or read from js_file).

The Citry instance the component class belongs to.

The Component class whose source messages were loaded.

The class that authored the inherited messages/messages_file pair.

The source-locale Fluent text before compilation.

A file path or inline module::Class.messages label for diagnostics.

The Citry instance the render belongs to.

The context of the render that consumed the nested one.

The context of the consumed nested render.

The Citry instance the render belongs to.

The root render's CitryContext. Its extra holds everything that bubbled up during the render. One render can be serialized several times, and every serialize() call sees the same extra: a value your on_serialize hook stores there is still there the next time the hook runs, so set or delete it on every run rather than adding it only when it is missing.

The final hook-selected render tree being serialized.

The joined HTML (threaded: return a new string to replace it).

The placeholder parts found during serialization: unique placeholder id (the Placeholder.key plus a counter and a private serialization identity) to the exact text standing in for it in html. Match the key prefix rather than relying on the private suffix.

The serialize(deps_strategy=...) argument.

The serialize(deps_position=...) argument.

The Citry instance the component belongs to.

The component whose template holds the <c-slot> that was rendered.

The Slot that was rendered: the fill, or the fallback when no fill was given.

The resolved slot name ("default" for an unnamed slot).

The runtime SlotNode at whose site the slot rendered.

Whether the slot resolved as required.

The rendered output (a str or a CitryRender).

Name of the extension allowed to receive this context.

Deterministic identity for compile-time host state.

The Citry instance the component class belongs to.

The Component class whose template was compiled.

The generated body node list.

Immutable identity of the exact template record being compiled.

Authored source origin used for diagnostics.

Record explicit outcomes for claims replaced by the provider.

Compile and protect one Citry run for later host-selected rendering.

The Citry instance the component class belongs to.

The Component class whose template was loaded.

The template string (before parsing).

Immutable identity of this loaded template record.

Source origin used for diagnostics.

The Citry instance the component class belongs to.

The Component class whose loaded template was reset.

The owning Citry instance.

The temporary live component class from the registry snapshot.