Skip to main content

infrahub_sdk.node.related_node

Classes​

RelatedNodeBase​

Base class for representing a related node in a relationship.

A RelatedNodeBase is the peer end of a cardinality-one relationship. It carries the lightweight identification of the peer (id, hfid, typename, ...) along with the relationship-edge properties (source, owner, is_protected, ...). The peer node is fetched lazily through :meth:RelatedNode.fetch / :meth:RelatedNodeSync.fetch.

Attributes:

  • schema: The schema describing the relationship.
  • name: The name of the relationship slot on the parent node.
  • updated_at: ISO-8601 timestamp of the most recent edge update.
  • is_loaded: True when the node's data contained the relationship, it was assigned since, it does not belong to a node, or the node has no id yet.

Methods:

id​

id(self) -> str | None

Return the parsed peer id without triggering a store lookup.

Returns None when the response carried only hfid_str (no id, no peer) — in that case .peer.id would resolve through the store and yield a non-None id, so .id and .peer.id are NOT interchangeable.

Returns:

  • str | None: The peer node ID, or None when neither the peer nor an ID is set.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.

hfid​

hfid(self) -> list[Any] | None

Return the human-friendly ID of the related node.

When the cached peer was fetched with only and has no HFID, because the response did not contain one and the fields it carries do not give one, the HFID the relationship was loaded with is returned instead.

Returns:

  • list[Any] | None: The peer HFID as a list of components, or None when not set.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.

hfid_str​

hfid_str(self) -> str | None

Return the human-friendly ID of the related node as a separator-joined string.

The returned string includes the kind prefix and is therefore suitable as a key for the client store. When the cached peer was fetched with only and has no HFID, because the response did not contain one and the fields it carries do not give one, the string is built from the HFID the relationship was loaded with.

Returns:

  • str | None: The peer HFID joined with the HFID separator, or None when
  • unavailable (no resolved peer or missing HFID).

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.

is_resource_pool​

is_resource_pool(self) -> bool

Return whether the related node is a resource pool.

Returns:

  • True when the resolved peer inherits from CoreResourcePool.

initialized​

initialized(self) -> bool

Return whether this related node has an identifier.

Returns:

  • True when an ID or HFID is known and the relationship can be referenced.

is_loaded​

is_loaded(self) -> bool

Return whether this relationship holds the peer from its node's data or from an assignment.

Never raises and sends no request.

Returns:

  • True when the data the node was built from contained the relationship, even
  • without a peer, when the relationship was assigned since, when it does not belong to a
  • node (such as a peer inside a cardinality-many relationship), or when its node has no
  • id yet. False otherwise.

display_label​

display_label(self) -> str | None

Return the human-readable label of the related node.

Returns:

  • str | None: The peer display label, or None when not provided.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.

typename​

typename(self) -> str | None

Return the GraphQL __typename of the related node.

Returns:

  • str | None: The peer typename, or None when not provided.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.

kind​

kind(self) -> str | None

Return the schema kind of the related node.

Returns:

  • str | None: The peer schema kind, or None when not provided.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.

is_from_profile​

is_from_profile(self) -> bool

Return whether this relationship was set from a profile.

A relationship is considered profile-sourced when the typename of its source property starts with the profile kind prefix.

Returns:

  • True when the relationship's source is a profile node.

get_relationship_metadata​

get_relationship_metadata(self) -> RelationshipMetadata | None

Return the relationship-edge metadata (updated_at, updated_by).

The metadata is populated only when the parent query was executed with include_metadata=True.

Returns:

  • RelationshipMetadata | None: The edge metadata if fetched, otherwise None.

RelatedNode​

Asynchronous related node bound to an :class:InfrahubClient.

Extends :class:RelatedNodeBase with the ability to lazily resolve the peer node: :meth:fetch retrieves the full peer from the backend, :meth:get returns it from the local cache or the client store, and :attr:peer is a convenience accessor around :meth:get.

Methods:

fetch​

fetch(self, timeout: int | None = None, priority: Priority | None = None, only: list[str] | None = None) -> None

Fetch the peer with its default fields, or only the fields named in only, and cache it on this object.

After fetch() completes, attribute and relationship access on the peer is available via :attr:peer or :meth:get.

Args:

  • timeout: Overrides the default timeout used when querying the GraphQL API. Specified in seconds.
  • priority: Override the client-wide request priority for this fetch. When None, the client default is used.
  • only: The only attributes and relationships to fetch on the peer, which also gets its id, display_label and __typename. Reading a field of the peer that was not fetched raises FieldNotLoadedError.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.
  • FieldNotFoundError: A name in only is not a field of the peer's kind; raised before the peer is queried.
  • TypeError: only is a string instead of a list of field names; raised before the peer is queried.
  • Error: If neither id nor typename is set on this related node.

peer​

peer(self) -> PeerT

Return the resolved peer node.

This is a convenience accessor for :meth:get; the peer must already have been fetched or stored in the client store.

Returns:

  • The resolved peer node.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.

get​

get(self) -> PeerT

Return the resolved peer node from cache or the client store.

Lookup order:

  1. The peer cached locally after a successful :meth:fetch.
  2. The client store keyed by id and typename.
  3. The client store keyed by hfid_str.

When resolving via hfid_str the returned node has a non-None id even when this RelatedNode's .id is None — that is the case in which .peer.id and .id diverge.

Returns:

  • The resolved peer node.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.
  • ValueError: If neither an ID nor an HFID is available to look up the peer.

RelatedNodeSync​

Synchronous related node bound to an :class:InfrahubClientSync.

Synchronous counterpart of :class:RelatedNode. Extends :class:RelatedNodeBase with the ability to lazily resolve the peer node: :meth:fetch retrieves the full peer from the backend, :meth:get returns it from the local cache or the client store, and :attr:peer is a convenience accessor around :meth:get.

Methods:

fetch​

fetch(self, timeout: int | None = None, priority: Priority | None = None, only: list[str] | None = None) -> None

Fetch the peer with its default fields, or only the fields named in only, and cache it on this object.

After fetch() completes, attribute and relationship access on the peer is available via :attr:peer or :meth:get.

Args:

  • timeout: Overrides the default timeout used when querying the GraphQL API. Specified in seconds.
  • priority: Override the client-wide request priority for this fetch. When None, the client default is used.
  • only: The only attributes and relationships to fetch on the peer, which also gets its id, display_label and __typename. Reading a field of the peer that was not fetched raises FieldNotLoadedError.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.
  • FieldNotFoundError: A name in only is not a field of the peer's kind; raised before the peer is queried.
  • TypeError: only is a string instead of a list of field names; raised before the peer is queried.
  • Error: If neither id nor typename is set on this related node.

peer​

peer(self) -> PeerTSync

Return the resolved peer node.

This is a convenience accessor for :meth:get; the peer must already have been fetched or stored in the client store.

Returns:

  • The resolved peer node.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.

get​

get(self) -> PeerTSync

Return the resolved peer node from cache or the client store.

Lookup order:

  1. The peer cached locally after a successful :meth:fetch.
  2. The client store keyed by id and typename.
  3. The client store keyed by hfid_str.

When resolving via hfid_str the returned node has a non-None id even when this RelatedNode's .id is None — that is the case in which .peer.id and .id diverge.

Returns:

  • The resolved peer node.

Raises:

  • FieldNotLoadedError: The node was queried with only and the relationship was not fetched.
  • ValueError: If neither an ID nor an HFID is available to look up the peer.

RelationshipAttribute​

Typing descriptor for a cardinality-one relationship on a generated protocol.

It reads back as RelatedNode[PeerT] (so .peer keeps the peer type) but accepts assignment of an id string, an HFID, a peer node, or None — mirroring the runtime InfrahubNode.__setattr__ behaviour, which wraps the assigned value in a RelatedNode.

This type only appears in generated protocols (it is never instantiated at runtime), so it exists purely to give node.rel separate read and assignment types under a type checker.

RelationshipAttributeSync​

Synchronous counterpart of :class:RelationshipAttribute.