Skip to content
Couchbase Python Client Library (Official)
Python C CMake C++ Shell
Branch: master
Clone or download
griels PYCBC-668: Add management package to installer
Change-Id: If9334effc15a9359b690e24ef7446808ccacb483
Reviewed-on: http://review.couchbase.org/116280
Tested-by: Ellis Breen <ellis.breen@couchbase.com>
Reviewed-by: Mike Goldsmith <goldsmith.mike@gmail.com>
Tested-by: Build Bot <build@couchbase.com>
Latest commit e2ebae9 Oct 11, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
acouchbase PYCBC-616: Asyncio for SDK3 Aug 27, 2019
cmake/json-cmake PYCBC-546: Automatically build and link libcouchbase using CMake May 17, 2019
couchbase PYCBC-665: Add create user management API Oct 11, 2019
couchbase_core PYCBC-665: Add create user management API Oct 11, 2019
couchbase_tests PYCBC-665: Add create user management API Oct 11, 2019
couchbase_v2 PYCBC-664: Add bucket management API Oct 9, 2019
docs PYCBC-665: Add create user management API Oct 11, 2019
examples PYCBC-616: Asyncio for SDK3 Aug 27, 2019
gcouchbase PYCBC-638: scope and collection methods should be marked as "uncommit… Sep 10, 2019
jenkins PYCBC-601: Rework build system to use correct RPATH when using distutils Jul 4, 2019
src
txcouchbase PYCBC-638: scope and collection methods should be marked as "uncommit… Sep 10, 2019
.gitignore
.tests.ini.travis
.travis.yml PYCBC-540, PYCBC-541: Relocate packages in preparation for V3 Jun 6, 2019
CMakeLists.txt
CONTRIBUTING.md fix typo in contribution guide Sep 27, 2013
LICENSE Adding Apache License 2.0 Mar 22, 2013
MANIFEST.in PYCBC-592: Fix manifest to include extra files for distribution Jun 18, 2019
README.rst PYCBC-616: Asyncio for SDK3 Aug 27, 2019
cbuild_cfg.json PYCBC-644, PYCBC-652, PYCBC-654: Refactor for LCB 3.0.0-alpha.6 Sep 16, 2019
cbuild_config.py PYCBC-660: Refactor for LCB Beta 1 Oct 3, 2019
cmake_build.py PYCBC-609: Fix RPATHs for non-cmake build Jul 11, 2019
cmodule.py PYCBC-601: Rework build system to use correct RPATH when using distutils Jul 4, 2019
couchbase_version.py PYCBC-540: Add provision for Alpha tagging Jun 14, 2019
dev_requirements.txt PYCBC-663: Rerun intermittently failing touch test Oct 4, 2019
lcb_version.py PYCBC-558: Better document lcb dependencies Feb 5, 2019
pyproject.toml PYCBC-546: Automatically build and link libcouchbase using CMake May 17, 2019
requirements.txt PYCBC-596: Make CBCollection proxy entire Bucket object. Jul 3, 2019
setup.py PYCBC-668: Add management package to installer Oct 11, 2019
tests.ini.sample PYCBC-535: Fix 'object from __aiter__ that does not implement __anext__' Nov 6, 2018
unittest.cfg PYCBC-562, PYCBC-564: Move to LCB V4 API Jun 6, 2019

README.rst

Couchbase Python Client

Client for Couchbase.

Note

This is the documentation for the 3.x version of the client. This is mostly compatible with the older version. Please refer to the release25 branch for the older version.

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

  • Couchbase Server (http://couchbase.com/download)
  • You may need a C compiler and Python development files, unless a binary wheel is available for your platform. These are available for at least Python 3.7 on Windows, but we will endeavour to add more.
  • Git, if a binary wheel is not available.

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 you have a libcouchbase install already (in, for example, /opt/local/libcouchbase), you may build using it by setting PYCBC_BUILD=DISTUTILS and some add extra directives, like so:

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

Or you can modify the environment CFLAGS and LDFLAGS variables.

Warning

If you do not intend to install this module, ensure you set the PYTHONPATH environment variable to this directory before running any scripts depending on it. Failing to do so may result in your script running against an older version of this module (if installed), or throwing an exception stating that the couchbase module could not be found.

Installing

pip 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
>>> from couchbase_core.cluster import ClassicAuthenticator
>>> cluster = Cluster('couchbase://localhost')
>>> cluster.authenticate(ClassicAuthenticator(buckets={'bucket-name': 'password'}))
>>> bucket = cluster.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
>>> from couchbase_core.cluster import PasswordAuthenticator
>>> cluster = Cluster('couchbase://localhost')
>>> cluster.authenticate(PasswordAuthenticator('username', 'password'))
>>> bucket = cluster.bucket('bucket-name')
>>> collection = bucket.default_collection()

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

>>> collection.upsert("key", "value")
>>> res = collection.get("key")
>>> res.content
u'value'
>>>

You can also use views

>>> resultset = cluster.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']

Warning

The async APIs below are from SDK2 and currently only available from the couchbase_v2 legacy support package. They will be updated to support SDK3 shortly. See PYCBC-590.*

Twisted API

NOTE: this API is from SDK2 and is currently only supports SDK2-style access. It will be updated to support SDK3 shortly.

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

NOTE: this API is from SDK2 and is currently only supports SDK2-style access. It will be updated to support SDK3 shortly.

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')
    cb_coll = cb.default_collection()
    await cb_coll.connect()
    await cb_coll.upsert(key, value)
    return await cb_coll.get(key)

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

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.

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.

You can’t perform that action at this time.