cloudant 0.2.1

# Cloudant.py [](https://travis-ci.org/cloudant-labs/cloudant-python) [](https://coveralls.io/r/cloudant-labs/cloudant-python) [](https://crate.io/packages/cloudant/) [](https://crate.io/packages/cloudant/)

An effortless Cloudant / CouchDB interface for Python.

## Install

pip install cloudant

## Usage

Cloudant.py is an asynchronous wrapper around Python [Requests](http://www.python-requests.org/en/latest/) for interacting with CouchDB or Cloudant instances. Check it out:

import cloudant

# create a connection object
conn = cloudant.Connection()
# create a database object
db = conn.database('test')
# now, create the database on the server
future = db.put()
response = future.result()
print response.json()
# {'ok': True}

### Philosophy

Cloudant and CouchDB expose REST APIs that map effortlessly into native Python objects. As much as possible, Cloudant.py uses native Python objects as shortcuts to the raw API, so that such convenience never obscures what's going on underneath. For example:

import cloudant

conn = cloudant.Connection()
db = conn.database('test')
same_db = conn['test']
assert db.uri == same_db.uri
# True

Cloudant.py expose raw interactions -- HTTP requests, etc. -- through special methods, so we provide syntactical sugar without obscuring the underlying API. Built-ins, such as `__getitem__`, act as Pythonic shortcuts to those methods. For example:

import cloudant

conn = cloudant.Connection()
db = conn.database('test')
doc = db.document('test_doc')
# create the document
resp = doc.put({
'_id': 'hello_world',
'herp': 'derp'
}).result()
# delete the document
rev = resp.json()['_rev']
doc.delete(rev).result()
# but this also creates a document
db['hello_world'] = {'herp': 'derp'}

If CouchDB has a special endpoint for something, it's in Cloudant.py as a special method, so any special circumstances are taken care of automagically. For example:

import cloudant

conn = cloudant.Connection()
db = conn.database('test')
view = db.all_docs() # returns all docs in the database
for doc in db:
# iterates over every doc in the database
pass
for doc in view:
# and so does this!
pass

### Asynchronous

HTTP request methods like `get` and `post` return `Future` objects, which represent an eventual response. This allows your code to keep executing while the request is off doing its business in cyberspace. To wait for the response, use the `result` method, like so:

import cloudant

conn = cloudant.Connection()
db = conn['test']
future = db.put()
response = future.result()
print db.get().result().json()
# {'db_name': 'test', ...}

As a result, any methods which must make an HTTP request return a `Future`.

### Option Inheritance

If you use one object to create another, the child will inherit the parents' settings. So, you can create a `Database` object explicitly, or use `Connection.database` to inherit cookies and other settings from the `Connection` object. For example:

import cloudant

conn = cloudant.Connection()
db = conn.database('test')
doc = db.document('test_doc')
otherdoc = cloudant.Document('http://localhost:5984/test/test_doc')
assert doc.uri == otherdoc.uri
# True

## API
- [Connection](#Connection)
- [Connection.active_tasks](#Connection.active_tasks)
- [Connection.all_dbs](#Connection.all_dbs)
- [Connection.database](#Connection.database)
- [Connection.delete](#Connection.delete)
- [Connection.get](#Connection.get)
- [Connection.login](#Connection.login)
- [Connection.logout](#Connection.logout)
- [Connection.post](#Connection.post)
- [Connection.put](#Connection.put)
- [Connection.replicate](#Connection.replicate)
- [Connection.session](#Connection.session)
- [Connection.uuids](#Connection.uuids)
- [Database](#Database)
- [Database.all_docs](#Database.all_docs)
- [Database.changes](#Database.changes)
- [Database.delete](#Database.delete)
- [Database.document](#Database.document)
- [Database.get](#Database.get)
- [Database.missing_revs](#Database.missing_revs)
- [Database.post](#Database.post)
- [Database.put](#Database.put)
- [Database.revs_diff](#Database.revs_diff)
- [Database.save_docs](#Database.save_docs)
- [Database.view_cleanup](#Database.view_cleanup)
- [Document](#Document)
- [Document.attachment](#Document.attachment)
- [Document.delete](#Document.delete)
- [Document.get](#Document.get)
- [Document.merge](#Document.merge)
- [Document.post](#Document.post)
- [Document.put](#Document.put)
- [Document.view](#Document.view)
- [View](#View)
- [View.delete](#View.delete)
- [View.get](#View.get)
- [View.post](#View.post)
- [View.put](#View.put)
- [Attachment](#Attachment)
- [Attachment.delete](#Attachment.delete)
- [Attachment.get](#Attachment.get)
- [Attachment.post](#Attachment.post)
- [Attachment.put](#Attachment.put)

<a name="Connection"></a>
### Connection(uri, **kwargs)

A connection to a Cloudant or CouchDB instance.

connection = cloudant.Connection()
connection.login(USERNAME, PASSWORD).result()
print connection.get().result().json()
# {"couchdb": "Welcome", ...}

<a name="Connection.active_tasks"></a>
#### Connection.active_tasks(**kwargs)

List replication, compaction, and indexer tasks currently running.

<a name="Connection.all_dbs"></a>
#### Connection.all_dbs(**kwargs)

List all databases.

<a name="Connection.database"></a>
#### Connection.database(name, **kwargs)

Create a `Database` object prefixed with this connection's URL.

<a name="Connection.delete"></a>
#### Connection.delete(path, **kwargs)

Make a DELETE request against the object's URI joined
with `path`. `kwargs` are passed directly to Requests.

<a name="Connection.get"></a>
#### Connection.get(path, **kwargs)

Make a GET request against the object's URI joined
with `path`. `kwargs` are passed directly to Requests.

<a name="Connection.login"></a>
#### Connection.login(username, password, **kwargs)

Authenticate the connection via cookie.

<a name="Connection.logout"></a>
#### Connection.logout(**kwargs)

De-authenticate the connection's cookie.

<a name="Connection.post"></a>
#### Connection.post(path, **kwargs)

Make a POST request against the object's URI joined
with `path`.

`kwargs['params']` are turned into JSON before being
passed to Requests. If you want to indicate the message
body without it being modified, use `kwargs['data']`.

<a name="Connection.put"></a>
#### Connection.put(path, **kwargs)

Make a PUT request against the object's URI joined
with `path`.

`kwargs['params']` are turned into JSON before being
passed to Requests. If you want to indicate the message
body without it being modified, use `kwargs['data']`.

<a name="Connection.replicate"></a>
#### Connection.replicate(source, target, opts, **kwargs)

Begin a replication job.
`opts` contains replication options such as whether the replication
should create the target (`create_target`) or whether the replication
is continuous (`continuous`).

Note: unless continuous, will not return until the job is finished.

<a name="Connection.session"></a>
#### Connection.session(**kwargs)

Get current user's authentication and authorization status.

<a name="Connection.uuids"></a>
#### Connection.uuids(count, **kwargs)

Generate an arbitrary number of UUIDs.

<a name="Database"></a>
### Database(uri, **kwargs)

Connection to a specific database.

Learn more about the raw API from the [Cloudant docs](http://docs.cloudant.com/api/database.html).

<a name="Database.all_docs"></a>
#### Database.all_docs(**kwargs)

Return a `View` object referencing all documents in the database.
You can treat it like an iterator:

for doc in db.all_docs():
print doc

<a name="Database.changes"></a>
#### Database.changes(**kwargs)

Gets a list of the changes made to the database.
This can be used to monitor for update and modifications to the database
for post processing or synchronization.

Automatically adjusts the request to handle the different response behavior
of polling, longpolling, and continuous modes.

For more information about the `_changes` feed, see
[the docs](http://docs.cloudant.com/api/database.html#obtaining-a-list-of-changes).

<a name="Database.delete"></a>
#### Database.delete(path, **kwargs)

Make a DELETE request against the object's URI joined
with `path`. `kwargs` are passed directly to Requests.

<a name="Database.document"></a>
#### Database.document(name, **kwargs)

Create a `Document` object from `name`.

<a name="Database.get"></a>
#### Database.get(path, **kwargs)

Make a GET request against the object's URI joined
with `path`. `kwargs` are passed directly to Requests.

<a name="Database.missing_revs"></a>
#### Database.missing_revs(revs, **kwargs)

Refers to [this method](http://docs.cloudant.com/api/database.html#retrieving-missing-revisions).

<a name="Database.post"></a>
#### Database.post(path, **kwargs)

Make a POST request against the object's URI joined
with `path`.

`kwargs['params']` are turned into JSON before being
passed to Requests. If you want to indicate the message
body without it being modified, use `kwargs['data']`.

<a name="Database.put"></a>
#### Database.put(path, **kwargs)

Make a PUT request against the object's URI joined
with `path`.

`kwargs['params']` are turned into JSON before being
passed to Requests. If you want to indicate the message
body without it being modified, use `kwargs['data']`.

<a name="Database.revs_diff"></a>
#### Database.revs_diff(revs, **kwargs)

Refers to [this method](http://docs.cloudant.com/api/database.html#retrieving-differences-between-revisions)

<a name="Database.save_docs"></a>
#### Database.save_docs(**kwargs)

Save many docs, all at once. Each `doc` argument must be a dict, like this:

db.save_docs({...}, {...}, {...})
# saves all documents in one HTTP request

<a name="Database.view_cleanup"></a>
#### Database.view_cleanup(**kwargs)

Cleans up the cached view output on disk for a given view. For example:

print db.view_cleanup().result().json()
# {'ok': True}

<a name="Document"></a>
### Document(uri, **kwargs)

Connection to a specific document.

Learn more about the raw API from the [Cloudant docs](http://docs.cloudant.com/api/documents.html)

<a name="Document.attachment"></a>
#### Document.attachment(name, **kwargs)

Create an `Attachment` object from `name` and the settings
for the current database.

<a name="Document.delete"></a>
#### Document.delete(rev, **kwargs)

Delete the given revision of the current document. For example:

rev = doc.get().result().json()['_rev']
doc.delete(rev)

<a name="Document.get"></a>
#### Document.get(path, **kwargs)

Make a GET request against the object's URI joined
with `path`. `kwargs` are passed directly to Requests.

<a name="Document.merge"></a>
#### Document.merge(change, **kwargs)

Merge `change` into the document,
and then `PUT` the updated document back to the server.

<a name="Document.post"></a>
#### Document.post(path, **kwargs)

Make a POST request against the object's URI joined
with `path`.

`kwargs['params']` are turned into JSON before being
passed to Requests. If you want to indicate the message
body without it being modified, use `kwargs['data']`.

<a name="Document.put"></a>
#### Document.put(path, **kwargs)

Make a PUT request against the object's URI joined
with `path`.

`kwargs['params']` are turned into JSON before being
passed to Requests. If you want to indicate the message
body without it being modified, use `kwargs['data']`.

<a name="Document.view"></a>
#### Document.view(method, function, **kwargs)

Create a `View` object by joining `method` and `function`. For example:

view = doc.view('_view', 'index-name')
# refers to /DB/_design/DOC/_view/index-name

<a name="View"></a>
### View(uri, **kwargs)

Methods for design document indexes and special methods.
Different kinds of indexes / methods will behave differently, so here are helpful docs:

* [Lucene search indexes](http://docs.cloudant.com/api/search.html#searching-for-documents-using-lucene-queries)
* [Secondary indexes / "views"](http://docs.cloudant.com/api/design-documents-querying-views.html#querying-a-view)
* [List functions](http://docs.cloudant.com/api/design-documents-shows-lists.html#querying-list-functions)
* [Show functions](http://docs.cloudant.com/api/design-documents-shows-lists.html#querying-show-functions)

Then, you just use basic HTTP methods to perform queries, like this:

view.get(params=QUERY_ARGUMENTS)

Remember, before you can query an index, you have to make sure it's in your database.
See [these docs](http://docs.cloudant.com/api/design-documents-get-put-delete-copy.html#creating-or-updating-a-design-document)
for how to do that.

<a name="View.delete"></a>
#### View.delete(path, **kwargs)

Make a DELETE request against the object's URI joined
with `path`. `kwargs` are passed directly to Requests.

<a name="View.get"></a>
#### View.get(path, **kwargs)

Make a GET request against the object's URI joined
with `path`. `kwargs` are passed directly to Requests.

<a name="View.post"></a>
#### View.post(path, **kwargs)

Make a POST request against the object's URI joined
with `path`.

`kwargs['params']` are turned into JSON before being
passed to Requests. If you want to indicate the message
body without it being modified, use `kwargs['data']`.

<a name="View.put"></a>
#### View.put(path, **kwargs)

Make a PUT request against the object's URI joined
with `path`.

`kwargs['params']` are turned into JSON before being
passed to Requests. If you want to indicate the message
body without it being modified, use `kwargs['data']`.

<a name="Attachment"></a>
### Attachment(uri, **kwargs)

Attachment methods for a single document

<a name="Attachment.delete"></a>
#### Attachment.delete(path, **kwargs)

Make a DELETE request against the object's URI joined
with `path`. `kwargs` are passed directly to Requests.

<a name="Attachment.get"></a>
#### Attachment.get(path, **kwargs)

Make a GET request against the object's URI joined
with `path`. `kwargs` are passed directly to Requests.

<a name="Attachment.post"></a>
#### Attachment.post(path, **kwargs)

Make a POST request against the object's URI joined
with `path`.

`kwargs['params']` are turned into JSON before being
passed to Requests. If you want to indicate the message
body without it being modified, use `kwargs['data']`.

<a name="Attachment.put"></a>
#### Attachment.put(path, **kwargs)

Make a PUT request against the object's URI joined
with `path`.

`kwargs['params']` are turned into JSON before being
passed to Requests. If you want to indicate the message
body without it being modified, use `kwargs['data']`.


## Testing

To run Cloudant.py's tests, just do:

python setup.py test

## Documentation

The API reference is automatically generated from the docstrings of each class and its methods. To install Cloudant.py with the necessary extensions to build the docs, do this:

pip install -e cloudant[docs]

Then, in Cloudant.py's root directory, do this:

python docs

Note: docstrings are in [Markdown](http://daringfireball.net/projects/markdown/).

## License

[MIT](http://opensource.org/licenses/MIT), yo.