Volker Mische | 25 Mar 21:34 2013
Picon

API design for new Python SDK

Hi all,

it's time to start thinking about the API for the new Python SDK. This
time I've put some bits in the Couchbase wiki to get discussion started [1].

After my little research I've the feeling that the Ruby SDK got a lot of
things right and that it might make sense to have the Python SDK pretty
similar to it.

Though nothing is set in stone, so please keep the ideas coming.

[1] http://www.couchbase.com/wiki/display/couchbase/Proposed+Python+API

Cheers,
  Volker

--

-- 
You received this message because you are subscribed to the Google Groups "Couchbase" group.
To unsubscribe from this group and stop receiving emails from it, send an email to couchbase+unsubscribe@...
For more options, visit https://groups.google.com/groups/opt_out.

Volker Mische | 26 Mar 13:40 2013
Picon

Re: API design for new Python SDK

On 03/25/2013 09:34 PM, Volker Mische wrote:
> Hi all,
> 
> it's time to start thinking about the API for the new Python SDK. This
> time I've put some bits in the Couchbase wiki to get discussion started [1].
> 
> After my little research I've the feeling that the Ruby SDK got a lot of
> things right and that it might make sense to have the Python SDK pretty
> similar to it.
> 
> Though nothing is set in stone, so please keep the ideas coming.
> 
> [1] http://www.couchbase.com/wiki/display/couchbase/Proposed+Python+API

I've updated the wiki page. The bucket concept is back, but in the way
the Ruby client does it. It's now:

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

This way functions for administrative tasks could be added to the main
Couchbase class.

Cheers,
  Volker

--

-- 
You received this message because you are subscribed to the Google Groups "Couchbase" group.
To unsubscribe from this group and stop receiving emails from it, send an email to couchbase+unsubscribe@...
For more options, visit https://groups.google.com/groups/opt_out.

(Continue reading)

Matt Ingenthron | 26 Mar 15:29 2013

Re: API design for new Python SDK

On 3/26/13 5:40 AM, "Volker Mische" <volker.mische@...> wrote:

>I've updated the wiki page. The bucket concept is back, but in the way
>the Ruby client does it. It's now:
>
>    cb = Couchbase.connect(ip:port, username, password, bucket)
>
>This way functions for administrative tasks could be added to the main
>Couchbase class.

Makes sense to me.

I do think we'll want a CouchbaseCluster object at some point too like
other SDKs, but that's not the main API thing to look at for right now.

-- 
Matt Ingenthron - Director, Developer Solutions
Couchbase, Inc.

--

-- 
You received this message because you are subscribed to the Google Groups "Couchbase" group.
To unsubscribe from this group and stop receiving emails from it, send an email to couchbase+unsubscribe@...
For more options, visit https://groups.google.com/groups/opt_out.

Yves Dorfsman | 29 Mar 06:42 2013

Re: API design for new Python SDK

On 2013-03-26 06:40, Volker Mische wrote:
 > I've updated the wiki page. The bucket concept is back, but in the way
 > the Ruby client does it. It's now:
> cb = Couchbase.connect(ip:port, username, password, bucket)

     cb = Couchbase.connect('localhost:8091', '', '', 'users')
TypeError: descriptor 'connect' requires a 'lcb.Couchbase' object but received 
a 'str'

Was this just a concept for now, or have you implemented it already?

-- 
Yves.                                                  http://www.SollerS.ca/
                                  Unix/Linux and Python specialist in Calgary.
                                                        http://blog.zioup.org/

--

-- 
You received this message because you are subscribed to the Google Groups "Couchbase" group.
To unsubscribe from this group and stop receiving emails from it, send an email to couchbase+unsubscribe@...
For more options, visit https://groups.google.com/groups/opt_out.

Volker Mische | 30 Mar 00:43 2013
Picon

Re: API design for new Python SDK

On 03/29/2013 06:42 AM, Yves Dorfsman wrote:
> On 2013-03-26 06:40, Volker Mische wrote:
>> I've updated the wiki page. The bucket concept is back, but in the way
>> the Ruby client does it. It's now:
>> cb = Couchbase.connect(ip:port, username, password, bucket)
> 
>     cb = Couchbase.connect('localhost:8091', '', '', 'users')
> TypeError: descriptor 'connect' requires a 'lcb.Couchbase' object but
> received a 'str'
> 
> Was this just a concept for now, or have you implemented it already?

It isn't implemented yet. I guess I should have made this more explicit.
The API discussion is completely independent from the implementation for
now.

First get the API right, then implement it. Though I already start to
implement during the API design. The implementation might lack behind
the most recent API decisions.

If that's too confusing and you don't feel like knowing what's going on,
but you'd like to contribute to either the API, the implementation or
both, let me know. I can increase the communication through this list or
make a better plan. But as it is currently only me, I do what works best
for me :)

Cheers,
  Volker

--

-- 
(Continue reading)

Michael Salmon | 28 Mar 09:59 2013

Re: API design for new Python SDK

Here are some comments/goals (can't edit wiki). Grain of salt required, as I'm new at this db, but maybe that is a helpful perspective..

#1. Error messages should be more descriptive, and cascade server error-codes to user-code. For example if a 401 occurs today, here's what client.py does...

client.py:#59
requests.get(server_config_uri).json() # this code is not very friendly...

raceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python2.7/site-packages/couchbase/client.py", line 59, in __init__
    jsonResp = requests.get(server_config_uri)
  File "/usr/lib/python2.7/site-packages/requests/models.py", line 604, in json
    return json.loads(self.text or self.content)
  File "/usr/lib/python2.7/site-packages/simplejson/__init__.py", line 455, in loads
    return _default_decoder.decode(s)
  File "/usr/lib/python2.7/site-packages/simplejson/decoder.py", line 374, in decode
    obj, end = self.raw_decode(s)
  File "/usr/lib/python2.7/site-packages/simplejson/decoder.py", line 393, in raw_decode
    return self.scan_once(s, idx=_w(s, idx).end())
  File "/usr/lib/python2.7/site-packages/simplejson/scanner.py", line 119, in scan_once
    return _scan_once(string, idx)
  File "/usr/lib/python2.7/site-packages/simplejson/scanner.py", line 84, in _scan_once
    raise JSONDecodeError(errmsg, string, idx)
simplejson.scanner.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

#2. Do not go back to the URI approach without a good reason. Because it's already flip-flopped from (a) to (b) http://www.couchbase.com/develop/python/next

#3 If getting rid of the bucket abstraction that's fine, then all calls get handled by a client object I imagine, and you pass in the bucket name to the db connection. It does imply though developers will need to keep extra database connection objects per bucket, vs before they could keep fewer db connections and query for the bucket when needed. Though I'm assuming cost of instantiating the connection is much higher than the bucket, at least that's what the docs indicate

#4 Avoid using different terms for the same thing, e.g. "key" and "documentID". docID makes more sense to me and is in the web GUI. key is in all the api documentation today though.

#5 bonus points - implement updating a field within a doc, I believe there's a feature request in jira: e.g.
doc = client.get("docID") # or bucket.get depending if that's still around
doc.replace("{'some': 123}") # doing the replace on the doc itself, instead of through the client. but either is fine

Thanks,
Michael




On Mon, Mar 25, 2013 at 1:34 PM, Volker Mische <volker.mische <at> gmail.com> wrote:
Hi all,

it's time to start thinking about the API for the new Python SDK. This
time I've put some bits in the Couchbase wiki to get discussion started [1].

After my little research I've the feeling that the Ruby SDK got a lot of
things right and that it might make sense to have the Python SDK pretty
similar to it.

Though nothing is set in stone, so please keep the ideas coming.

[1] http://www.couchbase.com/wiki/display/couchbase/Proposed+Python+API

Cheers,
  Volker

--
You received this message because you are subscribed to the Google Groups "Couchbase" group.
To unsubscribe from this group and stop receiving emails from it, send an email to couchbase+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
For more options, visit https://groups.google.com/groups/opt_out.



--
You received this message because you are subscribed to the Google Groups "Couchbase" group.
To unsubscribe from this group and stop receiving emails from it, send an email to couchbase+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
For more options, visit https://groups.google.com/groups/opt_out.
 
 
Volker Mische | 28 Mar 13:45 2013
Picon

Re: API design for new Python SDK

Hi Michael,

thanks for the feedback.

On 03/28/2013 09:59 AM, Michael Salmon wrote:
> Here are some comments/goals (can't edit wiki). Grain of salt required,
> as I'm new at this db, but maybe that is a helpful perspective..

You can't edit without an account, but weren't you able to create one?
If you don't want to create one I can understand that, it's a hassle.
Email works for me as well, I'll incorporate it into the wiki.

> #1. Error messages should be more descriptive, and cascade server
> error-codes to user-code. For example if a 401 occurs today, here's what
> client.py does...
> 
> client.py:#59
> requests.get(server_config_uri).json() # this code is not very friendly...
> 
> raceback (most recent call last):
>   File "<stdin>", line 1, in <module>
>   File "/usr/lib/python2.7/site-packages/couchbase/client.py", line 59,
> in __init__
>     jsonResp = requests.get(server_config_uri)
>   File "/usr/lib/python2.7/site-packages/requests/models.py", line 604,
> in json
>     return json.loads(self.text or self.content)
>   File "/usr/lib/python2.7/site-packages/simplejson/__init__.py", line
> 455, in loads
>     return _default_decoder.decode(s)
>   File "/usr/lib/python2.7/site-packages/simplejson/decoder.py", line
> 374, in decode
>     obj, end = self.raw_decode(s)
>   File "/usr/lib/python2.7/site-packages/simplejson/decoder.py", line
> 393, in raw_decode
>     return self.scan_once(s, idx=_w(s, idx).end())
>   File "/usr/lib/python2.7/site-packages/simplejson/scanner.py", line
> 119, in scan_once
>     return _scan_once(string, idx)
>   File "/usr/lib/python2.7/site-packages/simplejson/scanner.py", line
> 84, in _scan_once
>     raise JSONDecodeError(errmsg, string, idx)
> simplejson.scanner.JSONDecodeError: Expecting value: line 1 column 1
> (char 0)

Yes, better error messages are a must. I haven't added it to the wiki as
this is clear to me :)

> #2. Do not go back to the URI approach without a good reason. Because
> it's already flip-flopped from (a) to
> (*b) *http://www.couchbase.com/develop/python/next

I thought the URI way was still possible, but checking the code, it was
not. Good point.

> #3 If getting rid of the bucket abstraction that's fine, then all calls
> get handled by a client object I imagine, and you pass in the bucket
> name to the db connection. It does imply though developers will need to
> keep extra database connection objects per bucket, vs before they could
> keep fewer db connections and query for the bucket when needed. Though
> I'm assuming cost of instantiating the connection is much higher than
> the bucket, at least that's what the docs indicate

The connections are always per bucket, so it's just a matter of the API.

> #4 Avoid using different terms for the same thing, e.g. "key" and
> "documentID". docID makes more sense to me and is in the web GUI. key is
> in all the api documentation today though.

I think key is pretty common.

> #5 bonus points - implement updating a field within a doc, I believe
> there's a feature request in jira: e.g.
> doc = client.get("docID") # or bucket.get depending if that's still around
> doc.replace("{'some': 123}") # doing the replace on the doc itself,
> instead of through the client. but either is fine

That won't come to Couchbase soon, it can surely be implemented in the
client. But I don't know if it is good to hide that from the user or not.

It could be something like a recipe that shows how to implement little
helpers on top of the API.

Cheers,
  Volker

> On Mon, Mar 25, 2013 at 1:34 PM, Volker Mische <volker.mische@...
> <mailto:volker.mische@...>> wrote:
> 
>     Hi all,
> 
>     it's time to start thinking about the API for the new Python SDK. This
>     time I've put some bits in the Couchbase wiki to get discussion
>     started [1].
> 
>     After my little research I've the feeling that the Ruby SDK got a lot of
>     things right and that it might make sense to have the Python SDK pretty
>     similar to it.
> 
>     Though nothing is set in stone, so please keep the ideas coming.
> 
>     [1] http://www.couchbase.com/wiki/display/couchbase/Proposed+Python+API
> 
>     Cheers,
>       Volker
> 
>     --
>     You received this message because you are subscribed to the Google
>     Groups "Couchbase" group.
>     To unsubscribe from this group and stop receiving emails from it,
>     send an email to couchbase+unsubscribe@...
>     <mailto:couchbase%2Bunsubscribe@...>.
>     For more options, visit https://groups.google.com/groups/opt_out.
> 
> 
> 
> -- 
> You received this message because you are subscribed to the Google
> Groups "Couchbase" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to couchbase+unsubscribe@...
> For more options, visit https://groups.google.com/groups/opt_out.
>  
>  

--

-- 
You received this message because you are subscribed to the Google Groups "Couchbase" group.
To unsubscribe from this group and stop receiving emails from it, send an email to couchbase+unsubscribe@...
For more options, visit https://groups.google.com/groups/opt_out.


Gmane