Ref

Typed reference to an Entity represented as a path string in JSON.

Member Functions:

ref_string (field)

Returns

str

for_target

for_target(data: RefScope, target: E)

Create a reference to an entity contained in data.

Each configuration of the scope is indexed by entity on first use and the index reused afterwards, so building many references costs one walk per configuration rather than one per reference. An entity added since is looked for at the end of the lists declared to hold its type, and only a target neither can serve rescans the configuration, so entities may be added, renamed, moved, or removed between calls.

Parameters
Name Type Description

data

RefScope

The configuration, or configurable unit, that owns the target entity.

target

E

Entity to reference.

Returns

Ref[E]

Raises:

  • ValueError — If target is not contained in data.

get_target

get_target(scope: RefScope)

Resolve this reference inside scope.

Builds a resolver for one lookup. Hold a RefResolver instead when resolving many references against the same data: it indexes the entities once.

When scope holds this reference, the configuration that holds it is the source, so a target in another pillar of the unit is CROSS_PILLAR, as in RefResolver.validate.

Parameters
Name Type Description

scope

RefScope

The configuration, or configurable unit, to resolve against.

Returns

RefOutcome[E] — The outcome, classified as RESOLVED, EXTERNAL, NOT_FOUND, TYPE_MISMATCH, AMBIGUOUS, or CROSS_PILLAR.