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
Couchbase Server (http://couchbase.com/download)
libcouchbase. version 2.6.0 or greater (Bundled in Windows installer)
libcouchbase development files.
Python development files
A C compiler.
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
Or you can modify the environment CFLAGS and LDFLAGS variables.
Installing
python setup.py install
Using
Here’s an example code snippet which sets a key and then reads it
>>> from couchbase.bucket import Bucket
>>> c = Bucket('couchbase://localhost/default')
>>> c
<couchbase.bucket.Bucket bucket=default, nodes=['localhost:8091'] at 0x105991cd0>
>>> c.upsert("key", "value")
OperationResult<RC=0x0, Key=key, CAS=0x31c0e3f3fc4b0000>
>>> res = c.get("key")
>>> res
ValueResult<RC=0x0, Key=key, Value=u'value', CAS=0x31c0e3f3fc4b0000, Flags=0x0>
>>> res.value
u'value'
>>>
You can also use views
>>> from couchbase.bucket import Bucket
>>> c = Bucket('couchbase://localhost/beer-sample')
>>> resultset = c.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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for couchbase-2.2.3.win-amd64-py3.4.exe
Algorithm | Hash digest | |
---|---|---|
SHA256 | befafbde20e1d56e1652eda2ccc863f06036b26b5ba93a53cb2bcd04acae3d17 |
|
MD5 | c8a11fc8f8a647861f67ec5d0aeead42 |
|
BLAKE2b-256 | 3122a07bdc5363a8258cb5fe68c2fb064f4883c0ee3abc7a9459f4f5829a1e36 |
Hashes for couchbase-2.2.3.win-amd64-py3.3.exe
Algorithm | Hash digest | |
---|---|---|
SHA256 | 59728b1638759ca228e12d7b4c452a506d7c425f9397c12b8a4d20cd38bc6c2d |
|
MD5 | d2e11e8dda1a619db792288d0987f43a |
|
BLAKE2b-256 | 16e9ae1a04d926a0b974f20902eba59c7ff9f712530bdaab6e0988f3e41e190a |
Hashes for couchbase-2.2.3.win-amd64-py3.2.exe
Algorithm | Hash digest | |
---|---|---|
SHA256 | fec10b764773e7e0c3dc7ef764c072034b9cd64efe9741d0f69acee0bcb5ce75 |
|
MD5 | 444efca13fdecd53768c52f6d6cad768 |
|
BLAKE2b-256 | bccc0aaf5f77ecf96db50c326864d05455499eb7f2a6b4820a4ff21ee86b773e |
Hashes for couchbase-2.2.3.win-amd64-py2.7.exe
Algorithm | Hash digest | |
---|---|---|
SHA256 | fc12f03cebb5610fd23cdef7fbb83804f8099f822238f44fe55cc46aaea5be10 |
|
MD5 | a2116f147d8d375bc46e4224de614171 |
|
BLAKE2b-256 | 80ac02bfe4df3848edfab41e960973e265e61e3ebfb6b9bd51d0554a8d328f10 |