Published on

Published in: Technology
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide


  1. 1. python-graph-lovestory Documentation Release 0.99 Amirouche Boubekki April 21, 2013
  2. 2. CONTENTS 1 Walkthrough 3 1.1 Blueprints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 i
  3. 3. ii
  4. 4. 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
  5. 5. python-graph-lovestory Documentation, Release 0.99 2 CONTENTS
  6. 6. 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:// 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
  7. 7. 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 method nor, 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, 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
  8. 8. 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
  9. 9. 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
  10. 10. 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
  11. 11. 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
  12. 12. 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
  13. 13. 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
  14. 14. 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
  15. 15. 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