ComponentGraph
class
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.
coverage_complete
attribute
coverage_complete: boolWhether every selected primary template was available and parseable.
fully_resolved
attribute
fully_resolved: boolWhether source coverage is complete and every reference has a static target.
component
function
component(selector: str | ComponentGraphNode) -> ComponentGraphNodeReturn one graph node selected by registered name, alias, or retained node.
Parameters
selector
str | ComponentGraphNode
- Case-insensitive registered name or a node from this graph.
Returns
ComponentGraphNode: The canonical node stored in this graph.
Raises
TypeError - If selector is not a string or graph node.
NotRegistered - If the selector does not identify this graph's exact
component generation.
dependencies
function
dependencies(component: str | ComponentGraphNode) -> tuple[ComponentGraphNode, ...]Return unique registered components directly referenced by component.
dependents
function
dependents(component: str | ComponentGraphNode) -> tuple[ComponentGraphNode, ...]Return unique registered components that directly reference component.
references_from
function
references_from(component: str | ComponentGraphNode) -> tuple[ComponentGraphReference, ...]Return every resolved authored reference owned by component.
references_to
function
references_to(component: str | ComponentGraphNode) -> tuple[ComponentGraphReference, ...]Return every resolved authored reference targeting component.
unresolved_from
function
unresolved_from(component: str | ComponentGraphNode | None = None) -> tuple[UnresolvedComponentReference, ...]Return unresolved references from one component, or all of them when omitted.
to_json
function
Serialize this graph 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.
Raises
TypeError - If indent is not an integer or None.
ValueError - If indent is negative.
ComponentGraphNode
class
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.
ComponentGraphReference
class
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.
UnresolvedComponentReference
class
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.
ComponentGraphLocation
class
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.
ComponentGraphProblem
class
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.