ComponentCatalog
class
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.
to_dict
function
to_json
function
Serialize this catalog to deterministic UTF-8 JSON text.
Parameters
indent
int | None
- Optional non-negative indentation width. None emits
compact JSON.
Returns
str: Deterministic JSON with recursively sorted object keys and Unicode
Raises
TypeError - If indent is not an integer or None.
ValueError - If indent is negative.
ComponentInfo
class
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 four primary asset declarations.
extensions
tuple[ComponentExtensionInfo, ...]
- Explicitly requested extension-owned metadata.
ComponentIntrospectionContext
class
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.
component_class
attribute
The temporary live component class from the copied registry snapshot.
info
attribute
info: ComponentInfoThe already-built core metadata record, with no extension entries.
ComponentIntrospectionError
class
Bases: RuntimeError
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.
ComponentSchemas
class
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.
SchemaInfo
class
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.
namespace_policy
Literal['closed', 'allow-extra', 'unknown']
- Whether declared fields exhaust the normalized
runtime mapping, explicitly permit extras, or leave that unknown.
namespace_policy
attribute
namespace_policy: Literal['closed', 'allow-extra', 'unknown']FieldInfo
class
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.
source_module
str | None
- Module that owns the authored field, when provable.
source_qualname
str | None
- Qualified class name that owns the field, when provable.
source_file
Path | None
- Absolute already-loaded module file for that class, when available.
default_value_state
attribute
default_value_state: Literal['not-applicable', 'omitted', 'available', 'unsupported']ComponentAssets
class
Group a component's primary template, messages, JavaScript, and CSS declarations.
Attributes
template
AssetInfo
- The primary template declaration.
messages
AssetInfo
- The source-locale Fluent declaration.
js
AssetInfo
- The primary JavaScript declaration.
css
AssetInfo
- The primary CSS declaration.
AssetInfo
class
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.
owner_module
str | None
- Module of the class that supplied the declaration.
owner_qualname
str | None
- Qualified name of that declaring class.
resolution
attribute
resolution: Literal['not-applicable', 'not-requested', 'resolved', 'missing', 'unavailable']ExtensionVersion
class
ComponentExtensionInfo
class
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.
NestedClassDeclaration
class
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.