EXPERIMENTAL Python Bindings For Couchbase Lite

September 2021

This directory contains a Python API binding of Couchbase Lite, an embedded NoSQL document database engine with sync. It consists of Python classes that call glue generated by CFFI, which calls into Couchbase Lite's C API.

Here's a snippet of code to show what the Python API looks like:

from CouchbaseLite.Database import Database, DatabaseConfiguration
from CouchbaseLite.Document import MutableDocument

# Open a database:
db = Database("python_db", DatabaseConfiguration("/tmp"));

# Create a document:
doc = MutableDocument("foo")
doc["greeting"] = "Howdy!"
db.saveDocument(doc)

# Read it back:
readDoc = db.getDocument("foo")
props = readDoc.properties
greeting = props["greeting"]

Disclaimer

This library is NOT SUPPORTED BY COUCHBASE. Even if you are a Couchbase customer, our otherwise awesome support team cannot help you with using this library.

As of September 2021, this library is still incomplete and has been tested only partially and informally, mostly on one platform (macOS). Due to the dynamic nature of Python, there are probably glaring mistakes that won't show up until we get more code coverage.

That said, we would like to maintain and improve this library as time permits. We welcome bug reports, fixes and improvements!

Building

"Some assembly required..."

1. Python and CFFI

You'll need Python 3. Currently we've only tested with 3.9.

Make sure you have the CFFI package:

$ pip3 install cffi

2. Couchbase Lite For C

Next you need the Couchbase Lite For C shared library and headers. You can download them from Couchbase, or build them yourself from the Git repo.

3. Building CBL-Python

Now you can build the Python binding library. If Couchbase Lite has been installed into ``/usr/local`, you can just type:

$ cd couchbase-lite-python
$ ./build.sh

Otherwise, you'll need to tell the script where to find the native headers and library file:

$ cd couchbase-lite-python
$ ./build.sh --include /path/to/include/ --library /path/to/libcblite.dylib

/path/to/include/ must have a subdirectory named cbl containing the CBL headers.

(If this doesn't work, adding the --verbose flag may reveal more information from CFFI.)

4. Try it out

Now try the (rudimentary) tests:

$ test/test.sh

Hopefully this prints a bunch of stuff and exits normally without any exceptions.

You can look at the test code in test/test.py for examples of how to use the API.

The main thing you need to do is add the CouchbaseLite package directory to your Python path, for example by setting the PYTHONPATH environment variable to its parent directory, as the shell script does. Then import the packages CouchbaseLite.Database, CouchbaseLite.Document, etc.

Learning

If you're not already familiar with Couchbase Lite, you'll want to start by reading through its official documentation. Our goal is for the Python API to be compatible with the languages documented there.