[PYCBC-176] merge the 1.1 updated documentation into docs templates Created: 21/Aug/13  Updated: 25/Sep/13

Status: Open
Project: Couchbase Python Client Library
Component/s: None
Affects Version/s: None
Fix Version/s: 1.1.0
Security Level: Public

Type: Task Priority: Blocker
Reporter: Matt Ingenthron Assignee: Matt Ingenthron
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   
Need the updated documentation with 1.1 to be merged into the main docs.

Mark: this is assigned to you because you have supplied it, but Amy needs some guidance on how to handle the merge. The problem is that your generated docs make changes to the section of docs that had been previously edited and are part of the 1.0 docs.

Guidance needed: can you either generate just the 1.1 changed set, or let us know that it'll have to be manually merged. Also, how will we handle this going forward.

 Comments   
Comment by Mark Nunberg [ 25/Sep/13 ]
I really have no idea what this means. Traditionally my pattern with writing the docs has been to generate XML and stuff it inside the docs repo, with the other toolchain there applying the necessary formatting.

Feel free to reassign this to amy or close this if that's all that needs to be done on my part.




[PYCBC-237] Add page_size option to RowProcessor to limit get_multi sizes Created: 06/Mar/14  Updated: 12/May/14

Status: Open
Project: Couchbase Python Client Library
Component/s: None
Affects Version/s: None
Fix Version/s: None
Security Level: Public

Type: Improvement Priority: Major
Reporter: Mark Nunberg Assignee: Mark Nunberg
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   
This option would be delivered to the RowProcessor implementation (if it's an instance of RowProcessor) to limit the number of documents fetched for a multi-get when dealing with many view results.

Currently if we get several thousand results in a single fetch, it means the include_docs handling with also try to do a get_multi on that many documents.

This will waste much memory and slow down the application.

 Comments   
Comment by Mark Nunberg [ 12/May/14 ]
Note this is possible to work around via user code by implementing a custom RowProcessor




[PYCBC-214] bucket flush needs to be added Created: 06/Jan/14  Updated: 08/Jan/14

Status: Open
Project: Couchbase Python Client Library
Component/s: docs, library
Affects Version/s: 1.1.0
Fix Version/s: None
Security Level: Public

Type: Bug Priority: Major
Reporter: Matt Ingenthron Assignee: Mark Nunberg
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   
For a given bucket, there needs to be an easy way to invoke the bucket's RESTful flush(). This should be at the bucket level and authentication level. In other words, for a given bucket that I'm doing set()/get() with, I should be able to flush(). That flush() must use the REST interface for the bucket, not broadcast the libcouchbase/memached flush operation.

Note that it is safe for other client instances to be connected during this RESTful flush() operation. Also, it may be worth mentioning in the docs that flush is not atomic on the cluster and will propagate asynchronously.

 Comments   
Comment by Mark Nunberg [ 08/Jan/14 ]
We currently lack an admin interface; we'd be doing this via the admin interface if we were to support it.




[PYCBC-179] add_multi documentation could use improvement Created: 29/Aug/13  Updated: 03/Sep/13

Status: Open
Project: Couchbase Python Client Library
Component/s: docs
Affects Version/s: 1.0.0
Fix Version/s: None
Security Level: Public

Type: Improvement Priority: Major
Reporter: Michael Manfre Assignee: Mark Nunberg
Resolution: Unresolved Votes: 0
Labels: usability
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   
The docs don't mention that add_multi will raise KeyExistsError for the last already existing key, if any number of them already exist. If this is intentional behavior, mentioning it in the docs would be useful and that the KeyExistsError.all_results is where most people will need to look for the OperationResult list.

This behavior seems odd for the API. Assuming there is not a connection/server error, always returning the OperationResult dict would be more intuitive and avoid the code pattern of:

try:
  results = bucket.add_multi(keys)
except KeyExistsError as e:
  # ignore exception because I'm going to process the results anyway
  results = e.all_results

# now process/verify 'results'

---
If add_multi always returned an OperationResult dict, the code would simply be:

results = bucket.add_multi(keys)
# process/verify 'results' without the unnecessary exception

 Comments   
Comment by Mark Nunberg [ 03/Sep/13 ]
This may be fixed in subsequent versions, but the *multi API is expected to function identically to the single API with the exception of the return type being a dict rather than a Result object.

What I may do in the future is simply make all exception throwing optional (i.e. at least those exceptions caused by libcouchbase - the library may still throw exceptions in true "exceptional" situations).

Does that sound better?
Comment by Michael Manfre [ 03/Sep/13 ]
Given the API decision of "multi == single, except make the return type make sense for the function", how about changing that to "multi == single, except the return type and raised exceptions make sense for the function"? That API guideline change would open up two options to fix the multi functions.

1. (Preferred Fix) Always return a dict for the multi functions and don't raise the key errors. This is how memcached handles get_multi. Errors should still be raised in true "exceptional" situations.

2. Change the key error to also includes a list of keys that failed, instead of just all_results. While not ideal as always getting a result dict back, this would at least avoid all code from having to duplicate the work done by the couchbase driver, which already knows which keys failed.

----
If you make all exception throwing optional, please do so on a per function basis and not on a per connection basis. Per connection settings are only useful when you control all code that may use the connection, which may prevent using 3rd party packages that made a different 'quiet' choice when writing their code.
Comment by Mark Nunberg [ 03/Sep/13 ]
I'd like to get rid of exception throwing in _all_ situations except for true "unrecoverable" exceptions (for example, invalid format or some other serious error). Otherwise I do agree.

The problem with trying to figure out which keys "failed" is that currently only one exception (i.e. the first failure) is thrown - while the other ones still exist. Because Python cannot really return values when an exception has been thrown, those values are stored in the '.all_results' field of the exception object.

Note that you can use the Item API (though this is not present in 1.0.0, it will be available in 1.1.0) to go back to 'normal' behavior.

Also note that internally, the Couchbase driver doesn't really know which key failed - there is only _one_ failure flag internally for key failures - so that there isn't a huge performance hit if a lot of keys fail.

Feel free to rename this issue as "Don't raise exceptions on key failures", as this involves a lot of annoying boilerplate in any event. What we really should have done is something like:

# Raise on any error
cb.set(key, value, raise=True)

# Raise only on specific failures
cb.set(key, value, raise=[0x18, 0x27, 0x13])

# Don't raise (default)
cb.set(key, value)




[PYCBC-173] syncwait in design_create() expects "views" key Created: 13/Aug/13  Updated: 13/Aug/13

Status: Open
Project: Couchbase Python Client Library
Component/s: library
Affects Version/s: 1.1.0
Fix Version/s: None
Security Level: Public

Type: Bug Priority: Major
Reporter: Volker Mische Assignee: Mark Nunberg
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   
When you call design_create() with syncwait > 0 it polls the design document whether they are there or not. The polling seems to check the "views" key/value. The problem is that the design document might not contain any "views", but only spatial views that use "spatial" as key.




[PYCBC-133] Provide class-level methods by which to not print out long values Created: 13/Jun/13  Updated: 13/Jun/13

Status: Open
Project: Couchbase Python Client Library
Component/s: library
Affects Version/s: 0.11.1
Fix Version/s: None
Security Level: Public

Type: Task Priority: Major
Reporter: Mark Nunberg Assignee: Mark Nunberg
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Comments   
Comment by Mark Nunberg [ 13/Jun/13 ]
If a value is several long KBs and it has an exception, the screen will not be happy :)




[PYCBC-238] Add couchbase cluster compatibility to documentation Created: 25/Mar/14  Updated: 23/Jun/14

Status: Open
Project: Couchbase Python Client Library
Component/s: docs
Affects Version/s: None
Fix Version/s: .future
Security Level: Public

Type: Improvement Priority: Major
Reporter: Matt Ingenthron Assignee: Mark Nunberg
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Gantt: finish-start
has to be done after JCBC-438 Add table for 1.8, 2.x and 3.x compat... Open

 Description   
We should probably specify for this given major.minor of the SDK, one of three things for Couchbase Cluster releases:
- unsupported
- supported
- supports all features

These might be an 'x', '—' and "✓" in a table, or whatever Amy comes up with.

This is, in part, planning for 3.0 including beta.

This should be based on the work done in JCBC-438, so it's blocked by that issue.




[PYCBC-233] add discussion of timeout accuracy and resolution to documentation Created: 27/Feb/14  Updated: 23/Jun/14

Status: Open
Project: Couchbase Python Client Library
Component/s: docs
Affects Version/s: None
Fix Version/s: .future
Security Level: Public

Type: Improvement Priority: Major
Reporter: Matt Ingenthron Assignee: Mark Nunberg
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   
Since our timeouts are only as accurate as the underlying APIs/subsystems we use, we should document this for our users so they can plan accordingly. For instance, if processes aren't scheduled for a long period of time owing to CPU or memory contention... or in some cases IO doesn't happen for a long time and our timeout is IO event driven, we may not timeout to the application until later.




[PYCBC-250] support for distributing data by hashkey Created: 03/Jul/14  Updated: 03/Jul/14

Status: Open
Project: Couchbase Python Client Library
Component/s: apidocs, docs, library
Affects Version/s: None
Fix Version/s: .future
Security Level: Public

Type: New Feature Priority: Major
Reporter: Matt Ingenthron Assignee: Matt Ingenthron
Resolution: Unresolved Votes: 0
Labels: customer
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   
In some situations, users would like to co-locate related data to ensure that failure of a node would affect only related data, rather than a single node failure affecting possibly all user's data. This is referring to supporting the 'hashkey' function that exists in libcouchbase.

 Comments   
Comment by Matt Ingenthron [ 03/Jul/14 ]
Note that I've assigned this to myself as this would need to be considered as part of a bigger change. Couchbase Server is not tested in this fashion where data may be unevenly distributed and having this supported by some clients and not others would be a concern. I wanted to track the request for this feature, however, so I've posted it here.




[PYCBC-204] Release notes for the Windows SDK should have a link to the libcouchbase version used. Created: 04/Nov/13  Updated: 04/Nov/13

Status: Open
Project: Couchbase Python Client Library
Component/s: docs
Affects Version/s: 1.1.0
Fix Version/s: None
Security Level: Public

Type: Task Priority: Minor
Reporter: Patrick Varley Assignee: Mark Nunberg
Resolution: Unresolved Votes: 0
Labels: customer, documentation
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment: http://docs.couchbase.com/couchbase-sdk-python-1.1/#release-notes-for-couchbase-python-sdk-110-ga-1-october-2013


 Description   
The Python SDK for Windows includes libcouchbase.
The release notes should say which version of libcouchbase it uses and a link to that version's release note.

 Comments   
Comment by Mark Nunberg [ 04/Nov/13 ]
You can determine this at runtime :) - Connection.lcb_version()




[PYCBC-152] Tutorial review comments Created: 10/Jul/13  Updated: 24/Jul/13

Status: Open
Project: Couchbase Python Client Library
Component/s: docs
Affects Version/s: None
Fix Version/s: 1.0.0
Security Level: Public

Type: Task Priority: Minor
Reporter: Amy Kurtzman Assignee: Mark Nunberg
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: PDF File couchbase-sdk-python_tutorial_20130626-checked-off.pdf    

 Description   
Volker reviewed the tutorial section in the Python client library SDK and made many comments. Some of those comments suggest changes to the beer sample application. The comments note items of varying severity. For example, one of the comments says that the sample application won't run without the addition of a couple of lines of code.

This task is to review the comments. Then, if needed, update & test the sample code in Github, and then update the SDK documentation to match the sample code.

Attachment: My copy of Volker's review comments. In my copy I checked off the comments that I updated in the documentation.




Generated at Tue Sep 02 14:23:27 CDT 2014 using JIRA 5.2.4#845-sha1:c9f4cc41abe72fb236945343a1f485c2c844dac9.