More connection options and improved tests

The connection is no longer hard-coded, you can specify the server,
and bucket you want to connect to (together with username and
password).

The test suite was also improved. It's now easier to get it
working with your own Couchbase instance. The parmeters for the
tests are in `tests/tests.ini`.

README.md

@@ -57,7 +57,18 @@ The HTML output can be found in `docs/build/html/`.
 Running tests
 -------------
 
-If you have Python >=2.7 or >=3.2 you can run:
+The tests need a running Couchbase instance. The values to connect to the
+instance can be found in the test configuration file `tests/tests.ini`.
+
+The test suite need several buckets which need to be created before the tests
+are run. They will all have the common prefix as specified in the test
+configuration file. To create them, run:
+
+    python tests/setup_tests.py
+
+If the buckets already exist, they will be recreated.
+
+Now you can run the test. If you have Python >=2.7 or >=3.2 you can run:
 
     python -m unittest discover -s tests
 

couchbase/__init__.py

@@ -7,35 +7,54 @@
 class Couchbase:
     """The base class for interacting with Couchbase"""
     @staticmethod
-    def connect(host='localhost', port=8091):
+    def connect(host='localhost', port=8091, username=None, password=None,
+                bucket=None):
         """Connect to a bucket
 
+        The parameters `password` and `bucket` are **not** optional and
+        will cause a :exc:`couchbase.excpetions.ArgumentError`
+        exception if they are not specified.
+        If `username` is not given, it will automatically set to the
+        bucket name, as it is expected that you try to connect to a SASL
+        protected bucket, where the username is equal to the bucket
+        name.
+
         :param string host: the hostname or IP address of the node
         :param number port: port of the management API
+        :param string username: the user name to connect to the cluster.
+                                It's the username of the management API.
+                                The username could be skipped for
+                                protected buckets, the bucket name will
+                                be used instead.
+        :param string password: the password of the user or bucket
+        :param string bucket: the bucket name
 
-        :raise: :exc:`couchbase.exceptions.BucketNotFoundError` if there is
-                no such bucket to connect to
+        :raise: :exc:`couchbase.exceptions.BucketNotFoundError` if there
+                is no such bucket to connect to
 
                 :exc:`couchbase.exceptions.ConnectError` if the socket
                 wasn't accessible (doesn't accept connections or doesn't
                 respond in time)
 
+                :exc:`couchbase.exceptions.ArgumentError` if either the
+                password or the bucket wasn't specified
+
         :return: instance of :class:`couchbase.libcouchbase.Connection`
 
 
         Initialize connection using default options::
 
             from couchbase import Couchbase
-            cb = Couchbase.connect()
-
-        Select custom bucket::
-
-            cb = Couchbase.connect(bucket = 'foo')
+            cb = Couchbase.connect(username='admin', password='secret',
+                                   bucket='mybucket')
 
         Connect to protected bucket::
 
-            cb = Couchbase.connect('localhost', 8091, 'protected', 'secret',
-                                   'protected')
+            cb = Couchbase.connect(password='secret', bucket='protected')
+
+        Connect to a different server on the default port 8091::
 
+            cb = Couchbase.connect('example.com', username='admin',
+                                   password='secret', bucket='mybucket')
         """
-        return libcouchbase.Connection(host, port)
+        return libcouchbase.Connection(host, port, username, password, bucket)

couchbase/connection.pyx

@@ -1,4 +1,5 @@
 import couchbase.exceptions
+from couchbase.exceptions import ArgumentError
 
 
 cdef void cb_get_callback(lcb.lcb_t instance, const void *cookie,
@@ -29,9 +30,32 @@ cdef class Connection:
         self.default_format = CB_FMT_JSON
         memset(&self._create_options, 0, sizeof(self._create_options))
 
-    def __init__(self, host='localhost', port='8091'):
+    def __init__(self, host='localhost', port=8091, username=None,
+                 password=None, bucket=None):
+        """Connection to a bucket
+
+        Normally it's initialized through
+        :meth:`couchbase.Couchbase.connect`
+        """
+        if password is None:
+            raise ArgumentError("A password must be given")
+        if bucket is None:
+            raise ArgumentError("A bucket name must be given")
+
         host = (host + (':%d' % port)).encode('utf-8')
+        password = password.encode('utf-8')
+        bucket = bucket.encode('utf-8')
+
+        if username is None:
+            # Try to connect to a protected bucket
+            username = bucket
+        else:
+            username = username.encode('utf-8')
+
         self._create_options.v.v0.host = host
+        self._create_options.v.v0.bucket = bucket
+        self._create_options.v.v0.user = username
+        self._create_options.v.v0.passwd = password
 
         rc = lcb.lcb_create(&self._instance, &self._create_options)
         Utils.maybe_raise(rc, 'failed to create libcouchbase instance')

couchbase/exceptions.py

@@ -1,6 +1,15 @@
 from couchbase.libcouchbase import CouchbaseError
 
 
+class ArgumentError(CouchbaseError):
+    """Invalid argument
+
+    A given argument is invalid or must be set
+    """
+
+
+# The following exceptions are derived from libcouchbase
+
 class AuthError(CouchbaseError):
     """Authentication failed