skip to navigation
skip to content

Not Logged In

corduroy 0.9.0

An asynchronous CouchDB client library

About

Corduroy provides a python-friendly wrapper around CouchDB’s HTTP-based API. Behind the scenes it hooks into the asynchronous i/o routines from your choice of Tornado or the Requests & Gevent modules.

Using corduroy you can query the database without blocking your server’s event loop, making it ideal for CouchApp micro-middleware or scripted batch operations.

Usage

As a real world(ish) example of working with Corduroy, consider this pair of Tornado event handlers which update a url-specifed document then query a view. The first uses explicit callbacks to resume execution after each response from the database is received:

db = Database('players')
class RankingsUpdater(tornado.web.RequestHandler):
    @tornado.web.asynchronous
    def post(self, player_id):
        self.new_score = int(self.request.body)
        db.get(player_id, callback=self.got_player)

    def got_player(doc, status):
        doc.score = self.new_score
        db.save(doc, callback=self.saved_player)

    def saved_player(conflicts, status):
        db.view('leaderboard/highscores',
                 callback=self.got_highscores)

    def got_highscores(rows, status):
        self.write(json.dumps(rows))
        self.finish()

An alternative syntax is available (when using Tornado) through the use of the @relax decorator. Instead of defining callbacks for each database operation, the library can be called as part of a yield expression.

Tornado’s generator module will intercept these yields and provide a callback automatically. The result is code that looks quite sequential but will still execute asyncronously:

class RankingsUpdater(tornado.web.RequestHandler):
    @relax
    def post(self, player_id):
        # update this player's score
        doc = yield db.get(player_id)
        doc.score = int(self.request.body)
        yield db.save(doc)

        # return the new rankings
        highscores = yield db.view('leaderboard/highscores')
        self.write(json.dumps(highscores))
        self.finish()

For a gentle introduction to Corduroy (and CouchDB in general), take a look at the Guide. Documentation for all of Corduroy’s module-level classes can be found in the Reference section.

Installation

Automatic Installation

Corduroy can be found on PyPi and can be installed with your choice of pip or easy_install.

Manual Installation

Download corduroy-0.9.0.tar.gz:

tar xvzf corduroy-0.9.0.tar.gz
cd corduroy-0.9.0
python setup.py install

Dependencies

If you’re writing a Tornado app, Corduroy can use its pure-python HTTP client by installing with:

pip install corduroy tornado

Or if you’d prefer the libcurl-based client (which supports pooling and other niceties), use:

pip install corduroy tornado pycurl

If pycurl complains (I’m looking at you, OS X), try:

env ARCHFLAGS="-arch x86_64" pip install pycurl

Gevent users can install with:

pip install corduroy requests gevent

The library can also be used with plain-old blocking i/o:

pip install corduroy requests

License

Corduroy is released under the BSD license. Use it freely and in good health.

Acknowledgments

Corduroy is derived from Christopher Lenz’s excellent couchdb-python module and inherits much of its API (and most of its test cases) from that codebase. It is also indebted to Eric Naeseth’s mind-expanding Swirl library which first acquainted me with the idea of using generators to simulate sequential code.

 
File Type Py Version Uploaded on Size
corduroy-0.9.0.tar.gz (md5) Source 2012-04-03 289KB
  • Downloads (All Versions):
  • 57 downloads in the last day
  • 156 downloads in the last week
  • 278 downloads in the last month
  • Author: Christian Swinehart
  • Home Page: http://samizdat.cc/corduroy
  • License:
    Copyright (C) 2012 Samizdat Drafting Co.
    All rights reserved.
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
    
     1. Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.
     2. Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in
        the documentation and/or other materials provided with the
        distribution.
     3. The name of the author may not be used to endorse or promote
        products derived from this software without specific prior
        written permission.
    
    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
    OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
    GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
    IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
    IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • Categories
  • Package Index Owner: samizdat
  • DOAP record: corduroy-0.9.0.xml