flatty.couch - the couchdb adapter

This module helps you to build schemas for couchdb (it uses the couchdb-python module for storing the flattened dicts as couchdb documents)

This module has less than 20 lines of python code. If you want to support another marshaller, look at this modules source code, this should give you a good start.

Simple Example

>>> import flatty
>>> import couchdb
>>> from datetime import datetime

We use the db ‘flatty_couchdb_test’ and create it if it doesn’t exist

>>> dbname = 'flatty_couchdb_test'
>>> server = couchdb.Server('http://localhost:5984/')
>>>
>>> if dbname not in server:
...     db = server.create(dbname)
... else:
...     db = server[dbname]
>>>

Here comes the actual flatty code. This example is intentionally similar to the example for the couchdb-python mapper (http://packages.python.org/CouchDB/mapping.html) because we want to show the differences.

To define a flatable class in a couchdb you must inherit from the flatty.couch.Document. You can simply add fields and define their types.

>>> class Person(flatty.couch.Document):
...     name = str
...     age = int
...     added = datetime
...
...     def __init__(self, **kwargs):
...             super(Person,self).__init__(**kwargs)
...             self.added = datetime.now()
...
>>>
>>> person = Person(name='John Doe', age=42)
>>> person.store(db)   
('...', '...')
>>> old_rev = person._rev
>>> person = Person.load(db, person._id)
>>> person.name
'John Doe'
>>> person.added 
datetime.datetime(...)

To update the document call the store method.

>>> person.name = 'John R. Doe'
>>> person.store(db) 
('...', '...')

After retrieving the document from the db once again we will also get the updated values.

>>> person = Person.load(db, person._id)
>>> person.name
'John R. Doe'
>>> person._rev != old_rev
True
>>>

A more complex example

>>> from datetime import date
>>> import flatty
>>> import couchdb

We use the db ‘flatty_couchdb_test’ and create it if it doesn’t exist

>>> dbname = 'flatty_couchdb_test'
>>> server = couchdb.Server('http://localhost:5984/')
>>>
... if dbname not in server:
...     db = server.create(dbname)
... else:
...     db = server[dbname]

We define the schema

>>> class Comment(flatty.Schema):
...     user = str
...     txt = str
...
>>> class Book(flatty.Schema):
...     name = str
...     year = date
...     comments = flatty.TypedList.set_type(Comment)
...
>>> class Address(flatty.Schema):
...     street = str
...     city = str
...
>>> class Library(flatty.couch.Document):
...     name = str
...     address = Address
...     books = flatty.TypedDict.set_type(Book)

The important things we want to show in this schema definition are:

• only the class wich acts as couchdb document need to be subclassed

  from flatty.couch.Document all others are subclassed from `flatty.Schema

• Schema classes can be cascaded easily either direct (like Address) or

  with flatty.TypedDict and flatty.TypedList.

Now we can create objects and store it to the db

>>> library = Library(name='IT Library')
>>> library.address = Address(street='Baker Street 221b', city='London')
>>> book1 = Book(name='Dive Into Python',
...              year = date(2008,10,10))
>>> book2 = Book(name='Programming Python',
...              year = date(2011,1,31))
>>> book2.comments = []
>>> book2.comments.append(Comment(user='Alex', txt='good Book'))
>>> library.books={}
>>> library.books['978-1590593561'] = book1
>>> library.books['978-0596158101'] = book2
>>> id, rev = library.store(db)

When we load the the library object from the db again, the whole class structure is restored.

>>> library = Library.load(db, library._id)
>>> isinstance(library.address, Address)
True
>>> isinstance(library.books['978-0596158101'].comments[0], Comment)
True

Classes

class flatty.couch.Document(**kwargs)

This class is the base Class for alls couchdb documents

classmethod load(db, id)

loads the document from couchdb

Args:

db: should must be a couchdb-python ‘’Database’’ object

id: the document id of the couchdb document

Returns:

returns the object

store(db)

stores the document in the couchdb

Args:

db: should must be a couchdb-python ‘’Database’’ object

Returns:

returns a tuple id, rev. id is the document id which stays the same over time. rev changes on every store.