Couchbase Python client library (official)

Mark Nunberg f7c05fb36d PYCBC-310: remove 'experimental' from n1ql and geo 3 years ago
acouchbase 568c1fcd1c Asyncio fixes 4 years ago
couchbase c1efb994de PYCBC-308: Add tests to check for behavior when now rows are returned 3 years ago
docs f7c05fb36d PYCBC-310: remove 'experimental' from n1ql and geo 3 years ago
examples 5a94fc0666 Add 'docloader' example 4 years ago
gcouchbase d28435c92d N1QL Async API 4 years ago
src 1b7427c0c8 Reactor conversion encoding functions 3 years ago
txcouchbase c1efb994de PYCBC-308: Add tests to check for behavior when now rows are returned 3 years ago
.ci_script.sh 5fc477f58d Run tests with Travis CI 5 years ago
.gitignore f8dabbdd70 Move tests as subpackages 5 years ago
.tests.ini.travis bb456307a7 Upgrade to new mock 4 years ago
.travis.yml 54729fa3b9 Don't do -std=c89 -pedantic on travis builds 4 years ago
CONTRIBUTING.md 215332230f fix typo in contribution guide 5 years ago
LICENSE 0184b33852 Adding Apache License 2.0 6 years ago
MANIFEST.in 93c966321f Add __version__ (and generate it if necessary) 5 years ago
README.rst 88f5054015 Readme fixes 4 years ago
couchbase_version.py d336b7ea29 Modify version generation to conform with PEP-440 4 years ago
dev_requirements.txt 7c41f39a69 Move previous requirements.txt to dev_requirements 3 years ago
requirements.txt 7c41f39a69 Move previous requirements.txt to dev_requirements 3 years ago
setup.py 019fa16258 rename: connection, arithmetic C files... 3 years ago
tests.ini.sample bb456307a7 Upgrade to new mock 4 years ago

README.rst

=======================
Couchbase Python Client
=======================

Client for Couchbase_.

.. image:: https://travis-ci.org/couchbase/couchbase-python-client.png
:target: https://travis-ci.org/couchbase/couchbase-python-client


.. note::

This is the documentation for the 2.x version of the client. This is
mostly compatible with the older version. Please refer to the
*release12* 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

.. code-block:: sh

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

~~~~~~~~~~~~~
Prerequisites
~~~~~~~~~~~~~

- Couchbase Server (http://couchbase.com/download)
- libcouchbase_. version 2.4.7 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.

.. code-block:: sh

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

.. code-block:: sh

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
^^^^^^^^^^
.. code-block:: sh

python setup.py install

-----
Using
-----

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

.. code-block:: pycon

>>> from couchbase.bucket import Bucket
>>> c = Bucket('couchbase://localhost/default')
>>> c

>>> c.upsert("key", "value")
OperationResult
>>> res = c.get("key")
>>> res
ValueResult
>>> res.value
u'value'
>>>

You can also use views

.. code-block:: pycon

>>> from couchbase.bucket import Bucket
>>> c = Bucket('couchbase://localhost/beer-sample')
>>> resultset = c.query("beer", "brewery_beers", limit=5)
>>> resultset
View
>>> 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``

.. code-block:: python

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
# Got key. Result ValueResult


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
~~~~~~~~~~

.. code-block:: python

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.


~~~~
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

.. code-block:: sh

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

----------------------
Building documentation
----------------------


The documentation is using Sphinx and also needs the numpydoc Sphinx extension.
To build the documentation, go into the `docs` directory and run

.. code-block:: sh

make html

The HTML output can be found in `docs/build/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.

.. code-block:: sh

python setup_tests.py

To run the tests::

nosetests

-------
Support
-------

If you found an issue, please file it in our JIRA_. You may also ask in the
`#libcouchbase` IRC channel at freenode_. (which is where the author(s)
of this module may be found).

-------
License
-------

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

.. _Couchbase: http://couchbase.com
.. _libcouchbase: http://couchbase.com/develop/c/current
.. _JIRA: http://couchbase.com/issues/browse/pycbc
.. _freenode: http://freenode.net/irc_servers.shtml
.. _pypi: http://pypy.python.org/pypi/couchbase