Relationship

pylpg.relationship

Relationship classes and descriptors for graph edges.

Classes:

Name	Description
BoundRelationship	A relationship descriptor bound to a specific node instance.
Direction	Direction of a relationship traversal.
Relationship	Base class for graph relationships.
RelationshipDescriptor	Descriptor that declares a relationship on a Node class.
RelationshipFrom	Declares an incoming relationship on a Node class.
RelationshipTo	Declares an outgoing relationship on a Node class.
RelationshipUndirected	Declares an undirected relationship on a Node class.

BoundRelationship

BoundRelationship(owner: Node, descriptor: RelationshipDescriptor)

A relationship descriptor bound to a specific node instance.

Provides all() to traverse and connect() to create relationships.

Methods:

Name	Description
all	Return all nodes connected to the owner via this relationship.
connect	Create and save a relationship from the owner to target_node.

Source code in src/pylpg/relationship.py

def __init__(
    self,
    owner: pylpg.node.Node,
    descriptor: "RelationshipDescriptor",
) -> None:
    self._owner = owner
    self._descriptor = descriptor

all

all() -> list[Node]

Return all nodes connected to the owner via this relationship.

Source code in src/pylpg/relationship.py

def all(self) -> list[pylpg.node.Node]:
    """Return all nodes connected to the owner via this relationship."""
    return self._get_session()._traverse(
        node=self._owner,
        relationship_type=self._descriptor._relationship_class.__type__,
        direction=self._descriptor._direction,
    )

connect

connect(target_node: Node, **properties: Any) -> None

Create and save a relationship from the owner to target_node.

Example

session.save(alice)
session.save(bob)
alice.friends.connect(bob, since="2024")

Source code in src/pylpg/relationship.py

def connect(self, target_node: pylpg.node.Node, **properties: typing.Any) -> None:
    """Create and save a relationship from the owner to target_node.

    Example:
        ```python
        session.save(alice)
        session.save(bob)
        alice.friends.connect(bob, since="2024")
        ```
    """
    session = self._get_session()
    if self._descriptor._direction == Direction.INCOMING:
        (source, target) = (target_node, self._owner)
    else:
        (source, target) = (self._owner, target_node)
    relationship = self._descriptor._relationship_class(
        source=source,
        target=target,
        **properties,
    )
    session.save(relationship)

Direction

Bases: Enum

Direction of a relationship traversal.

Relationship

Relationship(*, source: Node, target: Node, **kwargs: Any)

Base class for graph relationships.

Subclass Relationship to define relationship types. The __type__ class attribute is required and sets the relationship type in the database.

Example

class Knows(Relationship):
    __type__ = "KNOWS"
    since: str | None = None

Methods:

Name	Description
is_saved	Return True if this relationship has been saved to the database.
to_dict	Return primitive properties as a dict, excluding None values.

Source code in src/pylpg/relationship.py

def __init__(
    self,
    *,
    source: pylpg.node.Node,
    target: pylpg.node.Node,
    **kwargs: typing.Any,
) -> None:
    self._database_id = None
    self._temp_id = uuid.uuid4().hex
    self.source = source
    self.target = target
    for property_name in self.__primitive_properties__:
        if property_name in kwargs:
            setattr(self, property_name, kwargs[property_name])
        elif not hasattr(type(self), property_name):
            raise ValueError(f"Missing required property: {property_name}")

is_saved

is_saved() -> bool

Return True if this relationship has been saved to the database.

Source code in src/pylpg/relationship.py

def is_saved(self) -> bool:
    """Return True if this relationship has been saved to the database."""
    return self._database_id is not None

to_dict

to_dict() -> dict[str, Any]

Return primitive properties as a dict, excluding None values.

Source code in src/pylpg/relationship.py

def to_dict(self) -> dict[str, typing.Any]:
    """Return primitive properties as a dict, excluding None values."""
    result: dict[str, typing.Any] = {}
    for property_name in self.__primitive_properties__:
        property_value = getattr(self, property_name)
        if property_value is not None:
            result[property_name] = property_value
    return result

RelationshipDescriptor

RelationshipDescriptor(direction: Direction, relationship_class: type[Relationship])

Descriptor that declares a relationship on a Node class.

Use the convenience subclasses RelationshipTo, RelationshipFrom, and RelationshipUndirected instead of this class directly.

Source code in src/pylpg/relationship.py

def __init__(
    self,
    direction: Direction,
    relationship_class: type[Relationship],
) -> None:
    self._direction = direction
    self._relationship_class = relationship_class

RelationshipFrom

RelationshipFrom(relationship_class: type[Relationship])

Bases: RelationshipDescriptor

Declares an incoming relationship on a Node class.

Example

class Person(Node):
    name: str
    known_by = RelationshipFrom(Knows)

Source code in src/pylpg/relationship.py

def __init__(
    self,
    relationship_class: type[Relationship],
) -> None:
    super().__init__(
        direction=Direction.INCOMING,
        relationship_class=relationship_class,
    )

RelationshipTo

RelationshipTo(relationship_class: type[Relationship])

Bases: RelationshipDescriptor

Declares an outgoing relationship on a Node class.

Example

class Person(Node):
    name: str
    friends = RelationshipTo(Knows)

Source code in src/pylpg/relationship.py

def __init__(
    self,
    relationship_class: type[Relationship],
) -> None:
    super().__init__(
        direction=Direction.OUTGOING,
        relationship_class=relationship_class,
    )

RelationshipUndirected

RelationshipUndirected(relationship_class: type[Relationship])

Bases: RelationshipDescriptor

Declares an undirected relationship on a Node class.

Example

class Person(Node):
    name: str
    contacts = RelationshipUndirected(Knows)

Source code in src/pylpg/relationship.py

def __init__(
    self,
    relationship_class: type[Relationship],
) -> None:
    super().__init__(
        direction=Direction.UNDIRECTED,
        relationship_class=relationship_class,
    )