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