Skip to end of metadata
Go to start of metadata

Proposed Python SDK API

This is about designing the API for the next generation Python SDK for Couchbase. In the end the API might look the same as the current one, or be completely different. Feel free to come up with any ideas.

To make it easier to get a feeling on what the API might look like I'll list a few API calls from different SDKs.

"Python" describes the current API, "Python vmx" is what Volker Mische has in mind. Add your own ideas, leave comments or sent an email to the Couchbase Group.

Connect to a bucket

The Python has the concept of a Server Connection where you can select buckets from. In the Ruby and PHP you connect directly to a bucket.

Python

couchbase = Couchbase(ip:port, username, password)
bucket = couchbase[bucketname]

Python vmx

Following the way Ruby is doing it, keeping the bucket concept, but different from the old Python API.

cb = Couchbase.connect(ip:port, username, password, bucket)

The connect will be an instance of the Bucket class. This way the API can be expanded in the future to do administrative tasks on the cluster that are not bucket specific.

Ruby

In Ruby there are essentially two ways, with a string to the REST end-point of a bucket, or with a hash, or combined way, where you can use string URI and override its parts with options. Also it is possible to specify set of nodes as array.

# using string URI
c = Couchbase.connect("http://example.com:8091/pools")

# using Hash of options
c = Couchbase.connect(:hostname = ip, :port => port, bucket => bucket, :username => username, :password => password)

Couchbase.connect is just class method to create new instance of Couchbase::Bucket class, so you can substitute Couchbase.connect with Couchbase::Bucket.new.

PHP

$cb = new Couchbase(ip:port, username, password, bucketname);

Perl

my $cb = Couchbase::Client->new({server => "server", username => "user", password => "password"});

Get

SDK get multi-get get-and-touch
Python bucket.get(key) or
bucket[key]
- bucket.gat(key, expiry)
Python vmx cb.get(key) or
cb[key]
cb.get(array-of-keys) cb.get(key, ttl=ttl)
Ruby c.get(key) or
c[key]
c.get(key1, key2, key3, ...) c.get(key, :ttl=ttl)
PHP $cb->get(key) $cb->getMulti(array-of-keys) cb->getAndTouch(key, expiry)
Perl $cb->get(key) $cb->get_multi(array-of-keys) cb->get(key, { exp => expiry })

Set

SDK set value set value with expiration multi-set
Python bucket.set(key, expiration, flags, value) or
bucket[key] = value
bucket.set(key, expiration, flags, value) or
bucket[key] = {'value': value, 'expiration': expiration}
-
Python vmx cb.set(key, value) or
cb[key] = value
cb.set(key, value, ttl=ttl) cb.set({key1: value1, key2: value2, ...})
Ruby c.set(key, value) or
c[key] = value
c.set(key, value, :ttl=ttl) c.set(key1 => value1, key2 => value2, ...)
PHP $cb->set(key, value) $cb->set(key, value, expiry) $cb->setMulti(array-of-key-value-pairs)
Perl $cb->set(key, value) $cb->set(key, value, { exp => $expiry }) $cb->set_multi([key, value, { exp => expiry }], ...)

https://github.com/mnunberg/perl-Couchbase-Client/commit/b4ee1413746fe58f99d53e48a4560aa794ec195c

Labels

new new Delete
python python Delete
api api Delete
proposal proposal Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Mar 25, 2013

    Matt Ingenthron says:

    Generally, I like getting rid of the bucket abstraction... A couple of question...

    Generally, I like getting rid of the bucket abstraction...

    A couple of questions would be:

    • How do you propose handling flags and datatypes?
    • Will there be some kind of built in support for conversion from Python to JSON and back?

    Also, as discussed previously, I think it should accept URIs and pass those down to libcouchbase for bootstrap. libcouchbase does support this notion-- even properly where not every host has to have the same port number.

    We can debate the URI thing ongoing, but just wanted to get it out there.

    1. Mar 25, 2013

      Volker Mische says:

      The flags, will be just another named property, so you can do: cb.set(key, v...

      The flags, will be just another named property, so you can do:

      cb.set(key, value, flag=flag)
      

      Datatypes should certainly be handled, but I'd like to put it out of scope for now. I'd say that's an layer on top of the API.

      I don't think URIs should be supported. Even libcouchbase doesn't use them.

      1. Mar 25, 2013

        Matt Ingenthron says:

        Ah, but libcouchbase does use them, sort of. Admittedly, if you look at the inn...

        Ah, but libcouchbase does use them, sort of. Admittedly, if you look at the innards it's not using them well but that's implementation detail based on history. I think it is in fact bootstrapping correctly after the first HTTP fetch.

  2. Mar 26, 2013

    Pavel Paulau says:

    btw, why do we use this strange "ip:port" notation?

    btw, why do we use this strange "ip:port" notation?

    1. Mar 28, 2013

      Volker Mische says:

      I use it because every other SDK uses it, even libcouchbase.

      I use it because every other SDK uses it, even libcouchbase.

  3. Mar 26, 2013

    Mark Getz says:

    I am not a Python person so this question is merely from an API perspective. Whe...

    I am not a Python person so this question is merely from an API perspective. When doing a multi-set operation, would it be possible to use an array of objects so that each key/value pair could have its own flags, expiry, etc?

    1. Mar 28, 2013

      Volker Mische says:

      Yes sure. If it was not clear enough in the table above, it is an array of dicti...

      Yes sure. If it was not clear enough in the table above, it is an array of dictionaries. So you can easily add other properties like the expiry to it.

  4. Mar 26, 2013

    Yves Dorfsman says:

    Two questions: will this be a pure python implementation, or are we relying on...

    Two questions:

    • will this be a pure python implementation, or are we relying on a (C?) library?
    • Any idea how we want to pursue python 2 vs python 3:
      • Common code (like bottle.py)
      • Separate stream? Using automation (2to3) only, or completely separate?
    1. Mar 28, 2013

      Volker Mische says:

      For now we'll rely on a C library. Are there any problems with it? I don't see a...

      For now we'll rely on a C library. Are there any problems with it? I don't see a reason to have a pure Python one.

      I haven't yet decided on the way to support Python 2 and 3 (and also not enough experience with supporting both). Any input is welcome. Though only the higher level API would need to be separate, as the lower level is done by Cython.

  5. Apr 27, 2013

    Teemu Harju says:

    First, I'd like to say that I'm really excited that you guys started working on ...

    First, I'd like to say that I'm really excited that you guys started working on libcouchbase based Python SDK. I've been sort of experimenting with Cython and libcouchbase also.

    Few questions. About the connect API. I don't know how other SDKs handle this since I've used mainly moxi to connect to Couchbase cluster, but for availability reasons I'd like to specify multiple IPs to connect to the cluster. Like in moxi where you can give a list of URLs to connect to. Then what happens inside libcouchbase, I suppose, is that it fetches the vbucket list etc that contains the IP addresses of all the machines in the cluster. If the one node that I would use to get the list of server is down, then I would not be able to connect to the cluster at all.

    Second question. Have you thought about async support yet? We rely heavily on gevent so we'd need to have that. The Ruby SDK seems to support eventmachine, so maybe some similar ideas could be used with pylibcouchbase.

    Cheers,

    Teemu

    1. Apr 28, 2013

      Volker Mische says:

      Hi Teemu, about the initial connection to several nodes, the Ruby SDK does it, ...

      Hi Teemu,

      about the initial connection to several nodes, the Ruby SDK does it, the Python SDK will also do, though it's not implemented yet.

      We thought about async support, though first get the sync one finished. If you'd like to contribute or have any suggestions about the async support, feel free to post here, send an email to the Couchbase discussion group or directly to me.

      Cheers,
      Volker