graphstore is the python module at the heart of braindump, but can be used independently from the web application. It takes care of storing the triples (the graph) and page descriptions in the SQLite database (which is just a file).

The basic unit of the graph is the page. Each page has metadata, which is a set of key/value pairs, and a textual description.

Install/Download

svn co http://brain-dump.googlecode.com/svn/trunk/graphstore/

Documentation

Graph Class

The only class you'll need.

__init__(database_path)

database_path is the relative path to the SQLite database file. If one isn't there, it'll be automatically created.

import graphstore

g = graphstore.Graph('path/to/graph.db')

create_schema()

Creates the necessary database tables. If you're starting with a blank file, you have to do this before trying to store anything.

g.create_schema()

list([criteria])

List all of the pages in the graph, alphebetized.

g.list() # => []
g.set('apple','color','red')
g.list() # => [u'apple', u'color', u'red']
g.set('me','favorite food','apple')
g.list() # => [u'apple', u'color', u'favorite food', u'me', u'red']

criteria is a string which allows you to filter the pages list with criteria based on metadata:

g.list('color is red') # => [u'apple']

The syntax is pretty simple: "attribute is value" (not case sensitive), separated by as many 'and's and 'or's as you want:

'color is red'
'color is red or color is yellow'
'color is red and type is fruit'

This will expand soon to include parenthesized conditions and more comparison operators, including fuzzy matches, regular expressions, greater than/less than, and perhaps more advanced stuff like before/after, north/south/east/west of, and within x miles of... We'll see.

You can check the number of pages in the graph two ways:

len(g.list())
len(g)

You can also iterate through the graph object:

for page in g:
  print page

get(pagename[, attribute])

Retreive metadata about a page. If you don't specify attribute, it returns a dict of page metadata:

print g.get('apple') # => {u'color': u'red', u'tastiness': u'high'}

If you do specify an attribute, it returns a string:

print g.get('apple','color') # => u'red'

Multiple values for one attribute are grouped together into lists and their keys are pluralized:

print g.get('grocery list') # => {u'items': [u'milk', u'bread']}
print g.get('grocery list','items') # => [u'milk', u'bread']

set(pagename, attribute, value)

value can be a string or list:

g.set('apple','color','red')
g.set('grocery list','items',['milk','bread'])

You can also supply a dict of attribute/value pairs for the second parameter and not supply a third:

g.set('grocery list',{'items': ['milk','bread'],'status': 'completed'})

If a set statement involves pages that don't exist, they'll be created. That includes values supplied attribute -- g.set('apple','color','red') will create a page called 'color' to which metadata and a description can be added, just like any other page.

unset(pagename[, attribute])

Unsets attribute of pagename if attribute it supplied; otherwise unsets all of pagename's metadata.

g.set('apple',{'color': 'red', 'tastiness': 'high'})
g.unset('apple','tastiness')
print g.get('apple') # => {u'color': u'red'}
g.unset('apple')
print g.get('apple') # => {}

backlinks(pagename)

Returns triples that pagename is on the receiving end of -- in other words, incoming arcs to that node on the graph.

g.set('apple','color','red')
g.backlinks('red') # => {u'color': u'apple'} it's the color of apple

between(page1, page2)

Returns the relationship between page1 and page2:

g.set('apple','color','red')
g.between('apple','red') # => 'color'

infer_types(pagename)

Infers what pagename is based on backlinks to it:

g.set('apple','color','red')
g.infer_types('red') # => [u'color']

g.set('Sarah','father','Jim')
g.set('Sally','husband','Jim')
g.set('Jim Sr.','son','Jim')

g.backlinks('Jim') # => {u'father': u'Sarah', u'son': u'Jim Sr.', u'husband': u'Sally'}

g.infer_types('Jim') # => [u'father', u'husband', u'son']

Literally, the implementation is this:

def infer_types(self, page):
  return self.backlinks(page).keys()

describe(pagename[, description])

If you supply description it sets the description of pagename to description; if you don't, it returns the description of pagename.

g.describe('apple','eat to keep doctor away')
g.describe('apple') # => u'eat to keep doctor away'

rename(pagename, newname)

Pretty self-explanatory. All triples involving pagename will be up to date with the new name.