Bulbs API¶

Open-source Python library for graph databases.

Bulbs supports pluggable backends and currently has bindings for Neo4j Server and Rexster.

Rexster is the Blueprints server and so this means Bulbs supports any Blueprints-enabled graph database, including: Neo4j, InfiniteGraph, OrientDB, Dex, TinkerGraph, and OpenRDF Sail.

Graph¶

class bulbs.base.graph.Graph(config=None)[source]

Abstract base class for the server-specific Graph implementations.

Parameters:	config (Config) – Optional Config object. Defaults to the default config.
Variables:	client_class – Client class. default_index – Default index class. client – Client object. config – Config object. vertices – VertexProxy object. edges – EdgeProxy object.

Example:

>>> from bulbs.neo4jserver import Graph
>>> g = Graph()
>>> james = g.vertices.create(name="James")
>>> julie = g.vertices.create(name="Julie")
>>> g.edges.create(james, "knows", julie)

Graph.client_class: alias of Client

Graph.default_index: alias of Index

Graph.V[source]

Returns a list of all the vertices in the graph.

Return type:	list or None

Graph.E[source]

Returns a list of all the edges in the graph.

Return type:	list or None

Graph.add_proxy(proxy_name, element_class, index_class=None)[source]

Adds an element proxy to the Graph object for the element class.

Parameters:	proxy_name (str) – Attribute name to use for the proxy. element_class (Element) – Element class managed by this proxy. index_class (Index) – Index class for Element’s primary index. Defaults to default_index.
Return type:	None

Graph.build_proxy(element_class, index_class=None)[source]

Returns an element proxy built to specifications.

Parameters:	element_class (Element) – Element class managed by this proxy. index_class (Index) – Optional Index class for Element’s primary index. Defaults to default_index.
Return type:	Element proxy

Graph.load_graphml(uri)[source]

Loads a GraphML file into the database and returns the response.

Parameters:	uri (str) – URI of the GraphML file.
Return type:	Response

Graph.get_graphml()[source]

Returns a GraphML file representing the entire database.

Return type:	Response

Graph.warm_cache()[source]

Warms the server cache by loading elements into memory.

Return type:	Response

Graph.clear()[source]

Deletes all the elements in the graph.

Return type:	Response

WARNING

This will delete all your data!

Config¶

class bulbs.config.Config(root_uri, username=None, password=None)[source]

Configuration options for Bulbs.

Parameters:

root_uri (str) – Root URI of the database.
username (str) – Optional username. Defaults to None.
password (str) – Optional password. Defaults to None.

Variables:

root_uri – Root URI of the server.
username – Optional username. Defaults to None.
password – Optional password. Defaults to None.
log_level – Python log level. Defaults to ERROR.
log_handler – Python log handler. Defaults to StreamHandler.
id_var – Name of the element ID variable. Defaults to “eid”.
type_var – Name of the type variable. Defaults to “element_type”.
label_var – Name of the label variable. Defaults to “label”.
type_system – Name of the type system. Defaults to “json”.
vertex_index – Name of the vertex index. Defaults to “vertex”.
edge_index – Name of the edge index. Defaults to “edge”.
autoindex – Enable auto indexing. Defaults to True.
server_scripts – Scripts are defined server side. Defaults to False.

Example:

>>> from bulbs.config import Config, DEBUG
>>> from bulbs.neo4jserver import Graph, NEO4J_URI
>>> config = Config(NEO4J_URI, username="james", password="secret")
>>> config.set_logger(DEBUG)
>>> g = Graph(config)

Config.set_logger(log_level, log_handler=None)[source]

Sets or updates the log level and log handler.

Parameters:	log_level (int) – Python log level. log_handler (logging.Handler) – Python log handler. Defaults to log_handler.
Return type:	None

Config.set_neo4j_heroku(log_level=40, log_handler=None)[source]

Sets credentials if using the Neo4j Heroku Add On.

Parameters:	log_level (int) – Python log level. Defaults to ERROR. log_handler (logging.Handler) – Python log handler. Defaults to log_handler.
Return type:	None

Vertices¶

class bulbs.element.Vertex(client)[source]

A container for a Vertex returned by a client proxy.

Parameters:	client (Client) – The Client object for the database.
Variables:	eid – Element ID. This varname is configurable in Config. _client – Client object. _data – Property data dict returned in Result. _vertices – Vertex proxy object. _edges – Edge proxy object. _initialized – Boolean set to True upon initialization.

Example:

>>> from bulbs.neo4jserver import Graph
>>> g = Graph() # Create a Neo4j Graph object
>>> james = g.vertices.get(3) # Get a vertex from the database
>>> james.age = 34 # Set a database property
>>> james.save() # Save the vertex in the database
>>> james.data() # Get the database property map
>>> friends = james.outV("knows") # Return Vertex generator of friends

classmethod Vertex.get_base_type()[source]

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

Return type:	str

WARNING

Don’t override this.

classmethod Vertex.get_element_key(config)[source]

Returns the element key. Defaults to “vertex”. Override this in Model.

Parameters:	config (Config) – Config object.
Return type:	str

classmethod Vertex.get_index_name(config)[source]

Returns the index name. Defaults to the value of Config.vertex_index.

Parameters:	config (Config) – Config object.
Return type:	str

classmethod Vertex.get_proxy_class()[source]

Returns the proxy class. Defaults to VertexProxy.

Return type:	class

Vertex.outE(label=None, start=None, limit=None)[source]

Returns the outgoing edges.

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

Vertex.inE(label=None, start=None, limit=None)[source]

Returns the incoming edges.

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

Vertex.bothE(label=None, start=None, limit=None)[source]

Returns the incoming and outgoing edges.

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

Vertex.outV(label=None, start=None, limit=None)[source]

Returns the out-adjacent vertices.

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

Vertex.inV(label=None, start=None, limit=None)[source]

Returns the in-adjacent vertices.

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

Vertex.bothV(label=None, start=None, limit=None)[source]

Returns all incoming- and outgoing-adjacent vertices.

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

Vertex.save()[source]

Saves the vertex in the database.

Return type:	Response

Vertex.data()

Returns the element’s property data.

Return type:	dict

Vertex.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

Vertex.map()

Deprecated. Returns the element’s property data.

Return type:	dict

class bulbs.element.VertexProxy(element_class, client)[source]

A proxy for interacting with vertices on the graph database.

Parameters:	element_class (Vertex class) – The element class managed by this proxy instance. client (Client) – The Client object for the database.
Variables:	element_class – Element class. client – Client object. index – The primary index object or None.

Note

The Graph object contains a VertexProxy instance named “vertices”.

Example:

>>> from bulbs.neo4jserver import Graph
>>> g = Graph() # Create Neo4j Graph
>>> james = g.vertices.create(name="James") # Create vertex in DB
>>> g.vertices.update(james.eid, name="James T") # Update properties
>>> james = g.vertices.get(james.eid) # Get vertex (again)
>>> g.vertices.delete(james.eid) # Delete vertex

VertexProxy.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:	Vertex

VertexProxy.get(_id)[source]

Returns the vertex for the given ID.

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

VertexProxy.get_or_create(key, value, _data=None, **kwds)[source]

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

VertexProxy.get_all()[source]

Returns all the vertices in the graph.

Return type:	Vertex generator

VertexProxy.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:	Response

VertexProxy.remove_properties(_id)[source]

Removes all properties from a vertex and returns the response.

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

VertexProxy.delete(_id)[source]

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

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

Edges¶

class bulbs.element.Edge(client)[source]

A container for an Edge returned by a client proxy.

Parameters:	client (Client) – The Client object for the database.
Variables:	eid – Element ID. This varname is configurable in Config. _client – Client object. _data – Property data dict returned in Result. _vertices – Vertex proxy object. _edges – Edge proxy object. _initialized – Boolean set to True upon initialization.

Example:

>>> from bulbs.neo4jserver import Graph
>>> g = Graph() # Create a Neo4j Graph
>>> edge = g.edges.get(8) # Get an edge from DB

>>> label = edge.label() # Return edge label
>>> outV = edge.outV() # Return outgoing vertex
>>> inV = edge.inV() # Return incoming vertex

>>> edge._outV # Return the outgoing vertex ID
>>> edge._inV # Return the incoming vertex ID

>>> edge.weight = 0.5 # Set a property
>>> edge.save() # Save properties in DB
>>> data = edge.data() # Return property data

Edge._outV[source]

Returns the edge’s outgoing (start) vertex ID.

Return type:	int

Edge._inV[source]

Returns the edge’s incoming (end) vertex ID.

Return type:	int

classmethod Edge.get_base_type()[source]

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

Return type:	str

WARNING

Don’t override this.

classmethod Edge.get_element_key(config)[source]

Returns the element key. Defaults to “edge”. Override this in Model.

Return type:	str

classmethod Edge.get_index_name(config)[source]

Returns the index name. Defaults to the value of Config.edge_index.

Return type:	str

classmethod Edge.get_proxy_class()[source]

Returns the proxy class. Defaults to EdgeProxy.

Return type:	class

Edge.outV()[source]

Returns the outgoing (start) Vertex of the edge.

Return type:	Vertex

Edge.inV()[source]

Returns the incoming (end) Vertex of the edge.

Return type:	Vertex

Edge.label()[source]

Returns the edge’s label.

Return type:	str

Edge.save()[source]

Saves the edge in the database.

Return type:	Response

Edge.data()

Returns the element’s property data.

Return type:	dict

Edge.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

Edge.map()

Deprecated. Returns the element’s property data.

Return type:	dict

class bulbs.element.EdgeProxy(element_class, client)[source]

A proxy for interacting with edges on the graph database.

Parameters:	element_class (Edge class) – The element class managed by this proxy instance. client (Client) – The Client object for the database.
Variables:	element_class – Element class client – Client object. index – The primary index object or None.

Note

The Graph object contains an EdgeProxy instance named “edges”.

Example:

>>> from bulbs.neo4jserver import Graph
>>> g = Graph() # Create Neo4j Graph
>>> james = g.vertices.create(name="James") # Create vertex
>>> julie = g.vertices.create(name="Julie") # Create vertex
>>> knows = g.edges.create(james, "knows", julie) # Create edge
>>> knows = g.edges.get(knows.eid) # Get edge (again)
>>> g.edges.update(knows.eid, weight=0.5) # Update properties
>>> g.edges.delete(knows.eid) # Delete edge

EdgeProxy.create(outV, label, inV, _data=None, **kwds)[source]

Creates an edge in the database and returns it.

Parameters:	outV (Vertex or int) – The outgoing vertex. label (str) – The edge’s label. inV (Vertex or int) – The incoming vertex. _data (dict) – Optional property data dict. kwds (dict) – Optional property data keyword pairs.
Return type:	Edge

EdgeProxy.get(_id)[source]

Retrieves an edge from the database and returns it.

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

EdgeProxy.get_all()[source]

Returns all the edges in the graph.

Return type:	Edge generator

EdgeProxy.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:	Response

EdgeProxy.remove_properties(_id)[source]

Removes all properties from a element and returns the response.

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

EdgeProxy.delete(_id)[source]

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

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

Indices¶

class bulbs.base.index.Index(client, result)[source]

Abstract base class for the default index.

Variables:	client – Client object result – Result object.

classmethod Index.get_proxy_class(base_type=None)[source]

Returns the IndexProxy class.

Parameters:	base_type (str) – Index base type, either vertex or edge.
Return type:	class

Index.index_name[source]

Returns the index name.

Return type:	str

Index.index_class[source]

Returns the index class.

Return type:	class

Index.put(_id, key=None, value=None, **pair)[source]

Put an element into the index at key/value and return the Response.

Parameters:	_id (int or str) – The element ID. key (str) – The index key. value (str or int) – The key’s value. pair (name/value pair) – Optional key/value pair. Example: name=”James”
Return type:	Response

Index.update(_id, key=None, value=None, **pair)[source]

Update the element ID for the key and value.

Parameters:	key (str) – The index key. value (str or int) – The key’s value. pair (key/value pair) – Optional key/value pair. Example: name=”James”
Return type:	Response

Index.lookup(key=None, value=None, **pair)[source]

Return all the elements in the index where key equals value.

Parameters:	key (str) – The index key. value (str or int) – The key’s value. pair (key/value pair) – Optional key/value pair. Example: name=”James”
Return type:	Element generator

Index.put_unique(_id, key=None, value=None, **pair)[source]

Put an element into the index at key/value and overwrite it if an element already exists; thus, when you do a lookup on that key/value pair, there will be a max of 1 element returned.

Parameters:	key (str) – The index key. value (str or int) – The key’s value. pair (key/value pair) – Optional key/value pair. Example: name=”James”
Return type:	Resposne

Index.get_unique(key=None, value=None, **pair)[source]

Returns a max of 1 elements in the index matching the key/value pair.

Parameters:	key (str) – The index key. value (str or int) – The key’s value. pair (key/value pair) – Optional key/value pair. Example: name=”James”
Return type:	Element or None

Index.remove(_id, key=None, value=None, **pair)[source]

Remove the element from the index located by key/value.

Parameters:	key (str) – The index key. value (str or int) – The key’s value. pair (key/value pair) – Optional key/value pair. Example: name=”James”
Return type:	Response

Index.count(key=None, value=None, **pair)[source]

Return the number of items in the index for the key and value.

Parameters:	key (str) – The index key. value (str or int) – The key’s value. pair (name/value pair) – Optional key/value pair. Example: name=”James”
Return type:	int

class bulbs.base.index.VertexIndexProxy(index_class, client)[source]

Abstract base class the vertex index proxy.

Variables:	index_class – Index class. client – Client object.

VertexIndexProxy.create(index_name)[source]

Creates an Vertex index and returns it.

Parameters:	index_name (str) – Index name.
Return type:	Index

VertexIndexProxy.get(index_name)[source]

Returns the Index object with the specified name or None if not found.

Parameters:	index_name (str) – Index name.
Return type:	Index

VertexIndexProxy.get_or_create(index_name)[source]

Get a Vertex Index or create it if it doesn’t exist.

Parameters:	index_name (str) – Index name.
Return type:	Index

VertexIndexProxy.delete(index_name)[source]

Deletes an index and returns the Response.

Parameters:	index_name (str) – Index name.
Return type:	Response

class bulbs.base.index.EdgeIndexProxy(index_class, client)[source]

Abstract base class the edge index proxy.

Variables:	index_class – Index class. client – Client object.

EdgeIndexProxy.create(index_name)[source]

Creates an Edge index and returns it.

Parameters:	index_name (str) – Index name.
Return type:	Index

EdgeIndexProxy.get(index_name)[source]

Returns the Index object with the specified name or None if not found.

Parameters:	index_name (str) – Index name.
Return type:	Index

EdgeIndexProxy.get_or_create(index_name)[source]

Get an Edge Index or create it if it doesn’t exist.

Parameters:	index_name (str) – Index name.
Return type:	Index

EdgeIndexProxy.delete(index_name)[source]

Deletes an index and returns the Response.

Parameters:	index_name (str) – Index name.
Return type:	Response

Nodes¶

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")

classmethod Node.get_element_type(config)[source]

Returns the element type.

Parameters:	config (bulbs.config.Config) – Config object.
Return type:	str

classmethod Node.get_element_key(config)[source]

Returns the element key.

Parameters:	config (bulbs.config.Config) – Config object.
Return type:	str

classmethod Node.get_index_name(config)[source]

Returns the index name.

Parameters:	config (bulbs.config.Config) – Config object.
Return type:	str

classmethod Node.get_proxy_class()[source]

Returns the proxy class.

Parameters:	config (bulbs.config.Config) – Config object.
Return type:	class

Node.save()[source]

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

Return type:	None

Node.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

Node.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

Node.data()

Returns a the element’s property data.

Return type:	dict

Node.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 Node.get_base_type()

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

Return type:	str

WARNING

Don’t override this.

Node.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

Node.get_index_keys()

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

Return type:	list or None

Node.get_property_keys()

Returns a list of all the Property keys.

Return type:	list

Node.inE(label=None, start=None, limit=None)

Returns the incoming edges.

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

Node.inV(label=None, start=None, limit=None)

Returns the in-adjacent vertices.

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

Node.map()

Deprecated. Returns the element’s property data.

Return type:	dict

Node.outE(label=None, start=None, limit=None)

Returns the outgoing edges.

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

Node.outV(label=None, start=None, limit=None)

Returns the out-adjacent vertices.

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

class bulbs.model.NodeProxy(element_class, client)[source]

NodeProxy.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

NodeProxy.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

NodeProxy.get_all()[source]

Returns all the elements for the model type.

Return type:	Node generator

NodeProxy.get_property_keys()[source]

Returns a list of all the Property keys.

Return type:	list

NodeProxy.delete(_id)

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

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

NodeProxy.get(_id)

Returns the vertex for the given ID.

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

NodeProxy.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

NodeProxy.remove_properties(_id)

Removes all properties from a vertex and returns the response.

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

Relationships¶

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')

classmethod Relationship.get_label(config)[source]

Returns the edge’s label.

Parameters:	config (bulbs.config.Config) – Config object.
Return type:	str

classmethod Relationship.get_element_key(config)[source]

Returns the element key.

Parameters:	config (bulbs.config.Config) – Config object.
Return type:	str

classmethod Relationship.get_index_name(config)[source]

Returns the index name.

Parameters:	config (bulbs.config.Config) – Config object.
Return type:	str

classmethod Relationship.get_proxy_class()[source]

Returns the proxy class.

Parameters:	config (bulbs.config.Config) – Config object.
Return type:	class

Relationship.save()[source]

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

Return type:	None

Relationship.data()

Returns a the element’s property data.

Return type:	dict

Relationship.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 Relationship.get_base_type()

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

Return type:	str

WARNING

Don’t override this.

Relationship.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

Relationship.get_index_keys()

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

Return type:	list or None

Relationship.get_property_keys()

Returns a list of all the Property keys.

Return type:	list

Relationship.inV()

Returns the incoming (end) Vertex of the edge.

Return type:	Vertex

Relationship.map()

Deprecated. Returns the element’s property data.

Return type:	dict

Relationship.outV()

Returns the outgoing (start) Vertex of the edge.

Return type:	Vertex

class bulbs.model.RelationshipProxy(element_class, client)[source]

RelationshipProxy.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

RelationshipProxy.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

RelationshipProxy.get_all()[source]

Returns all the relationships for the label.

Return type:	Relationship generator

RelationshipProxy.get_property_keys()[source]

Returns a list of all the Property keys.

Return type:	list

RelationshipProxy.delete(_id)

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

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

RelationshipProxy.get(_id)

Retrieves an edge from the database and returns it.

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

RelationshipProxy.remove_properties(_id)

Removes all properties from a element and returns the response.

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

Properties¶

class bulbs.property.String(fget=None, name=None, default=None, nullable=True, unique=False, indexed=False)[source]

Parameters:

fget (str) – Method name that returns a calculated value. Defaults to None.
name (str) – Database property name. Defaults to the Property key.
default (str, int, long, float, list, dict, or Callable) – Default property value. Defaults to None.
nullable (bool) – If True, the Property can be null. Defaults to True.
indexed (bool) – If True, index the Property in the DB. Defaults to False.

Variables:

fget – Name of the method that gets the calculated Property value.
name – Database property name. Defaults to the Property key.
default – Default property value. Defaults to None.
nullable – If True, the Property can be null. Defaults to True.
indexed – If True, index the Property in the DB. Defaults to False.

Note

If no Properties have index=True, all Properties are indexed.

String.python_type

Python type

alias of unicode

String.coerce(key, value)

Coerces a Property value to its Python type.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	object

String.convert_to_db(type_system, key, value)

Converts a Property value from its Python type to its database representation.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

String.convert_to_python(type_system, key, value)

Converts a Property value from its database representation to its Python type.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

String.validate(key, value)

Validates the Property value before saving it to the database.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	None

class bulbs.property.Integer(fget=None, name=None, default=None, nullable=True, unique=False, indexed=False)[source]

Parameters:

fget (str) – Method name that returns a calculated value. Defaults to None.
name (str) – Database property name. Defaults to the Property key.
default (str, int, long, float, list, dict, or Callable) – Default property value. Defaults to None.
nullable (bool) – If True, the Property can be null. Defaults to True.
indexed (bool) – If True, index the Property in the DB. Defaults to False.

Variables:

fget – Name of the method that gets the calculated Property value.
name – Database property name. Defaults to the Property key.
default – Default property value. Defaults to None.
nullable – If True, the Property can be null. Defaults to True.
indexed – If True, index the Property in the DB. Defaults to False.

Note

If no Properties have index=True, all Properties are indexed.

Integer.python_type

Python type

alias of int

Integer.coerce(key, value)

Coerces a Property value to its Python type.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	object

Integer.convert_to_db(type_system, key, value)

Converts a Property value from its Python type to its database representation.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

Integer.convert_to_python(type_system, key, value)

Converts a Property value from its database representation to its Python type.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

Integer.validate(key, value)

Validates the Property value before saving it to the database.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	None

class bulbs.property.Long(fget=None, name=None, default=None, nullable=True, unique=False, indexed=False)[source]

Parameters:

fget (str) – Method name that returns a calculated value. Defaults to None.
name (str) – Database property name. Defaults to the Property key.
default (str, int, long, float, list, dict, or Callable) – Default property value. Defaults to None.
nullable (bool) – If True, the Property can be null. Defaults to True.
indexed (bool) – If True, index the Property in the DB. Defaults to False.

Variables:

fget – Name of the method that gets the calculated Property value.
name – Database property name. Defaults to the Property key.
default – Default property value. Defaults to None.
nullable – If True, the Property can be null. Defaults to True.
indexed – If True, index the Property in the DB. Defaults to False.

Note

If no Properties have index=True, all Properties are indexed.

Long.python_type

Python type

alias of long

Long.coerce(key, value)

Coerces a Property value to its Python type.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	object

Long.convert_to_db(type_system, key, value)

Converts a Property value from its Python type to its database representation.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

Long.convert_to_python(type_system, key, value)

Converts a Property value from its database representation to its Python type.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

Long.validate(key, value)

Validates the Property value before saving it to the database.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	None

class bulbs.property.Float(fget=None, name=None, default=None, nullable=True, unique=False, indexed=False)[source]

Parameters:

fget (str) – Method name that returns a calculated value. Defaults to None.
name (str) – Database property name. Defaults to the Property key.
default (str, int, long, float, list, dict, or Callable) – Default property value. Defaults to None.
nullable (bool) – If True, the Property can be null. Defaults to True.
indexed (bool) – If True, index the Property in the DB. Defaults to False.

Variables:

fget – Name of the method that gets the calculated Property value.
name – Database property name. Defaults to the Property key.
default – Default property value. Defaults to None.
nullable – If True, the Property can be null. Defaults to True.
indexed – If True, index the Property in the DB. Defaults to False.

Note

If no Properties have index=True, all Properties are indexed.

Float.python_type

Python type

alias of float

Float.coerce(key, value)

Coerces a Property value to its Python type.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	object

Float.convert_to_db(type_system, key, value)

Converts a Property value from its Python type to its database representation.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

Float.convert_to_python(type_system, key, value)

Converts a Property value from its database representation to its Python type.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

Float.validate(key, value)

Validates the Property value before saving it to the database.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	None

class bulbs.property.Null(fget=None, name=None, default=None, nullable=True, unique=False, indexed=False)[source]

Parameters:

fget (str) – Method name that returns a calculated value. Defaults to None.
name (str) – Database property name. Defaults to the Property key.
default (str, int, long, float, list, dict, or Callable) – Default property value. Defaults to None.
nullable (bool) – If True, the Property can be null. Defaults to True.
indexed (bool) – If True, index the Property in the DB. Defaults to False.

Variables:

fget – Name of the method that gets the calculated Property value.
name – Database property name. Defaults to the Property key.
default – Default property value. Defaults to None.
nullable – If True, the Property can be null. Defaults to True.
indexed – If True, index the Property in the DB. Defaults to False.

Note

If no Properties have index=True, all Properties are indexed.

Null.python_type = None: Python type

Null.coerce(key, value)

Coerces a Property value to its Python type.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	object

Null.convert_to_db(type_system, key, value)

Converts a Property value from its Python type to its database representation.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

Null.convert_to_python(type_system, key, value)

Converts a Property value from its database representation to its Python type.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

Null.validate(key, value)

Validates the Property value before saving it to the database.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	None

class bulbs.property.List(fget=None, name=None, default=None, nullable=True, unique=False, indexed=False)[source]

Parameters:

fget (str) – Method name that returns a calculated value. Defaults to None.
name (str) – Database property name. Defaults to the Property key.
default (str, int, long, float, list, dict, or Callable) – Default property value. Defaults to None.
nullable (bool) – If True, the Property can be null. Defaults to True.
indexed (bool) – If True, index the Property in the DB. Defaults to False.

Variables:

fget – Name of the method that gets the calculated Property value.
name – Database property name. Defaults to the Property key.
default – Default property value. Defaults to None.
nullable – If True, the Property can be null. Defaults to True.
indexed – If True, index the Property in the DB. Defaults to False.

Note

If no Properties have index=True, all Properties are indexed.

List.python_type

Python type

alias of list

List.coerce(key, value)

Coerces a Property value to its Python type.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	object

List.convert_to_db(type_system, key, value)

Converts a Property value from its Python type to its database representation.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

List.convert_to_python(type_system, key, value)

Converts a Property value from its database representation to its Python type.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

List.validate(key, value)

Validates the Property value before saving it to the database.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	None

class bulbs.property.Dictionary(fget=None, name=None, default=None, nullable=True, unique=False, indexed=False)[source]

Parameters:

fget (str) – Method name that returns a calculated value. Defaults to None.
name (str) – Database property name. Defaults to the Property key.
default (str, int, long, float, list, dict, or Callable) – Default property value. Defaults to None.
nullable (bool) – If True, the Property can be null. Defaults to True.
indexed (bool) – If True, index the Property in the DB. Defaults to False.

Variables:

fget – Name of the method that gets the calculated Property value.
name – Database property name. Defaults to the Property key.
default – Default property value. Defaults to None.
nullable – If True, the Property can be null. Defaults to True.
indexed – If True, index the Property in the DB. Defaults to False.

Note

If no Properties have index=True, all Properties are indexed.

Dictionary.python_type

Python type

alias of dict

Dictionary.coerce(key, value)

Coerces a Property value to its Python type.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	object

Dictionary.convert_to_db(type_system, key, value)

Converts a Property value from its Python type to its database representation.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

Dictionary.convert_to_python(type_system, key, value)

Converts a Property value from its database representation to its Python type.

Parameters:	type_system (TypeSystem) – TypeSystem object. key (str) – Property key. value (object) – Property value.
Return type:	object

Dictionary.validate(key, value)

Validates the Property value before saving it to the database.

Parameters:	key (str) – Property key. value (object) – Property value.
Return type:	None

Gremlin¶

class bulbs.gremlin.Gremlin(client)[source]

An interface for executing Gremlin scripts on the client.

Parameters:	client (Client) – The Client object for the database.

Gremlin.command(script, params=None)[source]

Returns the raw Result object from an arbitrary Gremlin command.

Parameters:	script (str) – Gremlin script to execute on the client. params (dict or None) – Optional paramaters to bind to the Gremlin script.
Return type:	Result

Note

Use this when you are executing a command that returns a single result that does not need to be initialized.

Gremlin.query(script, params=None)[source]

Returns initialized Element objects from an arbitrary Gremlin query.

Parameters:	script (str) – Gremlin script to execute on the client. params (dict or None) – Optional paramaters to bind to the Gremlin script.
Return type:	Generator of objects: Vertex, Edge, Node, or Relationship

Note

Use this when you are returning elements that need to be initialized.

Gremlin.execute(script, params=None)[source]

Returns the raw Response object from an arbitrary Gremlin script.

Parameters:	script (str) – Gremlin script to execute on the client. params (dict or None) – Optional paramaters to bind to the Gremlin script.
Return type:	Response

Note

Use this when you are returning element IDs and the actual elements are cached in Redis or Membase. Or, when you’re returning primitives or Table data.

Client¶

class bulbs.base.client.Client(config=None)[source]

Abstract base class for the low-level server client.

Parameters:	config (bulbs.config.Config) – Optional Config object. Defaults to default Config.
Variables:	default_uri – Default URI for the database. request_class – Request class for the Client. config – Config object. registry – Registry object. type_system – TypeSystem object. request – Request object.

Example:

>>> from bulbs.neo4jserver import Neo4jClient
>>> client = Neo4jClient()
>>> script = client.scripts.get("get_vertices")
>>> response = client.gremlin(script, params=None)
>>> result = response.results.next()

Client.create_vertex(data)[source]

Creates a vertex and returns the Response.

Parameters:	data (dict) – Property data.
Return type:	Response

Client.get_vertex(_id)[source]

Gets the vertex with the _id and returns the Response.

Parameters:	data (int) – Vertex ID.
Return type:	Response

Client.get_all_vertices()[source]

Returns a Response containing all the vertices in the Graph.

Return type:	Response

Client.update_vertex(_id, data)[source]

Updates the vertex with the _id and returns the Response.

Parameters:	_id (dict) – Vertex ID. data (dict) – Property data.
Return type:	Response

Client.delete_vertex(_id)[source]

Deletes a vertex with the _id and returns the Response.

Parameters:	_id (dict) – Vertex ID.
Return type:	Response

Client.create_edge(outV, label, inV, data=None)[source]

Creates a edge and returns the Response.

Parameters:	outV (int) – Outgoing vertex ID. label (str) – Edge label. inV (int) – Incoming vertex ID. data (dict or None) – Property data.
Return type:	Response

Client.get_edge(_id)[source]

Gets the edge with the _id and returns the Response.

Parameters:	data (int) – Edge ID.
Return type:	Response

Client.get_all_edges()[source]

Returns a Response containing all the edges in the Graph.

Return type:	Response

Client.update_edge(_id, data)[source]

Updates the edge with the _id and returns the Response.

Parameters:	_id (dict) – Edge ID. data (dict) – Property data.
Return type:	Response

Client.delete_edge(_id)[source]

Deletes a edge with the _id and returns the Response.

Parameters:	_id (dict) – Edge ID.
Return type:	Response

Client.outE(_id, label=None)[source]

Returns the outgoing edges of the vertex.

Parameters:	_id (dict) – Vertex ID. label (str) – Optional edge label. Defaults to None.
Return type:	Response

Client.inE(_id, label=None)[source]

Returns the incoming edges of the vertex.

Parameters:	_id (dict) – Vertex ID. label (str) – Optional edge label. Defaults to None.
Return type:	Response

Client.bothE(_id, label=None)[source]

Returns the incoming and outgoing edges of the vertex.

Parameters:	_id (dict) – Vertex ID. label (str) – Optional edge label. Defaults to None.
Return type:	Response

Client.outV(_id, label=None)[source]

Returns the out-adjacent vertices of the vertex.

Parameters:	_id (dict) – Vertex ID. label (str) – Optional edge label. Defaults to None.
Return type:	Response

Client.inV(_id, label=None)[source]

Returns the in-adjacent vertices of the vertex.

Parameters:	_id (dict) – Vertex ID. label (str) – Optional edge label. Defaults to None.
Return type:	Response

Client.bothV(_id, label=None)[source]

Returns the incoming- and outgoing-adjacent vertices of the vertex.

Parameters:	_id (dict) – Vertex ID. label (str) – Optional edge label. Defaults to None.
Return type:	Response

Client.create_vertex_index(params)[source]

Creates a vertex index with the specified params.

Parameters:	index_name (str) – Name of the index to create.
Return type:	Response

Client.get_vertex_index(index_name)[source]

Returns the vertex index with the index_name.

Parameters:	index_name (str) – Name of the index.
Return type:	Response

Client.delete_vertex_index(index_name)[source]

Deletes the vertex index with the index_name.

Parameters:	index_name (str) – Name of the index.
Return type:	Response

Client.create_edge_index(index_name)[source]

Creates a edge index with the specified params.

Parameters:	index_name (str) – Name of the index.
Return type:	Response

Client.get_edge_index(index_name)[source]

Returns the edge index with the index_name.

Parameters:	index_name (str) – Name of the index.
Return type:	Response

Client.delete_edge_index(index_name)[source]

Deletes the edge index with the index_name.

Parameters:	index_name (str) – Name of the index.
Return type:	Response

Client.put_vertex(index_name, key, value, _id)[source]

Adds a vertex to the index with the index_name.

Parameters:	index_name (str) – Name of the index. key (str) – Name of the key. value (str) – Value of the key. _id (int) – Vertex ID
Return type:	Response

Client.lookup_vertex(index_name, key, value)[source]

Returns the vertices indexed with the key and value.

Parameters:	index_name (str) – Name of the index. key (str) – Name of the key. value (str) – Value of the key.
Return type:	Response

Client.remove_vertex(index_name, _id, key=None, value=None)[source]

Removes a vertex from the index and returns the Response.

Parameters:	index_name (str) – Name of the index. key (str) – Optional. Name of the key. value (str) – Optional. Value of the key.
Return type:	Response

Client.put_edge(index_name, key, value, _id)[source]

Adds an edge to the index and returns the Response.

Parameters:	index_name (str) – Name of the index. key (str) – Name of the key. value (str) – Value of the key. _id (int) – Edge ID
Return type:	Response

Client.lookup_edge(index_name, key, value)[source]

Looks up an edge in the index and returns the Response.

Parameters:	index_name (str) – Name of the index. key (str) – Name of the key. value (str) – Value of the key.
Return type:	Response

Client.remove_edge(index_name, _id, key=None, value=None)[source]

Removes an edge from the index and returns the Response.

Parameters:	index_name (str) – Name of the index. _id (int) – Edge ID key (str) – Optional. Name of the key. value (str) – Optional. Value of the key.
Return type:	Response

Client.create_indexed_vertex(data, index_name, keys=None)[source]

Creates a vertex, indexes it, and returns the Response.

Parameters:	data (dict) – Property data. index_name (str) – Name of the index. keys (list) – Property keys to index.
Return type:	Response

Client.update_indexed_vertex(_id, data, index_name, keys=None)[source]

Updates an indexed vertex and returns the Response.

Parameters:	index_name (str) – Name of the index. data (dict) – Property data. index_name – Name of the index. keys (list) – Property keys to index.
Return type:	Response

Client.create_indexed_edge(data, index_name, keys=None)[source]

Creates a edge, indexes it, and returns the Response.

Parameters:	outV (int) – Outgoing vertex ID. label (str) – Edge label. inV (int) – Incoming vertex ID. data (dict) – Property data. index_name (str) – Name of the index. keys (list) – Property keys to index. Defaults to None (indexes all properties).
Return type:	Response

Client.update_indexed_edge(_id, data, index_name, keys=None)[source]

Updates an indexed edge and returns the Response.

Parameters:	_id (int) – Edge ID. data (dict) – Property data. index_name (str) – Name of the index. keys (list) – Property keys to index. Defaults to None (indexes all properties).
Return type:	Response

Response¶

class bulbs.base.client.Response(response, config)[source]

Abstract base class for the response returned by the request.

Parameters:	response (Depends on Client.) – The raw response. config (bulbs.config.Config) – Config object.
Variables:	config – Config object. headers – Response headers. content – A dict containing the response content. results – A generator of Neo4jResult objects, a single Neo4jResult object, or None, depending on the number of results returned. total_size – The number of results returned. raw – Raw HTTP response. Only set when log_level is DEBUG.

Response.result_class: alias of Result

Response.handle_response(response)[source]

Check the server response and raise exception if needed.

Parameters:	response (Depends on Client.) – Raw server response.
Return type:	None

Response.get_headers(response)[source]

Returns a dict containing the headers from the response.

Parameters:	response (tuple) – Raw server response.
Return type:	httplib2.Response

Response.get_content(response)[source]

Returns a dict containing the content from the response.

Parameters:	response (tuple) – Raw server response.
Return type:	dict or None

Response.get_results()[source]

Returns the results contained in the response.

Returns:	A tuple containing two items: 1. Either a generator of Neo4jResult objects, a single Neo4jResult object, or None, depending on the number of results returned; 2. An int representing the number results returned.
Return type:	tuple

Response.get(attribute)[source]: Return a client-specific attribute.

Response.one()[source]

Returns one result or raises an error if there is more than one result.

Return type:	Result

Table of Contents

Bulbs API¶

Graph¶

Config¶

Vertices¶

Edges¶

Indices¶

Nodes¶

Relationships¶

Properties¶

Gremlin¶

Client¶

Response¶