Recently, there have been a few new versions of the Couchbase Python client available. It features a new API that is easier to use. As the SDK is now based on libcouchbase, it is also much faster. It’s also compatible with Python 3 now too!

Brief history

A rewrite was necessary as the Python SDK has a long history. It originated in a Python script Dustin Sallings wrote, which was then used by the quality engineering team at Couchbase to write their tests.  There were a lot of great capabilites, but it wasn’t a cohesive API for a new developer.

Later on it was carried forward by Benjamin Young to the next level to be the official Couchbase Python client. It still had the burden of being backwards compatible and hence couldn’t be as easy to use as many anticipated.

With the decision to do a rewrite and base it on libcouchbase in 0.9 using Cython, we also decided to break the API. This way you’ll get the best performance, but also a nice API.  Later, we moved to the Python C API directly in 0.10.

What does it look like

The new API is heavily inspired by the one of the Ruby client.

    import couchbase

# Connect to localhost on port 8091 by default
client = Couchbase.connect(username=‘beer-sample’, password=,

beer = client.get(‘aass_brewery-juleol’)
print(“{0}, ABV: {1}”.format(beer[‘name’, beer[‘abv’])

beer[‘comment’] = “Random beer from Norway”
client.replace(‘aass_brewery-juleol’, beer)

Get the client

Currently you need to build the module yourself, though that’s as easy as running as single command. Please install libcouchbase first, the instructions can be found on Couchbase page. Then get the couchbase python package:

shell> pip install couchbase

And finally build it:

shell> python build

If you have libcouchbase installed at a custom path you need to set the environment variables LD_LIBRARY_PATH, CFLAGS and LDFLAGS accordingly.

Future directions

The client isn’t feature complete yet, for example the support for views is still evolving and the API will change a bit. Filling those gaps will be the next steps. If you’d like to help out or have a need for a not supported feature, please get in touch with us.

Contributions can range from fixing typos or making the installation process in the documentation clearer to implementing missing features.

Instructions on how to contribute can be found in the couchbase-python-client repository on Github.

Get in touch with us

If you’ve any questions, just want to say hello or want to start to contribute, there are several ways to get in touch with us. Either join the Couchbase developer discussion or meet us in the #libcouchbase IRC channel on Freenode.


Posted by Volker Mische, Software Engineer, Couchbase

Volker Mische is a Software Engineer, Couchbase. He is in the view-engine team working mostly in Erlang, C/C++ to improve the geospatial & mapreduce indexing.

One Comment

  1. is there a twistedmatrix client ?

Leave a reply