Skip to main content

Python Client for Couchbase

Project description

Client for Couchbase.

Building and Installing

This only applies to building from source. If you are using a Windows installer then everything (other than the server) is already included. See below for windows snapshot releases.

Also note that these instructions apply to building from source. You can always get the latest supported release version from pypi.

If you have a recent version of pip, you may use the latest development version by issuing the following incantation

pip install git+git://github.com/couchbase/couchbase-python-client

Prerequisites

Building

The following will compile the module locally; you can then test basic functionality including running the examples.

python setup.py build_ext --inplace

If your libcouchbase install is in an alternate location (for example, /opt/local/libcouchbase), you may add extra directives, like so

python setup.py build_ext --inplace \
    --library-dir /opt/local/libcouchbase/lib \
    --include-dir /opt/local/libcouchbase/include

If you wish to enable the experimental tracing feature, set the PYCBC_TRACING_ENABLE environment variable.

Or you can modify the environment CFLAGS and LDFLAGS variables.

Installing

python setup.py install

Using

Authentication is handled differently depending on what version of Couchbase Server you are using:

Couchbase Server < 5.0

Each bucket can optionally have a password. You may omit the authenticator if you are only working with password-less buckets.

>>> from couchbase.cluster import Cluster, ClassicAuthenticator
>>> cluster = Cluster('couchbase://localhost')
>>> cluster.authenticate(ClassicAuthenticator(buckets={'bucket-name': 'password'}))
>>> bucket = cluster.open_bucket('bucket-name')

Couchbase Server >= 5.0

Role-Based Access Control (RBAC) provides discrete username and passwords for an application that allow fine-grained control. The authenticator is always required.

>>> from couchbase.cluster import Cluster, PasswordAuthenticator
>>> cluster = Cluster('couchbase://localhost')
>>> cluster.authenticate(PasswordAuthenticator('username', 'password'))
>>> bucket = cluster.open_bucket('bucket-name')

Here’s an example code snippet which sets a key and then reads it

>>> bucket.upsert("key", "value")
OperationResult<RC=0x0, Key=key, CAS=0x31c0e3f3fc4b0000>
>>> res = bucket.get("key")
>>> res
ValueResult<RC=0x0, Key=key, Value=u'value', CAS=0x31c0e3f3fc4b0000, Flags=0x0>
>>> res.value
u'value'
>>>

You can also use views

>>> resultset = bucket.query("beer", "brewery_beers", limit=5)
>>> resultset
View<Design=beer, View=brewery_beers, Query=Query:'limit=5', Rows Fetched=0>
>>> for row in resultset: print row.key
...
[u'21st_amendment_brewery_cafe']
[u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-21a_ipa']
[u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-563_stout']
[u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-amendment_pale_ale']
[u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-bitter_american']

Twisted API

The Python client now has support for the Twisted async network framework. To use with Twisted, simply import txcouchbase.connection instead of couchbase.bucket

from twisted.internet import reactor
from txcouchbase.bucket import Bucket

cb = Bucket('couchbase://localhost/default')
def on_upsert(ret):
    print "Set key. Result", ret

def on_get(ret):
    print "Got key. Result", ret
    reactor.stop()

cb.upsert("key", "value").addCallback(on_upsert)
cb.get("key").addCallback(on_get)
reactor.run()

# Output:
# Set key. Result OperationResult<RC=0x0, Key=key, CAS=0x9a78cf56c08c0500>
# Got key. Result ValueResult<RC=0x0, Key=key, Value=u'value', CAS=0x9a78cf56c08c0500, Flags=0x0>

The txcouchbase API is identical to the couchbase API, except that where the synchronous API will block until it receives a result, the async API will return a Deferred which will be called later with the result or an appropriate error.

GEvent API

from gcouchbase.bucket import Bucket

conn = Bucket('couchbase://localhost/default')
print conn.upsert("foo", "bar")
print conn.get("foo")

The API functions exactly like the normal Bucket API, except that the implementation is significantly different.

Asynchronous (Tulip) API

This module also supports Python 3.4/3.5 asynchronous I/O. To use this functionality, import the couchbase.experimental module (since this functionality is considered experimental) and then import the acouchbase module. The acouchbase module offers an API similar to the synchronous client:

import asyncio

import couchbase.experimental
couchbase.experimental.enable()
from acouchbase.bucket import Bucket


async def write_and_read(key, value):
    cb = Bucket('couchbase://10.0.0.31/default')
    await cb.connect()
    await cb.upsert(key, value)
    return await cb.get(key)

loop = asyncio.get_event_loop()
rv = loop.run_until_complete(write_and_read('foo', 'bar'))
print(rv.value)

PyPy

PyPy is an alternative high performance Python implementation. Since PyPy does not work well with C extension modules, this module will not work directly. You may refer to the alternate implementation based on the cffi module: https://github.com/couchbaselabs/couchbase-python-cffi

Other Examples

There are other examples in the examples directory. To run them from the source tree, do something like

PYTHONPATH=$PWD ./examples/bench.py -U couchbase://localhost/default

Building documentation

The documentation is using Sphinx and also needs the numpydoc Sphinx extension. In order for the documentation to build properly, the C extension must have been built, since there are embedded docstrings in there as well.

To build the documentation, go into the docs directory and run

make html

The HTML output can be found in docs/build/html/.

Alternatively, you can also build the documentation (after building the module itself) from the top-level directory:

python setup.py build_sphinx

Once built, the docs will be in in build/sphinx/html

Testing

For running the tests, you need the standard unittest module, shipped with Python. Additionally, the testresources package is required.

To run them, use either py.test, unittest or trial.

The tests need a running Couchbase instance. For this, a tests.ini file must be present, containing various connection parameters. An example of this file may be found in tests.ini.sample. You may copy this file to tests.ini and modify the values as needed.

The simplest way to run the tests is to declare a bucket_prefix in the tests.ini file and run the setup_tests.py script to create them for you.

python setup_tests.py

To run the tests:

nosetests

Support & Additional Resources

If you found an issue, please file it in our JIRA. You can ask questions in our forums or in the #libcouchbase channel on freenode.

The official documentation can be consulted as well for general Couchbase concepts and offers a more didactic approach to using the SDK.

License

The Couchbase Python SDK is licensed under the Apache License 2.0.

Project details


Release history Release notifications | RSS feed

This version

2.5.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

couchbase-2.5.1.tar.gz (379.8 kB view details)

Uploaded Source

Built Distributions

couchbase-2.5.1.win-amd64-py3.4.exe (852.5 kB view details)

Uploaded Source

couchbase-2.5.1.win-amd64-py3.3.exe (849.8 kB view details)

Uploaded Source

couchbase-2.5.1.win32-py3.4.exe (761.6 kB view details)

Uploaded Source

couchbase-2.5.1.win32-py3.3.exe (759.0 kB view details)

Uploaded Source

couchbase-2.5.1-cp37-cp37m-win_amd64.whl (652.2 kB view details)

Uploaded CPython 3.7mWindows x86-64

couchbase-2.5.1-cp37-cp37m-win32.whl (573.8 kB view details)

Uploaded CPython 3.7mWindows x86

couchbase-2.5.1-cp34-cp34m-win_amd64.whl (626.0 kB view details)

Uploaded CPython 3.4mWindows x86-64

couchbase-2.5.1-cp33-cp33m-win_amd64.whl (623.5 kB view details)

Uploaded CPython 3.3mWindows x86-64

File details

Details for the file couchbase-2.5.1.tar.gz.

File metadata

  • Download URL: couchbase-2.5.1.tar.gz
  • Upload date:
  • Size: 379.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.1.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/2.7.13

File hashes

Hashes for couchbase-2.5.1.tar.gz
Algorithm Hash digest
SHA256 5ab325e13edabe41f4841b6e28a62b8166d1488e8415c5d01b0df55401aa4e1f
MD5 79ab70ad7282dc1df689cb0d38ebc36f
BLAKE2b-256 fae61f9d7ea4333a155f8cab2dd907571839d7bc980d1f914878b2f948e580d4

See more details on using hashes here.

File details

Details for the file couchbase-2.5.1.win-amd64-py3.4.exe.

File metadata

  • Download URL: couchbase-2.5.1.win-amd64-py3.4.exe
  • Upload date:
  • Size: 852.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.1.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/2.7.13

File hashes

Hashes for couchbase-2.5.1.win-amd64-py3.4.exe
Algorithm Hash digest
SHA256 bfb473ec193117231d8d2f7a06c27bf56e8c0d45cab8ed7533243abcbedd07ef
MD5 bbceb8c7fdc525052316236c92e16b67
BLAKE2b-256 946a3b2d49f21d6d1b11c6a1d92372e1cbefe0fdb1aed8546c6ef91f6488a18e

See more details on using hashes here.

File details

Details for the file couchbase-2.5.1.win-amd64-py3.3.exe.

File metadata

  • Download URL: couchbase-2.5.1.win-amd64-py3.3.exe
  • Upload date:
  • Size: 849.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.1.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/2.7.13

File hashes

Hashes for couchbase-2.5.1.win-amd64-py3.3.exe
Algorithm Hash digest
SHA256 5a5c2c9045656239afe9564b3e599c49f10d16125756591f4a09addbd2254064
MD5 1a611f13910c58d82dd18f1a02c71886
BLAKE2b-256 31573438021860456a886505702c0639cb0bc524f0423a6418fd6b4a2d5b1cc8

See more details on using hashes here.

File details

Details for the file couchbase-2.5.1.win32-py3.4.exe.

File metadata

  • Download URL: couchbase-2.5.1.win32-py3.4.exe
  • Upload date:
  • Size: 761.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.1.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/2.7.13

File hashes

Hashes for couchbase-2.5.1.win32-py3.4.exe
Algorithm Hash digest
SHA256 7075644afd92e3db323152dc41e93090647caa5cbdf3aaa619d231c2ecd15e45
MD5 3b14a406560ea61bc0310f6bc77167e2
BLAKE2b-256 84ec5287fdf9026ee2a9229b1b95a7afbbacb9ed1b1db0bc4c0f0ab6c1af5f28

See more details on using hashes here.

File details

Details for the file couchbase-2.5.1.win32-py3.3.exe.

File metadata

  • Download URL: couchbase-2.5.1.win32-py3.3.exe
  • Upload date:
  • Size: 759.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.1.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/2.7.13

File hashes

Hashes for couchbase-2.5.1.win32-py3.3.exe
Algorithm Hash digest
SHA256 6ab8bfa62c43ce8cfa2bb923edeb182fbbe85a1b56a6a0bfe7f8906b3eeb736f
MD5 e091c171587160ddc97fdf39f75a2a95
BLAKE2b-256 3e1a4e236a93f72dc8bd2249c730cd170b274feeff80b0313b06d6bfaf94886e

See more details on using hashes here.

File details

Details for the file couchbase-2.5.1-cp37-cp37m-win_amd64.whl.

File metadata

  • Download URL: couchbase-2.5.1-cp37-cp37m-win_amd64.whl
  • Upload date:
  • Size: 652.2 kB
  • Tags: CPython 3.7m, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/38.4.0 requests-toolbelt/0.8.0 tqdm/4.27.0 CPython/3.6.2

File hashes

Hashes for couchbase-2.5.1-cp37-cp37m-win_amd64.whl
Algorithm Hash digest
SHA256 cc185d1b3d5ab6d88c79f6b57698b1574db20b1a38f09f115d21af7de88f4d1d
MD5 fa775a008e994cc51ebe9945ff214434
BLAKE2b-256 be3bec871512908bffd4dc9593db8bcf416bb70b46231a1c2d9a48c0017506b4

See more details on using hashes here.

File details

Details for the file couchbase-2.5.1-cp37-cp37m-win32.whl.

File metadata

  • Download URL: couchbase-2.5.1-cp37-cp37m-win32.whl
  • Upload date:
  • Size: 573.8 kB
  • Tags: CPython 3.7m, Windows x86
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/38.4.0 requests-toolbelt/0.8.0 tqdm/4.27.0 CPython/3.6.2

File hashes

Hashes for couchbase-2.5.1-cp37-cp37m-win32.whl
Algorithm Hash digest
SHA256 6323da8274dac81802bddcf6b0bbf45709263e10a7cf9c0c4afbc1be0d4bb21e
MD5 8458ea5415d677555858c9f935a814b0
BLAKE2b-256 330a3a2629ebc9b22622d342718e815b4cd0cacc7b2475a54cabb92de02c6811

See more details on using hashes here.

File details

Details for the file couchbase-2.5.1-cp34-cp34m-win_amd64.whl.

File metadata

  • Download URL: couchbase-2.5.1-cp34-cp34m-win_amd64.whl
  • Upload date:
  • Size: 626.0 kB
  • Tags: CPython 3.4m, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.1.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/2.7.13

File hashes

Hashes for couchbase-2.5.1-cp34-cp34m-win_amd64.whl
Algorithm Hash digest
SHA256 230e806578eff18027fc6c427bd0e10e2d5da423cb9a21bf4ba59b7f8ad0024b
MD5 297aff55a02256df9fd33df25945e546
BLAKE2b-256 a3e06f86b900c8b6f87520daedfa9e9252b0965b4d2e377af97d8200300b6308

See more details on using hashes here.

File details

Details for the file couchbase-2.5.1-cp33-cp33m-win_amd64.whl.

File metadata

  • Download URL: couchbase-2.5.1-cp33-cp33m-win_amd64.whl
  • Upload date:
  • Size: 623.5 kB
  • Tags: CPython 3.3m, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.1.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/2.7.13

File hashes

Hashes for couchbase-2.5.1-cp33-cp33m-win_amd64.whl
Algorithm Hash digest
SHA256 e6f52dbfb4fc52a76fc5ebeb48c1adc2a7ee6c43bcd3a24f5c49a5781fdfedef
MD5 98b01a588b608c1dfda1cb3b4639aa68
BLAKE2b-256 0c0b4c045e099d60ca84cc909714d66c8ede37c10eef342e1fb7d00e794d1395

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page