Model Objects

Warning

This is the first iteration of the interface for model objects. The function/class signatures might change in the next releases.

Basic Usage

Creating NodeSet and RelationshipSet classes with string is error prone.

Graphio offers a simple object graph model system:

from graphio import ModelNode, ModelRelationship

class Person(ModelNode):
    name = MergeKey()

class Food(ModelNode):
    type = MergeKey()

class PersonLikes(ModelRelationship):
    source = Person
    target = Food
    type = 'LIKES'

You can use these classes to create NodeSet and RelationshipSet:

person_nodeset = Person.dataset()
food_nodeset = Food.dataset()

person_likes_food = PersonLikes.dataset()

When adding data to the RelationshipSet you can use the MergeKey properties of the ModelNode classes to avoid typing the properties as strings:

for name, food in [('Susan', 'Pizza'), ('Ann', 'Sushi')]:
    person_likes_food.add_relationship(
        {Person.name: name}, {Food.type: food}
    )

You can set one or multiple Label and MergeKey properties on the ModelNode:

class Person(ModelNode):
    first_name = MergeKey()
    last_name = MergeKey()

    Person = Label()
    Human = Label()

You can override the actual values of the Label and MergeKey:

class Person(ModelNode):
    first_name = MergeKey('first_name')
    last_name = MergeKey('surname')

    Person = Label('Individual')
    Human = Label('HomoSapiens')

Add data with model instances

You can create instances of the model objects to create individual nodes and relationships:

from graphio import ModelNode, ModelRelationship
from py2neo import Graph

graph = Graph()

class Person(ModelNode):
    name = MergeKey()

class Food(ModelNode):
    type = MergeKey()

class PersonLikes(ModelRelationship):
    source = Person
    target = Food
    type = 'LIKES'

alice = Person(name='Alice')
sushi = Food(type='Sushi')

alice.merge(graph)
sushi.merge(graph)

alice_likes_sushi = PersonLikes(alice, sushi)
alice_likes_sushi.merge(graph)

You can also link nodes without creating ModelRelationship instances:

alice.link(graph, PersonLikes, sushi, since='always')

ModelNode

class graphio.ModelNode(*args, **kwargs)

Baseclass for model objects.

property additional_props: dict

Return all properties except the merge properties.

Returns: Dictionary with all properties except the merge properties.
Return type: dict

bind(graph)

Make sure the node is bound to the graph.

Parameters: graph – py2neo.Graph

classmethod dataset() → graphio.objects.nodeset.NodeSet

Returns: Return a NodeSet instance for this ModelNode.

exists(graph: py2neo.database.Graph) → Union[bool, py2neo.data.Node]

Check if node exists in the graph. If yes: return the Node. If no: return false.

Raise a TypeError if there is more than one Node found with these properties. Node definition only makes sense if working with unique nodes.

Parameters: graph – py2neo.Graph instance
Returns: The node or False.

classmethod factory(labels: List[str], merge_keys: Optional[List[str]] = None, name: Optional[str] = None) → type

Create a class with given labels and merge_keys. The merge_keys are optional but some functions do not work without them.

Parameters

labels – Labels for this ModelNode class.
merge_keys – MergeKeys for this ModelNode class.

Returns

The ModelNode class.

link(graph: py2neo.database.Graph, reltype: Union[Type[graphio.model.ModelRelationship], str], target: Union[graphio.model.ModelNode, graphio.model.NodeDescriptor], **properties) → None

Link the node to another node.

Input is either a combination of a ModelRelationship and ModelNode or a combination of a string for the reltype and a NodeDescriptor instance to describe the target node.

Parameters

graph – py2neo.Graph instance.
reltype – Either a ModelRelationship instance or a string for the relationship type.
target – Either a ModelNode instance or a NodeDescriptor instance.
properties – Proeprties for the relationships.

merge(graph: py2neo.database.Graph) → None

MERGE the node in the graph.

Parameters: graph – A py2neo.Graph instance.

property merge_props: dict

Return the merge properties for this node.

Returns: Dictionary with the merge properties for this node.
Return type: dict

ModelRelationship

class graphio.ModelRelationship(source: graphio.model.ModelNode, target: graphio.model.ModelNode, **kwargs)

Base class for model relationships.

Knows about the class of source node and target node (instances of ModelNode) and the relationship type:

class Person(ModelNode):
    name = MergeKey()

class Food(ModelNode):
    name = MergeKey()

class PersonLikesToEat(ModelRelationship):
    source = Person
    target = Food
    type = 'LIKES'

classmethod dataset() → graphio.objects.relationshipset.RelationshipSet

Returns: Return a RelationshipSet instance for this ModelRelationship.

exists(graph: py2neo.database.Graph) → bool

Check if the relationship exists.

Parameters: graph – A py2neo.Graph instance.
Returns: True/False

merge(graph: py2neo.database.Graph)

MERGE the relationship in the graph.

Parameters: graph – A py2neo.Graph instance.

Helper Classes

class graphio.NodeDescriptor(labels: List[str], properties: dict, merge_keys: Optional[List[str]] = None)

Unified interface to describe nodes with labels and properties.

NodeDescriptor instances are passed into functions when no ModelNode classes or instances are available.

Setting merge_keys is optional. If they are not set all property keys will be used as merge_keys.

Parameters

labels – Labels for this node.
properties – Properties for this node.
merge_keys – Optional.