Skip to main content

infrahub_sdk.node.relationship

Classes​

RelationshipManagerBase​

Base class for :class:RelationshipManager and :class:RelationshipManagerSync.

A RelationshipManagerBase exposes a cardinality-many relationship as a list of peers along with helpers to add, remove, or extend the set. Relationship managers are initialized lazily: until :meth:fetch (on the async/sync subclasses) is called, the members are not loaded and editing is not allowed.

Attributes:

  • name: The name of the relationship slot on the parent node.
  • schema: The schema describing the relationship.
  • branch: The branch the relationship is bound to.
  • peers: The current peer set.
  • initialized: True once the manager has been populated with data.

Methods:

is_fetched​

is_fetched(self) -> bool

Return whether this relationship was present in the response the node was built from.

Exposed under the same name as on Attribute and RelatedNode so merge logic can branch uniformly on is_fetched. Unlike initialized this is also True for a relationship the response carried as null, so the client store can tell "emptied on the server" from "not queried".

Returns:

  • True when the response carried this relationship.

peer_ids​

peer_ids(self) -> list[str]

Return the IDs of all peers that have one.

Returns:

  • list[str]: The IDs of the peers, in insertion order.

peer_hfids​

peer_hfids(self) -> list[list[Any]]

Return the HFIDs of all peers that have one.

Returns:

  • list[list[Any]]: The HFIDs of the peers as lists of components, in insertion order.

peer_hfids_str​

peer_hfids_str(self) -> list[str]

Return the HFIDs of all peers as separator-joined strings.

Returns:

  • list[str]: The HFIDs of the peers as Kind__part1__part2 strings.

has_update​

has_update(self) -> bool

Return whether the peer set has been modified since initialization.

Drives the mutation payload and stays set for the life of the object, so a later save still re-asserts the peer set.

Returns:

  • True after a successful :meth:add, :meth:extend, or :meth:remove.

is_from_profile​

is_from_profile(self) -> bool

Return whether this relationship was set from a profile.

The relationship is considered profile-sourced only when every peer is itself sourced from a profile.

Returns:

  • True when at least one peer exists and all peers are from a profile.

RelationshipManager​

Asynchronous manager for a cardinality-many relationship.

Extends :class:RelationshipManagerBase with the ability to populate and edit the peer set against an :class:InfrahubClient: :meth:fetch resolves every peer in a parallel batch and :meth:add, :meth:extend, and :meth:remove mutate the peer list in memory. Peers are exposed as :class:RelatedNode instances and can be accessed by index via manager[i].

Methods:

fetch​

fetch(self) -> None

Populate the peer set and resolve every peer to a full node.

When the manager is not yet initialized, the parent node is re-queried with this relationship included so the peer list can be populated. The peers are then fetched in a parallel batch grouped by kind and stored in the client store.

Raises:

  • Error: If any peer is missing an id or typename and cannot be resolved.

add​

add(self, data: str | RelatedNode | dict) -> None

Add a new peer to this relationship.

The new peer is only added when its ID or HFID is not already present; duplicate adds are silently ignored.

Args:

  • data: The peer to add. Accepts an ID string, an existing :class:RelatedNode, or a dict describing the peer (with id or hfid keys, plus optional relationship properties).

Raises:

  • UninitializedError: If :meth:fetch has not been called on this manager yet.

extend​

extend(self, data: Iterable[str | RelatedNode | dict]) -> None

Add new peers to this relationship.

This is a convenience wrapper that calls :meth:add for every item in data. Items already present (by ID or HFID) are silently ignored.

Args:

  • data: The peers to add, in any of the formats accepted by :meth:add.

Raises:

  • UninitializedError: If :meth:fetch has not been called on this manager yet.

remove​

remove(self, data: str | RelatedNode | dict) -> None

Remove a peer from this relationship.

The peer to remove is matched first by ID, then by HFID. When no match is found, the call is a no-op.

Args:

  • data: The peer to remove. Accepts an ID string, an existing :class:RelatedNode, or a dict describing the peer.

Raises:

  • UninitializedError: If :meth:fetch has not been called on this manager yet.
  • IndexError: If the internal peer index is inconsistent with the lookup result.

RelationshipManagerSync​

Synchronous manager for a cardinality-many relationship.

Synchronous counterpart of :class:RelationshipManager. Extends :class:RelationshipManagerBase with the ability to populate and edit the peer set against an :class:InfrahubClientSync: :meth:fetch resolves every peer in a parallel batch and :meth:add, :meth:extend, and :meth:remove mutate the peer list in memory. Peers are exposed as :class:RelatedNodeSync instances and can be accessed by index via manager[i].

Methods:

fetch​

fetch(self) -> None

Populate the peer set and resolve every peer to a full node.

When the manager is not yet initialized, the parent node is re-queried with this relationship included so the peer list can be populated. The peers are then fetched in a parallel batch grouped by kind and stored in the client store.

Raises:

  • Error: If any peer is missing an id or typename and cannot be resolved.

add​

add(self, data: str | RelatedNodeSync | dict) -> None

Add a new peer to this relationship.

The new peer is only added when its ID or HFID is not already present; duplicate adds are silently ignored.

Args:

  • data: The peer to add. Accepts an ID string, an existing :class:RelatedNodeSync, or a dict describing the peer (with id or hfid keys, plus optional relationship properties).

Raises:

  • UninitializedError: If :meth:fetch has not been called on this manager yet.

extend​

extend(self, data: Iterable[str | RelatedNodeSync | dict]) -> None

Add new peers to this relationship.

This is a convenience wrapper that calls :meth:add for every item in data. Items already present (by ID or HFID) are silently ignored.

Args:

  • data: The peers to add, in any of the formats accepted by :meth:add.

Raises:

  • UninitializedError: If :meth:fetch has not been called on this manager yet.

remove​

remove(self, data: str | RelatedNodeSync | dict) -> None

Remove a peer from this relationship.

The peer to remove is matched first by ID, then by HFID. When no match is found, the call is a no-op.

Args:

  • data: The peer to remove. Accepts an ID string, an existing :class:RelatedNodeSync, or a dict describing the peer.

Raises:

  • UninitializedError: If :meth:fetch has not been called on this manager yet.
  • IndexError: If the internal peer index is inconsistent with the lookup result.