Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/couchbaselabs/couchbase-lite-python

Experimental Python bindings for Couchbase Lite
https://github.com/couchbaselabs/couchbase-lite-python

database embedded json nosql python

Last synced: about 16 hours ago
JSON representation

Experimental Python bindings for Couchbase Lite

Awesome Lists containing this project

README 

        
# EXPERIMENTAL Python Bindings For Couchbase Lite



September 2021



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



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



```python

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][CBL_C].



### 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][CBLDOCS]. Our goal is for the Python API to be compatible with the languages documented there.



[CBL]: https://www.couchbase.com/products/lite

[CBL_C]: https://github.com/couchbaselabs/couchbase-lite-C

[CFFI]: https://cffi.readthedocs.io/en/latest/index.html

[CBLDOCS]: https://docs.couchbase.com/couchbase-lite/current/introduction.html