Name Date Size

..22-Jun-20214 KiB

.gitignoreH A D11-Feb-2020438

.tests.ini.travisH A D11-Feb-2020675

.travis.ymlH A D11-Feb-2020873

acouchbase/H11-Feb-20204 KiB

cbuild_cfg.jsonH A D11-Feb-2020990

cbuild_config.pyH A D11-Feb-202013.8 KiB

cmake/json-cmake/H11-Feb-20204 KiB

cmake_build.pyH A D11-Feb-20208.7 KiB

CMakeLists.txtH A D11-Feb-202012.9 KiB

cmodule.pyH A D11-Feb-20201.5 KiB

CONTRIBUTING.mdH A D11-Feb-20202.9 KiB

couchbase/H11-Feb-20204 KiB

couchbase_core/H11-Feb-20204 KiB

couchbase_tests/H11-Feb-20204 KiB

couchbase_v2/H11-Feb-20204 KiB

couchbase_version.pyH A D11-Feb-20205 KiB

dev_requirements.txtH A D11-Feb-2020556

docs/H11-Feb-20204 KiB

examples/H11-Feb-20204 KiB

gcouchbase/H11-Feb-20204 KiB

jenkins/H11-Feb-20204 KiB

lcb_version.pyH A D11-Feb-20201.2 KiB

LICENSEH A D11-Feb-202010.6 KiB

MANIFEST.inH A D11-Feb-2020381

pyproject.tomlH A D11-Feb-202084

README.rstH A D11-Feb-202010.2 KiB

requirements.txtH A D11-Feb-2020354

setup.pyH A D11-Feb-20203.8 KiB

src/H11-Feb-20204 KiB

tests.ini.sampleH A D11-Feb-2020792

txcouchbase/H11-Feb-20204 KiB

unittest.cfgH A D11-Feb-202045

README.rst

1=======================
2Couchbase Python Client
3=======================
4
5Client for Couchbase_.
6
7.. note::
8
9    This is the documentation for the 3.x version of the client. This is
10    mostly compatible with the older version. Please refer to the
11    *release25* branch for the older version.
12
13-----------------------
14Building and Installing
15-----------------------
16
17This only applies to building from source. If you are using a Windows
18installer then everything (other than the server) is already included.
19See below for windows snapshot releases.
20
21Also note that these instructions apply to building from source.
22You can always get the latest supported release version from pypi_.
23
24
25If you have a recent version of *pip*, you may use the latest development
26version by issuing the following incantation
27
28.. code-block:: sh
29
30    pip install git+git://github.com/couchbase/couchbase-python-client
31
32~~~~~~~~~~~~~
33Prerequisites
34~~~~~~~~~~~~~
35
36- Couchbase Server (http://couchbase.com/download)
37- You may need a C compiler and Python development files, unless a
38  binary wheel is available for your platform. These are available for
39  at least Python 3.7 on Windows, but we will endeavour to add more.
40- Git, if a binary wheel is not available.
41
42~~~~~~~~
43Building
44~~~~~~~~
45You will need a few tools installed to be able to build locally. A compiler
46and CMake (2.8.9 or above), to compile the C extensions that communicate with
47libcouchbase, git, pip and python's setuptools.
48
49Linux (example is for debian-like linux):
50
51.. code-block:: sh
52
53    sudo apt install git-all
54    sudo apt install python3-dev
55    sudo apt install python3-pip
56    sudo apt install python3-setuptools
57    sudo apt install cmake
58    sudo apt install build-essential
59
60MacOSX:
61
62.. code-block:: sh
63
64    # mac (I'm assuming you use homebrew)
65    git --version # this will prompt you to install if not already installed
66    brew install cmake
67    xcode-select --install
68    pip3 install setuptools
69
70
71The following will compile the module locally; you can then test basic
72functionality including running the examples.
73
74.. code-block:: sh
75
76    python setup.py build_ext --inplace
77
78
79If you have a libcouchbase install already (in, for example,
80`/opt/local/libcouchbase`), you may build using it by setting PYCBC_BUILD=DISTUTILS
81and some add extra directives, like so:
82
83.. code-block:: sh
84
85    export PYCBC_BUILD=DISTUTILS
86    python setup.py build_ext --inplace \
87        --library-dir /opt/local/libcouchbase/lib \
88        --include-dir /opt/local/libcouchbase/include
89
90Or you can modify the environment ``CFLAGS`` and ``LDFLAGS`` variables.
91
92
93.. warning::
94
95    If you do not intend to install this module, ensure you set the
96    ``PYTHONPATH`` environment variable to this directory before running
97    any scripts depending on it. Failing to do so may result in your script
98    running against an older version of this module (if installed), or
99    throwing an exception stating that the ``couchbase`` module could not
100    be found.
101
102^^^^^^^^^^
103Installing
104^^^^^^^^^^
105.. code-block:: sh
106
107    pip install .
108
109.. warning::
110
111    If you are on *macOS x* you may need to remove the build directory:
112    `rm -rf ./build` before installing with pip: `pip3 install .`.
113
114
115-----
116Using
117-----
118
119Authentication is handled differently depending on what version of Couchbase Server
120you are using:
121
122~~~~~~~~~~~~~~~~~~~~~~
123Couchbase Server < 5.0
124~~~~~~~~~~~~~~~~~~~~~~
125Each bucket can optionally have a password. You may omit the authenticator if you
126are only working with password-less buckets.
127
128.. code-block:: pycon
129
130    >>> from couchbase.cluster import Cluster
131    >>> from couchbase_core.cluster import ClassicAuthenticator
132    >>> cluster = Cluster('couchbase://localhost')
133    >>> cluster.authenticate(ClassicAuthenticator(buckets={'bucket-name': 'password'}))
134    >>> bucket = cluster.bucket('bucket-name')
135
136~~~~~~~~~~~~~~~~~~~~~~~
137Couchbase Server >= 5.0
138~~~~~~~~~~~~~~~~~~~~~~~
139Role-Based Access Control (RBAC) provides discrete username and passwords for an
140application that allow fine-grained control. The authenticator is always required.
141
142.. code-block:: pycon
143
144    >>> from couchbase.cluster import Cluster
145    >>> from couchbase_core.cluster import PasswordAuthenticator
146    >>> cluster = Cluster('couchbase://localhost')
147    >>> cluster.authenticate(PasswordAuthenticator('username', 'password'))
148    >>> bucket = cluster.bucket('bucket-name')
149    >>> collection = bucket.default_collection()
150
151Here's an example code snippet which sets a key and then reads it
152
153.. code-block:: pycon
154
155    >>> collection.upsert("key", "value")
156    >>> res = collection.get("key")
157    >>> res.content
158    u'value'
159    >>>
160
161You can also use views
162
163.. code-block:: pycon
164
165    >>> resultset = cluster.query("beer", "brewery_beers", limit=5)
166    >>> resultset
167    View<Design=beer, View=brewery_beers, Query=Query:'limit=5', Rows Fetched=0>
168    >>> for row in resultset: print row.key
169    ...
170    [u'21st_amendment_brewery_cafe']
171    [u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-21a_ipa']
172    [u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-563_stout']
173    [u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-amendment_pale_ale']
174    [u'21st_amendment_brewery_cafe', u'21st_amendment_brewery_cafe-bitter_american']
175
176
177.. _PYCBC-590: https://issues.couchbase.com/browse/PYCBC-590
178
179.. warning::
180    The async APIs below are from SDK2 and currently only available
181    from the couchbase_v2 legacy support package. They will
182    be updated to support SDK3 shortly. See PYCBC-590_.*
183
184~~~~~~~~~~~
185Twisted API
186~~~~~~~~~~~
187
188*NOTE: this API is from SDK2 and is currently only supports SDK2-style
189access. It will be updated to support SDK3 shortly.*
190
191The Python client now has support for the Twisted async network framework.
192To use with Twisted, simply import ``txcouchbase.connection`` instead of
193``couchbase.bucket``
194
195.. code-block:: python
196
197    from twisted.internet import reactor
198    from txcouchbase.bucket import Bucket
199
200    cb = Bucket('couchbase://localhost/default')
201    def on_upsert(ret):
202        print "Set key. Result", ret
203
204    def on_get(ret):
205        print "Got key. Result", ret
206        reactor.stop()
207
208    cb.upsert("key", "value").addCallback(on_upsert)
209    cb.get("key").addCallback(on_get)
210    reactor.run()
211
212    # Output:
213    # Set key. Result OperationResult<RC=0x0, Key=key, CAS=0x9a78cf56c08c0500>
214    # Got key. Result ValueResult<RC=0x0, Key=key, Value=u'value', CAS=0x9a78cf56c08c0500, Flags=0x0>
215
216
217The ``txcouchbase`` API is identical to the ``couchbase`` API, except that where
218the synchronous API will block until it receives a result, the async API will
219return a `Deferred` which will be called later with the result or an appropriate
220error.
221
222~~~~~~~~~~
223GEvent API
224~~~~~~~~~~
225
226*NOTE: this API is from SDK2 and is currently only supports SDK2-style
227access. It will be updated to support SDK3 shortly.*
228
229.. code-block:: python
230
231    from gcouchbase.bucket import Bucket
232
233    conn = Bucket('couchbase://localhost/default')
234    print conn.upsert("foo", "bar")
235    print conn.get("foo")
236
237The API functions exactly like the normal Bucket API, except that the
238implementation is significantly different.
239
240------------------------
241Asynchronous (Tulip) API
242------------------------
243
244This module also supports Python 3.4/3.5 asynchronous I/O. To use this
245functionality, import the `couchbase.experimental` module (since this
246functionality is considered experimental) and then import the `acouchbase`
247module. The `acouchbase` module offers an API similar to the synchronous
248client:
249
250.. code-block:: python
251
252    import asyncio
253
254    import couchbase.experimental
255    couchbase.experimental.enable()
256    from acouchbase.bucket import Bucket
257
258
259    async def write_and_read(key, value):
260        cb = Bucket('couchbase://10.0.0.31/default')
261        cb_coll = cb.default_collection()
262        await cb_coll.connect()
263        await cb_coll.upsert(key, value)
264        return await cb_coll.get(key)
265
266    loop = asyncio.get_event_loop()
267    rv = loop.run_until_complete(write_and_read('foo', 'bar'))
268    print(rv.value)
269
270
271~~~~~~~~~~~~~~
272Other Examples
273~~~~~~~~~~~~~~
274
275There are other examples in the `examples` directory. To run them from the
276source tree, do something like
277
278.. code-block:: sh
279
280    PYTHONPATH=$PWD ./examples/bench.py -U couchbase://localhost/default
281
282----------------------
283Building documentation
284----------------------
285
286
287The documentation is using Sphinx and also needs the numpydoc Sphinx extension.
288In order for the documentation to build properly, the C extension must have
289been built, since there are embedded docstrings in there as well.
290
291To build the documentation, go into the `docs` directory and run
292
293.. code-block:: sh
294
295    make html
296
297The HTML output can be found in `docs/build/html/`.
298
299
300Alternatively, you can also build the documentation (after building the module
301itself) from the top-level directory:
302
303.. code-block:: sh
304
305    python setup.py build_sphinx
306
307Once built, the docs will be in in `build/sphinx/html`
308
309-------
310Testing
311-------
312
313For running the tests, you need the standard `unittest` module, shipped
314with Python. Additionally, the `testresources` package is required.
315
316To run them, use either `py.test`, `unittest` or `trial`.
317
318The tests need a running Couchbase instance. For this, a `tests.ini`
319file must be present, containing various connection parameters.
320An example of this file may be found in `tests.ini.sample`.
321You may copy this file to `tests.ini` and modify the values as needed.
322
323To run the tests::
324
325    nosetests
326
327------------------------------
328Support & Additional Resources
329------------------------------
330
331If you found an issue, please file it in our JIRA_.
332You can ask questions in our forums_ or in the `#libcouchbase` channel on
333freenode_.
334
335The `official documentation`_ can be consulted as well for
336general Couchbase concepts and offers a more didactic approach to using the
337SDK.
338
339-------
340License
341-------
342
343The Couchbase Python SDK is licensed under the Apache License 2.0.
344
345.. _Couchbase: http://couchbase.com
346.. _libcouchbase: https://github.com/couchbase/libcouchbase
347.. _official documentation: https://docs.couchbase.com/python-sdk/3.0/hello-world/start-using-sdk.html
348.. _JIRA: http://couchbase.com/issues/browse/pycbc
349.. _freenode: http://freenode.net/irc_servers.shtml
350.. _pypi: http://pypi.python.org/pypi/couchbase
351.. _forums: https://forums.couchbase.com
352