This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

This Python module wraps the CouchDB HTTP REST API and defines a common interface for making blocking and non-blocking operations on a CouchDB.

Install

Install using pip:

pip install tornado-couchdb

The code has been tested with Python 3.3 and 2.7.

BlockingCouch

The BlockingCouch class is a basic wrapper for making blocking operations on a CouchDB. Using this class implies that the Tornado eventloop is blocked on a database call, waiting for reply from the database.

Use this class when blocking the eventloop is not a problem, or when there is a low latency connection to the database, and the operations are “small”, i.e., only takes short time (in the range of tens of miliseconds) to complete.

Example usage:

import couch

db = couch.BlockingCouch('mytestdb')
db.create_db()
r = db.save_doc({'msg': 'My first document'})
doc = db.get_doc(r['id'])
db.delete_doc(doc)

For any methods of this class: If an error is returned from the database, an exception is raised using an appropriate sub-class of CouchException.

Example error handling:

import couch

db = couch.AsyncCouch('mytestdb')
try:
    doc = db.get_doc('non-existing-id')
except couch.NotFound:
    print('Document not found')

AsyncCouch

The AsyncCouch class is a basic wrapper for making non-blocking operations on a CouchDB. Using this class implies that the Tornado eventloop is not blocked on a database call, and reply from the database is returned as a Future or delivered to a callback function.

Use this class when blocking the eventloop is a problem, or when there is a high latency connection to the database, and the operations are “large”, i.e., takes long time (in the range of seconds) to complete.

Example usage with coroutine:

import couch
from tornado import ioloop, gen

@gen.coroutine
def run_test():
    db = couch.AsyncCouch('mytestdb')
    yield db.create_db()
    r = yield db.save_doc({'msg': 'My first document'})
    doc = yield db.get_doc(r['id'])
    yield db.delete_doc(doc)
    yield db.delete_db()

ioloop.IOLoop.run_sync(run_test)

For any methods of this class: If the database call results in an error, an exception is raised at the callpoint using an appropriate sub-class of CouchException. This applies both when calling with a callback function and when yielding to a Future (using gen.coroutine).

Example error handling:

import couch
from tornado import ioloop, gen

@gen.coroutine
def main():
     db = couch.AsyncCouch('mytestdb')
     try:
         doc = yield db.get_doc('non-existing-id')
     except couch.NotFound:
         print('Document not found')

 ioloop.IOLoop.run_sync(main)

Note: In versions before 0.2.0, if error occured in the database call, AsyncCouch would pass the exception as a parameter to the callback function.

BlockingCouch and AsyncCouch methods

General methods.

use(self, db_name='', couch_url='http://127.0.0.1:5984/'):
    Set database name `db_name` and `couch_url`.

close(self):
    Closes the CouchDB client, freeing any resources used.

Database related methods.

create_db(self, db_name=None):
    Creates a new database.

delete_db(self, db_name=None):
    Deletes the database.

list_dbs(self):
    List names of databases.

info_db(self, db_name=None):
    Get info about the database.

pull_db(self, source, db_name=None, create_target=False):
    Replicate changes from a source database to current (target)
    database.

uuids(self, count=1):
    Get one or more uuids.

Document related methods.

get_doc(self, doc_id):
    Get document with the given `doc_id`.

get_docs(self, doc_ids):
    Get multiple documents with the given list of `doc_ids`.

    Response is a list with the requested documents, in same order as the
    provided document id's.

    If one or more documents are not found in the database, a NotFound
    exception is raised.

has_doc(self, doc_id):
    Check if document with the given `doc_id` exists.
    Returns True if document exists, returns False otherwise.

save_doc(self, doc):
    Save/create a document to/in a given database. Response is a dict
    with id and rev of the saved doc.

save_docs(self, docs, all_or_nothing=False):
    Save/create multiple documents.
    Response is a list of dicts with id and rev of the saved docs.

delete_doc(self, doc):
    Delete a document
    The `doc` shall be a dict, at least having the keys `_id` and `_rev`.

delete_docs(self, docs, all_or_nothing=False):
    Delete multiple documents
    The `docs` shall be an array of dicts, each at least having the keys
    `_id` and `_rev`.

get_attachment(self, doc, attachment_name, mimetype=None):
    Get document attachment.
    The parameter `doc` should at least contain an `_id` key.
    If mimetype is not specified, `doc` shall contain an `_attachments`
    key with info about the named attachment.

save_attachment(self, doc, attachment):
    Save an attachment to the specified doc.
    The attachment shall be a dict with keys: `mimetype`, `name`, `data`.
    The `doc` shall be a dict, at least having the key `_id`, and if doc is
    existing in the database, it shall also contain the key `_rev`

delete_attachment(self, doc, attachment_name):
    Delete a named attachment to the specified doc.
    The doc shall be a dict, at least with the keys: _id and _rev

view(self, design_doc_name, view_name, **kwargs):
    Query a pre-defined view in the specified design doc.
    The following query parameters can be specified as keyword arguments.

    Limit query results to those with the specified key or list of keys:
      key=<key-value>
      keys=<list of keys>

    Limit query results to those following the specified startkey:
      startkey=<key-value>

    First document id to include in the output:
      startkey_docid=<document id>

    Limit query results to those previous to the specified endkey:
      endkey=<key-value>

    Last document id to include in the output:
      endkey_docid=<document id>

    Limit the number of documents in the output:
      limit=<number of docs>

    Prevent CouchDB from refreshing a stale view:
      stale="ok"
      stale="update_after"

    Reverse the output:
      descending=True
      descending=False  (default value)

    Note that the descending option is applied before any key filtering, so
    you may need to swap the values of the startkey and endkey options to
    get the expected results.

    Skip the specified number of docs in the query results:
      skip=<number>  (default value is 0)

    The group option controls whether the reduce function reduces to a set
    of distinct keys or to a single result row:
      group=True
      group=False  (default value)

      group_level=<number>

    Use the reduce function of the view:
      reduce=True  (default value)
      reduce=False

    Note that default value of reduce is True, only if a reduce function is
    defined for the view.

    Automatically fetch and include the document which emitted each view
    entry:
      include_docs=True
      include_docs=False  (default value)

    Determine whether the endkey is included in the result:
      inclusive_end=True  (default value)
      inclusive_end=False

view_all_docs(self, **kwargs):
    Query the _all_docs view.
    Accepts the same keyword parameters as `view()`.

temp_view(self, view_doc, **kwargs):
    Query a temporary view.
    The view_doc parameter is a dict with the view's map and reduce
    functions.

Exceptions on database call errors

The following exception classes are used for the various database call errors:

CouchException: Base class for CouchDB specific exceptions. It is a sub-class of tornado.httpclient.HTTPError, and it therefore also contains the HTTP error message, response and error code.

NotModified: The document has not been modified since the last update.

BadRequest: The syntax of the request was invalid or could not be processed.

NotFound: The requested resource was not found.

MethodNotAllowed: The request was made using an incorrect request method; for example, a GET was used where a POST was required.

Conflict: The request failed because of a database conflict.

PreconditionFailed: Could not create database - a database with that name already exists.

InternalServerError: The request was invalid and failed, or an error occurred within the CouchDB server that prevented it from processing the request.

License

Copyright (c) 2010-2015 Nephics AB
MIT License, see the LICENSE file.
Release History

Release History

0.3.0

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
tornado_couchdb-0.3.0-py2-none-any.whl (16.2 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Jun 5, 2015
tornado_couchdb-0.3.0-py3-none-any.whl (16.2 kB) Copy SHA256 Checksum SHA256 3.4 Wheel Jun 5, 2015
tornado-couchdb-0.3.0.tar.gz (12.3 kB) Copy SHA256 Checksum SHA256 Source Jun 5, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting