Component libraries

Declare one ordered, engine-neutral collection of library components.

Construct the manifest after all class decorators have completed. A valid manifest seals its definitions against later class-attribute mutation.

Attributes

• name str - Stable lowercase package identity inside one Citry instance.
• components Sequence[type[LibraryComponent]] - Definitions in their deterministic registration order.
• required_extensions Sequence[str] - Exact extension names required before any class is materialized.

name: str

components: Sequence[type[LibraryComponent]]

required_extensions: Sequence[str]

Define a component once for materialization into multiple Citry instances.

A subclass has the same authored surface as Component: templates, methods, nested schemas, extension declarations, and assets all live on the class. Defining it has no registry side effects. Calling it returns a LibraryComponentInvocation that resolves through the Citry instance active at render time.

name: str | None

Remember one engine-neutral component call until rendering selects Citry.

Attributes

• definition type[LibraryComponent] - The exact inert definition object that was called.
• kwargs Mapping[str, Any] - A read-only copy of the component keyword arguments.
• slots Mapping[str, Any] - A read-only copy of the reserved slot-fill mapping.

definition: type[LibraryComponent]

kwargs: Mapping[str, Any]

slots: Mapping[str, Any]

identity: LibraryComponentIdentity

resolve(citry: Citry) -> CitryElement

render(citry: Citry | None = None, template_globals: Mapping[str, Any] | None = None) -> CitryRender

An immutable handle to one committed generation installed into Citry.

Retaining this handle does not make it active after Citry.clear(). Component access validates the exact active generation before returning a class.

Attributes

• library ComponentLibrary - The manifest used for this generation.
• engine_id str - The receiving Citry instance's stable runtime identity.

library: ComponentLibrary

engine_id: str

is_active: bool

classes: tuple[type[Component], ...]

definitions: tuple[type[LibraryComponent], ...]

component(definition: type[LibraryComponent]) -> type[Component]

A value that composes a component for the Citry instance rendering it.

Implement this structural protocol when a third-party object should work in template expressions or slot values without itself being a Component. Citry resolves the object once at the render site and verifies that the returned element belongs to the exact active instance.

Example

::

class NoticeValue:
    def __citry_element__(self, citry, /):
        Notice = citry.get("Notice")
        return Notice(message="Saved")

Report that a library invocation has no Citry instance to resolve through.

Report that a retained installation is not the Citry instance's active generation.

Report an incompatible manifest for an already installed library name.

Report that no active library installation can satisfy an invocation.