--- title: Component libraries url: https://citry.dev/reference/component-libraries/ description: "Engine-neutral component definitions, explicit manifests, and per-Citry installations." --- # Component libraries Engine-neutral component definitions, explicit manifests, and per-Citry installations.
View source

ComponentLibrary class

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

View source

name attribute 

name: str
View source

components attribute 

components: Sequence[type[LibraryComponent]]
View source

required_extensions attribute 

required_extensions: Sequence[str]
View source

LibraryComponent class

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.

View source

pure attribute 

pure: bool
View source

simple attribute 

simple: bool

Render without an independent instance; see Component.simple.

View source

name attribute 

name: str | None

Optional explicit registry name, with the same behavior as Component.name.

View source

LibraryComponentInvocation class

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

Attributes

View source

definition attribute 

definition: type[LibraryComponent]
View source

kwargs attribute 

kwargs: Mapping[str, Any]
View source

slots attribute 

slots: Mapping[str, Any]
View source

identity attribute 

identity: LibraryComponentIdentity

Return the definition's logical source identity for diagnostics.

View source

resolve function 

resolve(citry: Citry) -> CitryElement

Resolve this invocation to a concrete component element.

Parameters

  • citry Citry - The Citry instance whose installed concrete class should be used.

Returns

CitryElement: A normal [`CitryElement`](/reference/rendering/#citry-citryelement) associated with the

Raises

  • TypeError - If citry is not a Citry instance.
  • LibraryNotInstalled - If no active installation contains this exact definition generation.
View source

render function 

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

Render this invocation through an explicit Citry instance.

Parameters

  • citry Citry | None - The instance with the component's library installed.
  • template_globals Mapping[str, Any] | None - Values added to this render's template globals.
  • provides Mapping[str, Any] | None - Values the root and its rendered descendants may read with inject().

Returns

CitryRender: The resulting deferred render tree.

Raises

  • LibraryComponentContextError - If citry is omitted. Contextual resolution is supplied automatically only when the invocation appears inside another component tree.
View source

LibraryInstallation class

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

View source

library attribute 

library: ComponentLibrary
View source

engine_id attribute 

engine_id: str
View source

is_active attribute 

is_active: bool

Return whether this is still the Citry instance's exact active record.

View source

classes attribute 

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

Return concrete component classes in manifest order if this record is active.

View source

definitions attribute 

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

Return the engine-neutral definitions in manifest order.

View source

component function 

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

Return the installed concrete class for an exact definition generation.

Parameters

Returns

type[Component]: The concrete Component class associated with this installation.

Raises

  • LibraryInstallationStale - If the Citry instance was cleared or a newer installation generation is active.
  • KeyError - If the definition is outside this library.
View source

ComponentLike class

Bases: Protocol

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")
View source

LibraryComponentContextError class

Bases: RuntimeError

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

View source

LibraryInstallationStale class

Bases: RuntimeError

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

View source

LibraryManifestChanged class

Bases: RuntimeError

Report an incompatible manifest for an already installed library name.

View source

LibraryNotInstalled class

Bases: RuntimeError

Report that no active library installation can satisfy an invocation.