This document provides documentation on the python-graph-lovestory library for working with graph databases in Python. It includes an overview of the Blueprints API, which allows using different graph databases with the same API, and examples of creating a graph and modeling a wiki with pages and revisions. It also demonstrates how to create vertices, edges, indexes and navigate the graph.

1. python-graph-lovestory Documentation
Release 0.99
Amirouche Boubekki
April 21, 2013

3. CONTENTS
1 Walkthrough 3
1.1 Blueprints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
i

4. ii

5. python-graph-lovestory Documentation, Release 0.99
Here you will find documentation about the component of my python graph lovestory, I hope you like it because I do.
CONTENTS 1

6. python-graph-lovestory Documentation, Release 0.99
2 CONTENTS

7. CHAPTER
ONE
WALKTHROUGH
There’s no direct to the matter of «Developping Web application using graph databases» tutorial instead you read the
following subject in order which introduce each library part of the stack each of which deal with specific matters and
as such complexities are introduced along way you discover the stack, so that you know all the good parts but also all
the bad parts before you start.
1.1 Blueprints
1.1.1 Kesako ?
Blueprints allows to use several graph database with the same API. It can be used to embed a graph database in your
Python program. If several process need to access the same database it’s not what you need. python-blueprints are
pyjnius powered bindings of Tinkerpop’s Java Blueprints.
1.1.2 Installation
There is no binary package for now so you may have some difficulties installing python-blueprints on Windows and
MacOS machines, but it’s possible.
Follow the cli dance:
mkvirtualenv --system-site-packages coolprojectname
pip install cython git+git://github.com/kivy/pyjnius.git blueprints
You are ready for some graph database awesomeness in Python.
1.1.3 Getting started with core API
The python-blueprints API is straightforward it’s basicly the Blueprints API in Python, if you know Neo4j’s python-
embedded the API is similar but not the same.
Create a graph
Creating a graph is just matter of knowing where to store the files and the backend you want to use, currently only
Neo4j and OrienDB are supported.
For the purpose of the tutorial, we will use /tmp/ as storage directory.
Using Neo4j:
3

8. python-graph-lovestory Documentation, Release 0.99
from printemps.core import Graph
graph = Graph(’neo4j’, ’/tmp/’)
Getting OrientDB running is very similar:
from printemps.core import Graph
graph = Graph(’orientdb’, ’local:/tmp/’)
A Wiki model
The following is exactly the same for both OrientDB and Neo4j. In order to make easier for everybody to under-
stand how graphs works, we will model a wiki, while we introduce the base API of any graph databases used with
printemps.core.
A wiki will be a set of pages which have several revisions.
Create and modify edge and vertex
To create a vertex just call Graph.create_vertex() method inside a transaction:
with graph.transaction():
wiki = graph.create_vertex()
There is no Vertex.save() method nor Edge.save(), the elements are automatically persisted if the transaction
succeed.
If you want to know the identifier of the wiki in the database to store it somewhere or learn it by hearth, you can use
Vertex.id(), Edge.id() does the same for edges.
Both vertex and edge work like a dictionary, you can set and get properties, they are persisted if you do it inside a
transaction, I don’t know what happens outside transactions. Let’s give a name and description to our wiki vertex:
with graph.transaction():
wiki[’title’] = ’Printemps Wiki’
wiki[’description’] = ’My first graph based wiki’
Keys are always strings, values can be:
• strings
• integers
• list of strings
• list of integers
We will see later how it can be done, it’s very natural for Python programmers.
Now we will create a page, a page will be vertex too:
with graph.transaction():
frontpage = graph.create_vertex()
frontpage[’title’] = ’Welcome to Printemps Wiki’
The page needs to be linked to wiki as a part of, for that matter there is a method Graph.create_edge(start,
label, end) than can be used like this:
4 Chapter 1. Walkthrough

9. python-graph-lovestory Documentation, Release 0.99
with graph.transaction():
partof = graph.edge(wiki, ’part of’, frontpage)
An edge has three important methods, that do actually nothing but return the value we are interested in, but since those
are not editable, you access them through methods:
• Edge.start() returns the vertex where the edge is starting, in the case of partof it’s wiki vertex
• Edge.end() returns the vertex where the edge is ending, in the case of partof it’s frontpage vertex
• Edge.label() returns the label of the edge, in the case of partof it’s the string ’part of’
In general, every object you think of is a vertex, but some times some «objects» are modeled as edges, those are links.
An object representing a link between two objects is an edge. If the link object involves more that two edges, then it
can be represented as an hyperedge.
Note: this is advanced topic you can skip it.
The idea behind the hyperedge is that a vertex can be linked to several other vertex using only one special edge the hy-
peredge, which means the edge starts with one vertex, and ends with several vertex. Here is an example representation
of an hyperedge:
1.1. Blueprints 5

10. python-graph-lovestory Documentation, Release 0.99
This can be modeled in a graph using only vertices and simple edges with an intermediate vertex which serves as a
hub for serveral edges that will link to the end vertices of the hyperedge. Here is the pattern illustrated:
6 Chapter 1. Walkthrough

11. python-graph-lovestory Documentation, Release 0.99
Hyperedges are not part of popular graphdbs as is, so you have to use the intermediate vertex pattern.
To sum up, link objects with more that two objects involved in the link are the exception among link objects and are
represented as vertex.
Navigation
Stay away with your motors, sails and emergency fire lighters, it’s just plain Python even though you can do it in boat
too, but this is not my issue at the present moment.
Before advancing any further, let’s sum up, we have a graph with two vertices, and one edge, it can be represented as
follow:
1.1. Blueprints 7

12. python-graph-lovestory Documentation, Release 0.99
Because we like the wiki so much we know its identifier by hearth and stored it in a variable named
wiki_identifier, we can retrieve the wiki vertex like so:
wiki = graph.vertex(wiki_identifier)
Vertices have two kinds of edges:
• Vertex.incomings(): a generator yielding edges that ends at this vertex, currently there is none on wiki
• Vertex.outgoings(): a generator yielding edges that starts at this vertex, currently there is only one.
To retrieve the frontpage we can use next function of wiki.outgoings() to rertrieve the first and only edge as
first hop and navigate to the index using Edge.end() as second hop:
link = next(wiki.outgoings())
frontpage = link.end()
We got back our frontpage vertex back, Ulysse himself wouldn’t believe it, it’s not the same object though.
More vertices and more edges
What we have right now is only a wiki with a page and its title, but there is no content and no revisions. For that matter
we will use more edges and more vertex. Before the actual code which re-use all the above we will have a look at what
we are going to build:
8 Chapter 1. Walkthrough

13. python-graph-lovestory Documentation, Release 0.99
This is one of the normalized graph that can be used to represent the wiki, every graph structure that solve this problem
has its strengths, this happens, I think, to be the simplest.
First let’s create a function that create a revision for a given page given a body text, if you followed the whole tutorial it
should be easy to understand, and even if you happen to be here by mistake, I think it semantically expressive enough
to be understood by any Python programmer:
def create_revision(graph, page, body):
with graph.transaction():
max_revision = 0
for link in page.outgoings()
max_revision = max(link[’revision’], max_revision)
new_revision = max_revision + 1
# create the vertex first
revision = graph.vertex()
revision[’body’] = body
# link the edge and annotate it
link = graph.edge(page, ’revised as’, revision)
link[’revision’] = new_revision
create_revision does the following:
1.1. Blueprints 9

14. python-graph-lovestory Documentation, Release 0.99
1. Look for the highest revision in edges linked to page
2. Increment the revision number for the new page
3. Create the new revision
4. Link it to page with the proper revision property on the link vertex
A basic wiki would only need to fetch the last revision that’s what we do in the following fetch_last_revision
function:
def fetch_last_revision(graph, page):
max_revision = None
for link in page.outgoings()
new_revision = max(link[’revision’], max_revision)
if new_revision != max_revision:
max_revision = link.end()
return max_revision # if it returns None, the page is empty
That is all! Creating a page is very similar to this, so I won’t repeat the same code... Oh! I almost forgot about the list
of strings as property, the following function will add the tags passed as arguments which must be a list of strings, as
tags property of the last revision:
def add_tags(graph, page, *tags):
rev = fetch_last_revision(graph, page)
rev[’tags’] = tags
The basics are straightforward. Getting links working between pages is left as an exercices to the reader.
Index
GraphDBs have index, to create an index of vertex use the following code:
pages = graph.index.create(’pages’, graph.VERTEX)
To create an index of edges do this:
revisions = graph.index.create(’revisions’, graph.EDGE)
Then you can put vertex in an index using put(key, value, element):
pages.put(’page’, ’page’, page)
key and value parameters are not really interesting in the above example but an index can be that simple. You can
use key and value to have a fine-grained index of related elements, for instances, the following snipped builds an
index for revisions, properly separating minor, major revisions and sorting them by date of revisions:
revisions.put(’all’, ’today’, r2)
revisions.put(’all’, ’yesterday’, r1)
revisions.put(’all’, ’before’, r0)
revisions.put(’minor’, ’today’, r2)
revisions.put(’major’, ’yesterday’, r1)
revisions.put(’all’, ’before’, r0)
You can use Graph.index.get(name) to retrieve an index:
index = graph.index.get(’pages’)
To retrieve an index content, use Index.get, like this:
10 Chapter 1. Walkthrough

15. python-graph-lovestory Documentation, Release 0.99
index = index.get(’pages’, ’pages’)
first_page = next(index)
That’s almost all the index API, for more please refer to the API documentation.
End
When you finished working with the database don’t forget to call Graph.close().
More
If you still struggle with the API here is it with more comments:
• from blueprints import Graph
– Graph(name, path) remember that name is lower case of the databases names and the path for Ori-
entDB is prepended with local:.
– Graph.transaction() is a contextmanager, thus used with with statement that starts a transaction,
elements are automatically saved and you must always do mutating operations in transaction.
– Graph.create_vertex() create a vertex in a transaction.
– Graph.create_edge(start, label, end) create an edge in a transaction starting at start
vertex, ending at end vertex with label as label. The tutorial doesn’t say much about labels, so I add
here that it’s a way to know which edge is which when they are several edges starting and ending at the
same vertices.
– Graph.vertex(id) and Graph.edge(id) the former retrieve the vertex with id as identifier and
the latter the edge.
– Graph.close() clean up your database after you finished work.
– Graph.edges() and Graph.vertices() were not presented because they IMO should not be used
outside debug in an application where speed matters.
• An element is a vertex or an edge, they both are usable as dict to get and set values but can only be mutated in a
transaction. Every element can be deleted with delete() method in a transaction.
• Vertex you don’t import Vertex class, you get it from Graph.vertex() or graph.get_vertex(id)
or hoping through Edge.end() or Edge.starts.
– Vertex.outgoings() is a generator over the edges that are starting from the current vertex, each edge
retrieved implied a hop.
– Vertex.incomings() is a generator over the edges that are ending in the current vertex, each edge
retrieved implied a hop.
• Edge similarly are not imported, they are created with Graph.edge(start, label, end)
retrieved with Graph.get_vertice(id) and via iteration of Vertex.outgoings() and
Vertex.incomings() generators.
– Vertex.start() retrieve starting vertex via a hop
– Vertex.end() retrieve ending vertex via a hop
– Vertex.label() retrieve the label associated with the edge.
• Similarly you don’t import the Index class, but create one using Graph.index.create(name,
ELEMENT) where ELEMENT should be one of Graph.EDGE or Graph.VERTEX or retrieve the index by
its name using Graph.index.get(name).
1.1. Blueprints 11

16. python-graph-lovestory Documentation, Release 0.99
– Index.put(key, value, element put element in the key, value namespace.
– Index.get(key, vallue) to retrieve the index content, this is a generator over the index content.
hops are a metric used to compute the complexity of a query.
1.1.4 Moar doc
blueprints Package
blueprints Package
edge Module
element Module
graph Module
index Module
java Module
vertex Module
Subpackages
12 Chapter 1. Walkthrough