README.md
1COUCHBASE PYTHON LIBRARY
2========================
3
4This library provides methods to connect to both the couchbase
5memcached interface and the couchbase rest api interface.
6
7This version requires Python 2.6 or later.
8
9Open Issues: http://www.couchbase.org/issues/browse/PYCBC
10
11[](http://travis-ci.org/BigBlueHat/couchbase-python-client)
12
13USAGE
14=====
15
16Two simple use cases to set and get a key in the default bucket
17and then create a new bucket using the memcached and rest clients::
18
19 #!/usr/bin/env python
20
21 from couchbase.couchbaseclient import CouchbaseClient
22 from couchbase.couchbaseclient import MemcachedTimeoutException
23 from couchbase.rest_client import RestConnection
24
25 client = CouchbaseClient("http://localhost:8091/pools/default",
26 "default","",False)
27 client.set("key1", 0, 0, "value1")
28 client.get("key1")
29
30 server_info = {"ip":"localhost",
31 "port":8091,
32 "username":"Administrator",
33 "password":"password"}
34 rest = RestConnection(server_info)
35 rest.create_bucket(bucket='newbucket',
36 ramQuotaMB=100,
37 authType='none',
38 saslPassword='',
39 replicaNumber=1,
40 proxyPort=11215,
41 bucketType='membase')
42
43Example code that creates buckets and then does sets, gets and views using
44the unified client::
45
46 import couchbase
47
48 # connect to a couchbase server
49 cb = couchbase.Server('localhost:8091',
50 username='Administrator',
51 password='password')
52
53 # create default bucket if it doesn't exist
54 try:
55 cb.create('default')
56 except:
57 pass
58
59 # fetch a Bucket with subscript
60 default_bucket = cb['default']
61 # set a value with subscript (equivilent to .set)
62 default_bucket['key1'] = 'value1'
63
64 # fetch a bucket with a function
65 default_bucket2 = cb.bucket('default')
66 # set a json value with subscript (equivilent to .set)
67 default_bucket2['key2'] = {'value':'value2','expiration':0,'flags':10}
68
69 # set a value with a function
70 default_bucket.set('key3', 0, 0, 'value3')
71
72 # fetch a key with a function
73 print 'key1 ' + str(default_bucket.get('key1'))
74 print 'key2 ' + str(default_bucket2.get('key2'))
75 # fetch a key with subscript
76 print 'key3 ' + str(default_bucket2['key3'])
77
78 # delete a bucket
79 cb.delete('default')
80 try:
81 cb['default']
82 except Exception as ex:
83 print ex
84
85 # create a new bucket
86 try:
87 newbucket = cb.create('newbucket', ram_quota_mb=100, replica=1)
88 except:
89 newbucket = cb['newbucket']
90
91 # set a json document with a function
92 # this will translate $flags and $expiration to memcached protocol
93 # automatically generate the _id
94 doc_id = newbucket.save({'type':'item',
95 'value':'json test',
96 '$flags':25})
97 print doc_id + ' ' + str(newbucket[doc_id])
98 # use a provided _id
99 doc_id = newbucket.save({'_id':'key4',
100 'type':'item',
101 'value':'json test',
102 '$flags':25})
103 print doc_id + ' ' + str(newbucket[doc_id])
104
105 design = {
106 "_id" : "_design/testing",
107 "language" : "javascript",
108 "views" : {
109 "all" : {
110 "map" : '''function (doc) {\n emit(doc, null);\n}'''
111 },
112 },
113 }
114 # save a design document
115 # right now with no _rev, we can only create, we can't update
116 try:
117 doc_id = newbucket.save(design)
118 except:
119 doc_id = "_design/testing"
120
121 rows = newbucket.view("_design/testing/_view/all")
122 for row in rows:
123 print row
124
125
126RUNNING TESTS
127=============
128
129Requirements:
130
131 * easy_install nose
132 * pip install nose-testconfig
133
134We're now using nose to run our tests. There's a supplied
135test.ini.template that you can customize to match your installed
136environment. Copy test.ini.template to test.ini, customize, and
137then run the following command:
138
139 nosetests --tc-file=test.ini
140
141Adding coverage information is as easy as install coverage and running
142nosetests with these settings:
143
144 nosetests --tc-file=test.ini --with-coverage --cover-package=couchbase --cover-html
145
146This will output coverage reports into the 'cover' directory.
147