Extensions

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

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

Base class the per-component nested config inherits from.

CLI commands this extension provides (see :class:ExtensionCommand).

Positive schema version when this extension publishes component metadata.

Whether settled render state from this extension can be replayed.

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 (see citry/util/routing.py).

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 CacheExtension(Extension):
    name = "cache"

    def validate_config_fields(self, fields, *, component=None):
        for name in fields:
            if name != "ttl":
                msg = f"unknown config field {name!r}; the only field is 'ttl'"
                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 :attr: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``.

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 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 a new CitryRender / str to replace the output, raise to replace the error, or return None to keep the original.

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

Return a new render part (str or CitryRender) to replace the output, or None to keep the original. Raising propagates.

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).

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.

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

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.

Called once per class with the template string before it is parsed. Return a new string to modify it.

Called once per compiled body, with the generated node list. Mutate it in place or return a new list.

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

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

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

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

The owning Component instance.

Raises RuntimeError if this config runs outside a component lifecycle (no component), or if 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 defines name by overriding it (see _extensions_with_hook). name need not be a hook declared on :class:Extension, so an extension can fire its own custom hook for others to implement.

manager.emit("on_component_data", ctx)

manager.emit("on_template_loaded", ctx, result="map", field="content")

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

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

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

Whether any installed extension implements the hook name.

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.

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

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).

Deliberately not declared on the :class:Extension base: this is the first consumer of the duck-typed custom-hook dispatch (an extension subscribes by defining a method named on_files_reset).

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

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

Positional arguments and options, declared with :class:~citry.command.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 (mirrors :attr:Extension.citry). A command's handle reads it to reach the component registry and the installed extensions.

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

The add_argument keywords for this argument, minus name_or_flags.

name_or_flags is passed positionally by :func:build_parser, 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.

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 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`](/reference/extensions/#citry-extension-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). Consumed by the built-in dependencies extension.

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 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 carries everything that bubbled up during the render).

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).

The Citry instance the component class belongs to.

The Component class whose template was compiled.

The generated body node list.

The Citry instance the component class belongs to.

The Component class whose template was loaded.

The template string (before parsing).

The Citry instance the component class belongs to.

The Component class whose loaded template was reset.