Core primitives

The drm.base module defines the low-level graph primitives used throughout the library:

These classes are the foundation for both backends and for all semantic entities defined in drm.drm_entities.

See also drm.networkx_graph and drm.neo4j_graph for the concrete backends that consume these primitives.

Core data structures: Node, Relation, WeakNode, WeakRelation.

These classes represent the graph primitives used by both Neo4jGraph and NetworkXGraph. Nodes carry a primary key (pk), a main label, optional alternative labels, and optional parent relationships for WeakNode hierarchies. Relations connect two nodes with a typed edge.

class drm.base.Node(pk=<object object>, main_label='', alternative_labels=None, version=5, neo4j_id=None, **kwargs)[source]

Bases: object

A graph node with a primary key, labels, and optional parent.

Nodes are the fundamental building blocks of the DRM graph. Each node has a main_label (the primary Cypher label), optional alternative_labels, and a pk (primary key) that uniquely identifies it within its label.

When a parent is provided the node becomes a WeakNode: its primary key is merged with the parent’s key to form a composite key, and a typed edge is created when the node is inserted into a graph store.

By default a node must have a pk or a neo4j_id (or both). If the caller passes pk=None explicitly, the node is created with _primary_key = None and the backend is expected to assign a real ID later (e.g. Neo4j generates an internal node ID, which is then stored as _primary_key). If the backend never assigns one, _primary_key remains None.

Parameters:

  • pk (Dict[str, int | str] | None | object) – Primary key — an int is converted to {"id": pk}, a dict is used as-is. Must be provided (or explicitly None) unless neo4j_id is given.

  • main_label (str) – The primary label used in Cypher queries.

  • alternative_labels (str | List[str] | None) – Additional labels attached to the node.

  • version (int) – Neo4j protocol version (default 5).

  • neo4j_id (int | None) – Internal Neo4j node ID (used when reconstructing a node from a database result).

  • **kwargs (Any) – Arbitrary additional attributes stored on the node. Special kwargs: parent (Node), parent_relation (str), is_weak (bool), _propagate (bool), dependencies.

Raises:

  • ValueError – If pk is not provided at all (not even as None) and neo4j_id is also absent.

  • TypeError – If pk is neither an int nor a dict (when pk is provided but not None).

__init__(pk=<object object>, main_label='', alternative_labels=None, version=5, neo4j_id=None, **kwargs)[source]
Parameters:
class drm.base.Relation(src, dst, rel_type, **kwargs)[source]

Bases: object

A typed edge connecting two nodes in the graph.

Relations store the primary keys of their source and destination nodes and can carry arbitrary edge properties.

Parameters:

  • src (Node) – Source node. Its pk is extracted and stored.

  • dst (Node) – Destination node. Its pk is extracted and stored.

  • type – Relation type (e.g. “HAS_NOM”, “CONNECTS”). Stored uppercase.

  • **kwargs (Any) – Edge properties stored as attributes.

  • rel_type (str)

  • **kwargs

__init__(src, dst, rel_type, **kwargs)[source]

Initialize a Relation between two nodes.

Parameters:

  • src (Node) – Source node. Its pk is extracted and stored.

  • dst (Node) – Destination node. Its pk is extracted and stored.

  • rel_type (str) – Relation type (e.g. “HAS_NOM”, “CONNECTS”). Stored uppercase.

  • **kwargs (Any) – Edge properties stored as attributes.

Return type:

None

class drm.base.WeakNode(**kwargs)[source]

Bases: Node

A node whose identity is tied to its parent node.

WeakNodes form a parent-child hierarchy where the child’s primary key is merged with the parent’s key to produce a composite key. This models document structures such as Document → Section → Page where a child cannot exist without its parent.

When a WeakNode is inserted into a graph store, a typed edge (WeakRelation) is automatically created linking the parent to the child. This edge carries the _propagate=TRUE flag, which triggers cascade delete: deleting the parent automatically deletes all descendants in the hierarchy.

Parameters:

  • parent – The parent Node. Must not be None.

  • **kwargs (Any) – Forwarded to Node.__init__. Common kwargs include pk (child’s primary key), main_label, alternative_labels, parent_relation (default "HAS"), and _propagate.

Raises:

AssertionError – If parent is not a Node instance.

__init__(**kwargs)[source]

Initialize a WeakNode tied to a parent node.

Parameters:

  • parent – The parent Node. Required — must be passed as a kwarg.

  • **kwargs (Any) – Passed to Node.__init__ (pk, main_label, alternative_labels, parent_relation, _propagate, etc.).

Raises:

AssertionError – If parent is not provided or is not a Node instance.

Return type:

None

class drm.base.WeakRelation(src, dst, rel_type, **kwargs)[source]

Bases: Relation

A typed edge connecting a parent node to its child (WeakNode).

WeakRelations are automatically created when a WeakNode is inserted. They carry the _propagate=TRUE flag, which signals to the graph store that deleting the parent should cascade to the child node.

Parameters:

  • src (Node) – Source (parent) node.

  • dst (Node) – Destination (child / WeakNode).

  • rel_type (str) – Relation type (e.g. "HAS_PAGE", "CONTAINS").

  • **kwargs (Any) – Edge properties. The propagate kwarg controls whether the _propagate flag is set (default True).

_propagate

Always True by default. Indicates that deleting the source node should cascade delete to the destination node.

__init__(src, dst, rel_type, **kwargs)[source]

Initialize a WeakRelation with cascade propagation.

Parameters:

  • src (Node) – Source (parent) node.

  • dst (Node) – Destination (child) node.

  • rel_type (str) – Relation type.

  • propagate – If True (default), the edge carries the _propagate=TRUE flag for cascade delete.

  • kwargs (Any)

Return type:

None