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"]

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!

"Some assembly required..."

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

Make sure you have the CFFI package:

$ pip3 install cffi

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.

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.)

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.

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.