You are viewing the documentation for a prerelease version.

View Latest

Install and Start Using the Python SDK with Couchbase Server

The Couchbase Python SDK allows Python applications to access a Couchbase cluster. The Python SDK offers a traditional synchronous API as well as integration with twisted, gevent, and asyncio. It depends on the C SDK, libcouchbase, which it uses for performance and reliability.

These pages cover the Alpha of the Couchbase Python SDK. As such they are likely to change without notice. This alpha code should not be used in production.

Documentation is incomplete, subject to change, and likely to contain broken links.

Couchbase Python SDK bundles libcouchbase automatically, so no need to install it separately. You may need cmake to install, although the installer will attempt to download it from PyPI automatically.

The Python SDK 3.0 requires Python 3, with Python 3.5 and above supported. It should work on Python 2.7, but is not officially supported.

Installing on Linux

Debian and Ubuntu
# Only needed during first-time setup:
sudo apt-get install build-essential python3-dev python3-pip
sudo pip3 install --pre couchbase-3.0.0a4
RHEL and CentOS
# Only needed during first-time setup:
sudo yum install gcc gcc-c++ python-devel python-pip
sudo pip install --pre couchbase-3.0.0a4
RHEL/CentOS distributions may not provide the python-pip package in the base repositories. It may be found in the EPEL repository.

Installation on Mac OS X

To install the library on Mac OS X, first install the de-facto package manager for OS X: Homebrew. Once Homebrew is configured:

brew update # get list of latest packages
brew install python
pip install --pre couchbase-3.0.0a4
The above example uses the Python supplied by Homebrew and not the vendor-supplied Python which ships with OS X. The Python SDK will still work with the vendor-supplied Python (though pip install may be a privileged command), but it is recommended to use Homebrew’s Python instead.

Installing on Microsoft Windows

pip install --pre couchbase-3.0.0a4

Hello Couchbase

The code snippet below shows how the Python SDK may be used for some common operations.

from couchbase.cluster import Cluster, ClusterOptions
from couchbase_core.cluster import PasswordAuthenticator

cluster = Cluster('couchbase://localhost', ClusterOptions(PasswordAuthenticator('username', 'password')))
cb = cluster.bucket('bucket-name')
cb_coll = cb.default_collection()
cb_coll.upsert('u:king_arthur',
               {'name': 'Arthur', 'email': 'kingarthur@couchbase.com', 'interests': ['Holy Grail', 'African Swallows']})
# OperationResult<RC=0x0, Key=u'u:king_arthur', CAS=0xb1da029b0000>

print(cb_coll.get('u:king_arthur').content_as[str])
# {u'interests': [u'Holy Grail', u'African Swallows'], u'name': u'Arthur', u'email': u'kingarthur@couchbase.com'}

## The CREATE PRIMARY INDEX step is only needed the first time you run this script
cluster.query('CREATE PRIMARY INDEX ON bucket-name')

from couchbase_core.n1ql import N1QLQuery
row_iter = cluster.query(N1QLQuery('SELECT name FROM bucket-name WHERE ' + \
                                   '$1 IN interests', 'African Swallows'))
for row in row_iter: print(row)
# {u'name': u'Arthur'}

Connecting

To connect to a Couchbase bucket, you must use Couchbase Role-Based Access Control (RBAC). This is fully described in the section Authorization. An authenticator, containing username and password, should be defined, and then passed to the cluster. Following successful authentication, the bucket can be opened:

from couchbase.cluster import Cluster, ClusterOptions
from couchbase_core.cluster import PasswordAuthenticator
cluster = Cluster('couchbase://localhost', ClusterOptions(PasswordAuthenticator('username', 'password')))
bucket = cluster.bucket('bucket-name')
coll = bucket.default_collection()

Once defined, the authenticator can be passed to other clusters, as appropriate.

See howtos:managing-connections.adoc for more connection options and details about the connection string.

Document Operations

Document operations, such as storing and retrieving documents, can be done using simple methods on the Bucket class such as Bucket.get and Bucket.upsert. Simply pass the key (and value, if applicable) to the relevant methods.

rv = coll.get('document-id')
print(rv.content)
coll.upsert('document-id', {'application': 'data'})

N1QL Queries

Couchbase N1QL queries are performed by creating a N1QLQuery object and passing that to the Bucket.n1ql_query() method:

from couchbase_core.n1ql import N1QLQuery
query = N1QLQuery("""SELECT airportname, city, country FROM `travel-sample` """
                  """WHERE type="airport" AND city=$my_city""", my_city="Reno")
for row in cluster.query(query):
    print(row)

Additional Resources

The API reference is generated for each release and can be found linked from the relnotes-python-sdk.adoc. Most of the API documentation can also be accessed via pydoc.

Couchbase welcomes community contributions to the Java SDK. The Python SDK source code is available on GitHub.

Information on new features, fixes, known issues as well as information on how to install older release versions is in the release notes.

PyPy support

Because the Python SDK is written primarily in C using the CPython API, the official SDK will not work on PyPy.

An unofficial module, couchbase_ffi uses ffi rather than the CPython C API to implement the internals of the library, and may be used with PyPy.