Component introspection

Hold one immutable, versioned snapshot of registered component metadata.

Attributes

• schema_version int - The core component-catalog schema version.
• citry_version str - Installed Citry package version used for the snapshot.
• engine_id str - Runtime identity of the inspected Citry instance.
• extension_versions tuple[ExtensionVersion, ...] - Requested extension metadata versions, sorted by name.
• components tuple[ComponentInfo, ...] - Component records in canonical catalog order.

schema_version: int

citry_version: str

engine_id: str

extension_versions: tuple[ExtensionVersion, ...]

components: tuple[ComponentInfo, ...]

to_dict() -> dict[str, object]

to_json(indent: int | None = None) -> str

Describe one exact registered component class generation.

Attributes

• class_id str - Stable import-derived component route identity.
• engine_id str - Runtime identity of the owning Citry instance.
• definition_id str - Runtime identity of this exact class generation.
• name str - Deterministically selected primary registration name.
• aliases tuple[str, ...] - Other registration names for the same class.
• class_name str | None - Python class name, when available.
• module str | None - Python module name, when available.
• qualname str | None - Python qualified class name, when available.
• import_path str | None - Full Python import path, when available.
• python_file Path | None - Absolute already-loaded module file, when available.
• description str | None - The component class's own cleaned docstring.
• transparent bool - Whether the component joins its parent's serialization frame.
• builtin bool - Whether Citry created this as a framework component.
• schemas ComponentSchemas - The component's five effective typed schemas.
• assets ComponentAssets - The component's three primary asset declarations.
• extensions tuple[ComponentExtensionInfo, ...] - Explicitly requested extension-owned metadata.

class_id: str

engine_id: str

definition_id: str

name: str

aliases: tuple[str, ...]

class_name: str | None

module: str | None

qualname: str | None

import_path: str | None

python_file: Path | None

description: str | None

transparent: bool

builtin: bool

schemas: ComponentSchemas

assets: ComponentAssets

extensions: tuple[ComponentExtensionInfo, ...]

Give one extension the inputs for an explicitly requested metadata query.

The component class is temporary live runtime state. Inspectors publish copied JSON metadata and must not retain this context or the class.

Attributes

• citry Citry - The owning Citry instance.
• component_class type[Component] - The live class from the query's copied registry snapshot.
• info ComponentInfo - The complete core metadata record, with no extension entries.

citry: Citry

component_class: type[Component]

info: ComponentInfo

Report that a requested extension could not publish component metadata.

Attributes

• extension_name - The installed or requested extension name.
• component_name - The component's primary registered name, when the failure happened while inspecting one component.

Group the five typed schema roles exposed by a component.

Attributes

• kwargs SchemaInfo - Inputs accepted as component keyword arguments.
• slots SchemaInfo - Slot fills accepted by the component.
• template_data SchemaInfo - Values returned for template rendering.
• js_data SchemaInfo - Values made available to component JavaScript.
• css_data SchemaInfo - Values made available to component CSS.

kwargs: SchemaInfo

slots: SchemaInfo

template_data: SchemaInfo

js_data: SchemaInfo

css_data: SchemaInfo

Describe one effective component schema binding.

Attributes

• kind Literal['absent', 'fields', 'opaque'] - Whether the schema is absent, recognized as fields, or opaque.
• declared_on str | None - Import path of the MRO class that supplied the binding.
• import_path str | None - Import path of the effective schema class.
• fields tuple[FieldInfo, ...] - Recognized fields in runtime declaration order.

kind: Literal['absent', 'fields', 'opaque']

declared_on: str | None

import_path: str | None

fields: tuple[FieldInfo, ...]

Describe one field in a recognized component schema.

Attributes

• name str - The schema adapter's canonical field name.
• required bool - Whether callers must provide the field.
• type_display str | None - A safe normalized type string, when available.
• type_fidelity Literal['normalized', 'unavailable'] - Whether ``type_display`` contains a normalized type.
• default_kind Literal['missing', 'value', 'factory'] - Whether the field has no default, a value, or a factory.
• default_value_state Literal['not-applicable', 'omitted', 'available', 'unsupported'] - Whether a real default value was requested and copied.
• default_value FrozenJsonValue | None - A recursively frozen portable default, when available.
• description str | None - Runtime field documentation from a supported schema source.

name: str

required: bool

type_display: str | None

type_fidelity: Literal['normalized', 'unavailable']

default_kind: Literal['missing', 'value', 'factory']

default_value_state: Literal['not-applicable', 'omitted', 'available', 'unsupported']

default_value: FrozenJsonValue | None

description: str | None

Group a component's primary template, JavaScript, and CSS declarations.

Attributes

• template AssetInfo - The primary template declaration.
• js AssetInfo - The primary JavaScript declaration.
• css AssetInfo - The primary CSS declaration.

template: AssetInfo

js: AssetInfo

css: AssetInfo

Describe one primary template, JavaScript, or CSS declaration.

Attributes

• kind Literal['none', 'inline', 'file'] - Whether the asset is absent, inline, or file-backed.
• declared_on str | None - Import path of the class that supplied the declaration.
• owner_file Path | None - Absolute Python file containing the declaring class.
• declared_path str | None - The file path exactly as declared by the component.
• resolution Literal['not-applicable', 'not-requested', 'resolved', 'missing', 'unavailable'] - Whether path resolution was requested and what it found.
• resolved_path Path | None - Absolute existing asset path when resolution succeeded.
• searched_paths tuple[Path, ...] - Absolute candidate paths checked during resolution.

kind: Literal['none', 'inline', 'file']

declared_on: str | None

owner_file: Path | None

declared_path: str | None

resolution: Literal['not-applicable', 'not-requested', 'resolved', 'missing', 'unavailable']

resolved_path: Path | None

searched_paths: tuple[Path, ...]

Record one requested extension's introspection schema version.

Attributes

• name str - The extension's unique registered name.
• introspection_version int - The extension-owned positive schema version.

name: str

introspection_version: int

Store one extension's explicitly published component metadata.

Attributes

• name str - The extension's unique registered name.
• introspection_version int - The extension-owned positive schema version.
• data FrozenJsonObject - A defensively copied and recursively frozen JSON object.

name: str

introspection_version: int

data: FrozenJsonObject

One nested class binding written on a component or definition base.

Attributes

• declaring_class type - The class whose body contains the binding.
• name str - The nested declaration name, such as ``"Events"``.
• value object - The exact authored value. Supported declarations use a class, while ``None`` explicitly resets inherited declarations.

declaring_class: type

name: str

value: object