couchdb/client.py: def update_doc(self, name, docid=None, **options): """Calls server side update handler.

    :param name: the name of the update handler function in the format
                 ``designdoc/updatename``.
    :param docid: optional ID of a document to pass to the update handler.
    :param options: optional query string parameters.
    :return: (headers, body) tuple, where headers is a dict of headers
             returned from the list function and body is a readable
             file-like instance
    """
    path = _path_from_name(name, '_update')
    if docid is None:
        func = self.resource(*path).post
    else:
        path.append(docid)
        func = self.resource(*path).put
    _, headers, body = func(**options)
    return headers, body

The Document Update Handlers API reference (http://docs.couchdb.org/en/latest/ddocs.html#update-functions) mentions support for both PUT and POST. For larger updates (>650bytes) PUT is not appropriate (HTTP 414, request too long, concerns). The module should prefer POST or include a kwarg to allow the caller to decide the verb.

Thanks!

Actually, the update handlers supports any method except GET (that's artificial restriction on query server side).

However, semantically only POST and PUT methods matters and there is no any restrictions on their payload size.

Is there some proxy-server in front of your CouchDB?

Cool on the any method but GET comment, good to know!

And cool on the no restriction on payload size. :) Regardless of my setup, you are right, objects are commonly length-restricted when proxies are used. Though there are additional concerns like request/access logging, which would prefer larger content in the body.

The issue does not reflect a specific setup, it is a common-practices suggestion. The flexibility of verb usage, by the caller, is desired.

Thanks!

Suddenly, you have to fix your proxy setup because CouchDB uses RESTful HTTP API where request method's makes a sense.

Fixing this issue for update handlers will not fix the similar for attachments - they are big and may be stored only with PUT method, so you will still have problems due to proxy server.

I agree with you that PUT "traditionally" makes sense in a RESTful world to update objects (and POST to create). Forgive me if I'm asking you to commit RESTful sin by allowing an update with POST, haha. ;)

POST in some scenarios does make sense to update objects (i.e., I POST to add content, I POST to add sub-content, I POST a change). In this case, CouchDB supports POST to update documents via the Document Update Handler API.

I'm not a web developer and admittedly not the person to argue/defend/describe REST implementations. Though I am a user of your module and would greatly appreciate mainline support that corroborates the CouchDB documentation. I've listed a few examples of why it may be preferred for some users. If they are not sufficient I am unfortunately at a loss.

Sure, but I'm trying to tell you that fixing update_doc method for using POST method instead of PUT because you have proxy-server issues wouldn't help you with any other CouchDB API requests that required PUT-only requests like:

• Document updates
• Attachments storing
• Database security setup
• Replication
• On fly configuration updates

So this fix would be just a workaround of your network issues, not a fix of CouchDB API misusing.

You're right, and in my case the issue is not the PUT vs. POST, but the handling of the expanded kwargs.

The following seem equivalent:

PUT update_doc(..., body=options) POST update_doc(..., **options)

PUT, with the expanded options tacks on the variables to the query string. POST, with the expanded options adds them as HTTP request content. Long request objects + query strings is trouble, long request contents is not.

My error is an oversight in the expected behavior of update_doc(..., **options). Since you're using POST and PUT (for new and updates respectively), there was some ambiguity about the behavior of the update variables. I'm not sure if this requires any action on the part of python-couchdb, though it would be nice if the API took the same action (updates within HTTP request body) when using update_doc.

Thanks!

FWIW, I have a slightly different application that would benefit from being able to specify the method. As you say, the update handler will accept any method except for GET. Even though the documentation only mentions POST & PUT, COUCHDB-1779 describes using update handlers to implement PATCH until it is available as part of the CouchDB REST API. I'm working on a project where we will use DELETE against the update handler to flag a document as deleted, but otherwise preserve its contents (basically a Trash folder).

This issue has been migrated to GitHub. Please continue discussion here:

https://github.com/djc/couchdb-python/issues/230