Component graph

Hold a versioned snapshot of authored dependencies between registered components.

Build a graph with Citry.inspect_component_graph(). Query direct dependencies or reverse references by primary name, alias, or a node returned from the same graph.

Example

graph = app.inspect_component_graph()

for dependency in graph.dependencies("page"):
    print(dependency.name)

for dependent in graph.dependents("button"):
    print(dependent.name)

Attributes

• schema_version int - Graph JSON schema version.
• citry_version str - Installed Citry package version used to build the graph.
• engine_id str - Runtime identity of the inspected Citry instance.
• nodes tuple[ComponentGraphNode, ...] - Registered component definitions in canonical order.
• references tuple[ComponentGraphReference, ...] - Resolved authored occurrences in canonical source order.
• unresolved tuple[UnresolvedComponentReference, ...] - Unknown and dynamic authored occurrences.
• problems tuple[ComponentGraphProblem, ...] - Sources that could not be inspected completely.

schema_version: int

citry_version: str

engine_id: str

nodes: tuple[ComponentGraphNode, ...]

references: tuple[ComponentGraphReference, ...]

unresolved: tuple[UnresolvedComponentReference, ...]

problems: tuple[ComponentGraphProblem, ...]

coverage_complete: bool

fully_resolved: bool

component(selector: str | ComponentGraphNode) -> ComponentGraphNode

dependencies(component: str | ComponentGraphNode) -> tuple[ComponentGraphNode, ...]

dependents(component: str | ComponentGraphNode) -> tuple[ComponentGraphNode, ...]

references_from(component: str | ComponentGraphNode) -> tuple[ComponentGraphReference, ...]

references_to(component: str | ComponentGraphNode) -> tuple[ComponentGraphReference, ...]

unresolved_from(component: str | ComponentGraphNode | None = None) -> tuple[UnresolvedComponentReference, ...]

to_dict() -> dict[str, object]

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

Identify one registered component definition in an authored dependency graph.

Use name in templates and graph queries. aliases contains the other registered spellings that resolve to the same component.

Example

graph = app.inspect_component_graph()
card = graph.component("card")
print(card.name)

Attributes

• class_id str - Stable identity for the component's Python route.
• engine_id str - Runtime identity of the Citry instance that built the graph.
• definition_id str - Runtime identity of this exact class generation.
• name str - Canonical registered component name.
• aliases tuple[str, ...] - Other registered names for the same component.
• builtin bool - Whether Citry created this framework component.

class_id: str

engine_id: str

definition_id: str

name: str

aliases: tuple[str, ...]

builtin: bool

Describe one authored component reference that resolves to a registered target.

Repeated invocations remain separate records. Use ComponentGraph.dependencies when you need unique target components.

Attributes

• source_definition_id str - Exact component definition that owns the source.
• target_definition_id str - Exact registered target definition.
• registered_name str - Normalized registry name that matched the reference.
• authored_name str - Target name exactly as written by the author.
• syntax Literal['tag', 'static-selector'] - Whether the target came from a tag or static selector.
• location ComponentGraphLocation - Authored source occurrence.

source_definition_id: str

target_definition_id: str

registered_name: str

authored_name: str

syntax: Literal['tag', 'static-selector']

location: ComponentGraphLocation

Describe an authored component reference whose target is not statically known.

unknown-component retains the written name. dynamic-target uses authored_name=None because the runtime expression or spread chooses it.

Attributes

• source_definition_id str - Exact component definition that owns the source.
• authored_name str | None - Written target name, or None for a dynamic target.
• reason Literal['unknown-component', 'dynamic-target'] - Whether the name is unknown or the target is dynamic.
• syntax Literal['tag', 'static-selector', 'dynamic-selector'] - Authored tag or selector form.
• location ComponentGraphLocation - Authored source occurrence.

source_definition_id: str

authored_name: str | None

reason: Literal['unknown-component', 'dynamic-target']

syntax: Literal['tag', 'static-selector', 'dynamic-selector']

location: ComponentGraphLocation

Point to one component reference in an authored primary template.

start_index and end_index are half-open UTF-8 byte offsets in the normalized root template. source_range carries the same span as zero-based UTF-16 positions for editors.

Attributes

• origin str - Human-readable template origin.
• source_kind Literal['inline', 'file'] - Whether the template is inline or file-backed.
• declared_on str | None - Import path of the class that declared the template.
• declaration_file Path | None - Python file containing that declaration, when known.
• template_file Path | None - Resolved file-backed template path, when applicable.
• start_index int - Inclusive UTF-8 byte offset in the root template.
• end_index int - Exclusive UTF-8 byte offset in the root template.
• source_range LspRange - Equivalent zero-based UTF-16 editor range.

origin: str

source_kind: Literal['inline', 'file']

declared_on: str | None

declaration_file: Path | None

template_file: Path | None

start_index: int

end_index: int

source_range: LspRange

Report why Citry could not inspect part of an authored template source.

Graph construction continues after a problem, so callers can use references from unaffected components. component_definition_ids identifies every selected component that consumes the affected physical source.

Attributes

• component_definition_ids tuple[str, ...] - Sorted exact definitions affected.
• code str - Stable graph-local problem category.
• message str - Human-readable explanation.
• origin str - Source or declaration that failed.
• location ComponentGraphLocation | None - Authored range when the failure supplied one.

component_definition_ids: tuple[str, ...]

code: str

message: str

origin: str

location: ComponentGraphLocation | None