Models

Create custom, type-checked domain objects.

Example:

# people.py

from bulbs.model import Node, Relationship
from bulbs.property import String, Integer, DateTime
from bulbs.utils import current_datetime

class Person(Node):

    element_type = "person"

    name = String(nullable=False)
    age = Integer()


class Knows(Relationship):

    label = "knows"

    timestamp = DateTime(default=current_datetime, nullable=False)

You can use the Graph add_proxy() method to build Model proxies based on the Model container, and add them to the Graph object:

>>> from people import Person, Knows
>>> from bulbs.neo4jserver import Graph

>>> g = Graph()
>>> g.add_proxy("people", Person)
>>> g.add_proxy("knows", Knows)

>>> james = g.people.create(name="James")
>>> julie = g.people.create(name="Julie")
>>> knows = g.knows.create(james, julie)

By convention, proxy objects are named using the plural form of their container object.

For example, the Vertex container’s proxy is named “vertices”, the Edge proxy is named “edges”, the Person proxy is named “people”.

Node Proxy

class bulbs.model.NodeProxy(element_class, client)[source]
create(_data=None, **kwds)[source]

Adds a vertex to the database and returns it.

Parameters:
  • _data (dict) – Optional property data dict.
  • kwds (dict) – Optional property data keyword pairs.
Return type:

Node

update(_id, _data=None, **kwds)[source]

Updates an element in the graph DB and returns it.

Parameters:
  • _id (int or str) – The vertex ID.
  • _data (dict) – Optional property data dict.
  • kwds (dict) – Optional property data keyword pairs.
Return type:

Node

get_all()[source]

Returns all the elements for the model type.

Return type:Node generator
get_property_keys()[source]

Returns a list of all the Property keys.

Return type:list
delete(_id)

Deletes a vertex from the graph database and returns the response.

Parameters:_id (int or str) – The vertex ID.
Return type:Response
get(_id)

Returns the vertex for the given ID.

Parameters:_id (int or str) – The vertex ID.
Return type:Vertex or None
get_or_create(key, value, _data=None, **kwds)

Lookup a vertex in the index and create it if it doesn’t exsit.

Parameters:
  • key (str) – Index key.
  • value (str, int, long) – Index value.
  • _data (dict) – Optional property data dict.
  • kwds (dict) – Optional property data keyword pairs.
Return type:

Vertex

remove_properties(_id)

Removes all properties from a vertex and returns the response.

Parameters:_id (int or str) – The vertex ID.
Return type:Response

Node Container

class bulbs.model.Node(client)[source]

Abstract base class used for creating a Vertex Model.

It’s used to create classes that model domain objects, and it’s not meant to be used directly. To use it, create a subclass specific to the type of data you are storing.

Example model declaration:

# people.py

from bulbs.model import Node
from bulbs.property import String, Integer

class Person(Node):
    element_type = "person"
    
    name = String(nullable=False)
    age = Integer()

Example usage:

>>> from people import Person
>>> from bulbs.neo4jserver import Graph
>>> g = Graph()

# Add a "people" proxy to the Graph object for the Person model:
>>> g.add_proxy("people", Person)

# Use it to create a Person node, which also saves it in the database:
>>> james = g.people.create(name="James")
>>> james.eid
3
>>> james.name
'James'

# Get the node (again) from the database by its element ID:
>>> james = g.people.get(james.eid)

# Update the node and save it in the database:
>>> james.age = 34
>>> james.save()

# Lookup people using the Person model's primary index:
>>> nodes = g.people.index.lookup(name="James")
_initialize(result)[source]

Initializes the element. Initialize all non-DB attributes here.

Parameters:result (Result) – Result object.
Return type:None

..note:: Called by _create, _update, and utils.initialize_element.

_id

Returns the element ID.

Return type:int or str

Note

This is the element’s “primary key”; however, some DBs (such as neo4j) reuse IDs if they are deleted so be careful with how you use them.

If you want to guarantee they are unique across the DB’s lifetime either don’t physically delete elements and just set a deleted flag, or use some other mechanism for the primary key, such as an external sequence or a hash.

_type

Returns the result’s base type, either vertex or edge.

Return type:str
classmethod get_element_type(config)[source]

Returns the element type.

Parameters:config (bulbs.config.Config) – Config object.
Return type:str
classmethod get_element_key(config)[source]

Returns the element key.

Parameters:config (bulbs.config.Config) – Config object.
Return type:str
classmethod get_index_name(config)[source]

Returns the index name.

Parameters:config (bulbs.config.Config) – Config object.
Return type:str
classmethod get_proxy_class()[source]

Returns the proxy class.

Parameters:config (bulbs.config.Config) – Config object.
Return type:class
save()[source]

Saves/updates the element’s data in the database.

Return type:None
bothE(label=None, start=None, limit=None)

Returns the incoming and outgoing edges.

Parameters:label (str or None) – Optional edge label.
Return type:Edge generator
bothV(label=None, start=None, limit=None)

Returns all incoming- and outgoing-adjacent vertices.

Parameters:label (str or None) – Optional edge label.
Return type:Vertex generator
data()

Returns a the element’s property data.

Return type:dict
get(name, default_value=None)

Returns the value of a Python attribute or the default value.

Parameters:
  • name (str) – Python attribute name.
  • default_value (object) – Default value. Defaults to None.
Return type:

object or None

classmethod get_base_type()

Returns this element class’s base type, which is “vertex”.

Return type:str

WARNING

Don’t override this.

get_bundle(_data=None, **kwds)

Returns a tuple contaning the property data, index name, and index keys.

Parameters:
  • _data (dict) – Data that was passed in via a dict.
  • kwds (dict) – Data that was passed in via name/value pairs.
Return type:

tuple

get_index_keys()

Returns Property keys to index in DB. Defaults to None (index all keys).

Return type:list or None
get_property_keys()

Returns a list of all the Property keys.

Return type:list
inE(label=None, start=None, limit=None)

Returns the incoming edges.

Parameters:label (str or None) – Optional edge label.
Return type:Edge generator
inV(label=None, start=None, limit=None)

Returns the in-adjacent vertices.

Parameters:label (str or None) – Optional edge label.
Return type:Vertex generator
map()

Deprecated. Returns the element’s property data.

Return type:dict
outE(label=None, start=None, limit=None)

Returns the outgoing edges.

Parameters:label (str or None) – Optional edge label.
Return type:Edge generator
outV(label=None, start=None, limit=None)

Returns the out-adjacent vertices.

Parameters:label (str or None) – Optional edge label.
Return type:Vertex generator

Relationship Proxy

class bulbs.model.RelationshipProxy(element_class, client)[source]
create(outV, inV, _data=None, **kwds)[source]

Creates an edge in the database and returns it.

Parameters:
  • outV (Vertex or int) – The outgoing vertex.
  • inV (Vertex or int) – The incoming vertex.
  • _data (dict) – Optional property data dict.
  • kwds (dict) – Optional property data keyword pairs.
Return type:

Relationship

update(_id, _data=None, **kwds)[source]

Updates an edge in the database and returns it.

Parameters:
  • _id (int or str) – The edge ID.
  • _data (dict) – Optional property data dict.
  • kwds (dict) – Optional property data keyword pairs.
Return type:

Relationship

get_all()[source]

Returns all the relationships for the label.

Return type:Relationship generator
get_property_keys()[source]

Returns a list of all the Property keys.

Return type:list
delete(_id)

Deletes a vertex from a graph database and returns the response.

Parameters:_id (int or str) – The edge ID.
Return type:Response
get(_id)

Retrieves an edge from the database and returns it.

Parameters:_id (int or str) – The edge ID.
Return type:Edge or None
remove_properties(_id)

Removes all properties from a element and returns the response.

Parameters:_id (int or str) – The edge ID.
Return type:Response

Relationship Container

class bulbs.model.Relationship(client)[source]

Abstract base class used for creating a Relationship Model.

It’s used to create classes that model domain objects, and it’s not meant to be used directly. To use it, create a subclass specific to the type of data you are storing.

Example usage for an edge between a blog entry node and its creating user:

# people.py

from bulbs.model import Relationship
from bulbs.properties import DateTime
from bulbs.utils import current_timestamp

class Knows(Relationship):

    label = "knows"

    created = DateTime(default=current_timestamp, nullable=False)

Example usage:

>>> from people import Person, Knows
>>> from bulbs.neo4jserver import Graph
>>> g = Graph()

# Add proxy interfaces to the Graph object for each custom Model
>>> g.add_proxy("people", Person)
>>> g.add_proxy("knows", Knows)

# Create two Person nodes, which are automatically saved in the DB
>>> james = g.people.create(name="James")
>>> julie = g.people.create(name="Julie")

# Create a "knows" relationship between James and Julie:
>>> knows = g.knows.create(james,julie)
>>> knows.timestamp

# Get the people James knows (the outgoing vertices labeled "knows")
>>> friends = james.outV('knows')
_initialize(result)[source]

Initializes the element. Initialize all non-DB attributes here.

Parameters:result (Result) – Result object.
Return type:None

..note:: Called by _create, _update, and utils.initialize_element.

_id

Returns the element ID.

Return type:int or str

Note

This is the element’s “primary key”; however, some DBs (such as neo4j) reuse IDs if they are deleted so be careful with how you use them.

If you want to guarantee they are unique across the DB’s lifetime either don’t physically delete elements and just set a deleted flag, or use some other mechanism for the primary key, such as an external sequence or a hash.

_type

Returns the result’s base type, either vertex or edge.

Return type:str
classmethod get_label(config)[source]

Returns the edge’s label.

Parameters:config (bulbs.config.Config) – Config object.
Return type:str
classmethod get_element_key(config)[source]

Returns the element key.

Parameters:config (bulbs.config.Config) – Config object.
Return type:str
classmethod get_index_name(config)[source]

Returns the index name.

Parameters:config (bulbs.config.Config) – Config object.
Return type:str
classmethod get_proxy_class()[source]

Returns the proxy class.

Parameters:config (bulbs.config.Config) – Config object.
Return type:class
save()[source]

Saves/updates the element’s data in the database.

Return type:None
data()

Returns a the element’s property data.

Return type:dict
get(name, default_value=None)

Returns the value of a Python attribute or the default value.

Parameters:
  • name (str) – Python attribute name.
  • default_value (object) – Default value. Defaults to None.
Return type:

object or None

classmethod get_base_type()

Returns this element class’s base type, which is “edge”.

Return type:str

WARNING

Don’t override this.

get_bundle(_data=None, **kwds)

Returns a tuple contaning the property data, index name, and index keys.

Parameters:
  • _data (dict) – Data that was passed in via a dict.
  • kwds (dict) – Data that was passed in via name/value pairs.
Return type:

tuple

get_index_keys()

Returns Property keys to index in DB. Defaults to None (index all keys).

Return type:list or None
get_property_keys()

Returns a list of all the Property keys.

Return type:list
inV()

Returns the incoming (end) Vertex of the edge.

Return type:Vertex
map()

Deprecated. Returns the element’s property data.

Return type:dict
outV()

Returns the outgoing (start) Vertex of the edge.

Return type:Vertex