As of 13 October 2015, this development repository is deprecated in favor of the new repository and development branch starting at version 2.0.0a1.
The new version will introduce breaking changes. No attempt was made to follow the API in 0.5.10.
This is the final version of this repository and branch -- 0.5.10.
Please use the new library for your new projects and begin to migrate your old projects that have used versions 0.5.10 and prior.
We will keep 0.5.10 as the latest stable version on PyPI until early 2016, at which time we plan to switch over completely to 2.0.0. Also at that time, this repository will be taken down.
Alpha and Beta versions starting with 2.0.0a1 will be uploaded to PyPI. The latest alpha or beta release may be installed by
pip install --pre cloudant
Note that our new development repository is still pre 2.0.0. As such, we cannot make any guarantees, though we will try, of course, not to introduce new API that will later be removed.
pip install cloudant
Cloudant-Python is a wrapper around Python Requests for interacting with CouchDB or Cloudant instances. Check it out:
importcloudant# connect to your account# in this case, https://garbados.cloudant.comUSERNAME='garbados'account=cloudant.Account(USERNAME)
# login, so we can make changeslogin=account.login(USERNAME, PASSWORD)
assertlogin.status_code==200# create a database objectdb=account.database('test')
# now, create the database on the serverresponse=db.put()
printresponse.json()
# {'ok': True}HTTP requests return Response objects, right from Requests.
Cloudant-Python can also make asynchronous requests by passing async=True to an object's constructor, like so:
importcloudant# connect to your account# in this case, https://garbados.cloudant.comUSERNAME='garbados'account=cloudant.Account(USERNAME, async=True)
# login, so we can make changesfuture=account.login(USERNAME, PASSWORD)
# block until we get the response bodylogin=future.result()
assertlogin.status_code==200Asynchronous HTTP requests return Future objects, which will await the return of the HTTP response. Call result() to get the Response object.
See the API reference for all the details you could ever want.
Cloudant-Python is minimal, performant, and effortless. Check it out:
Cloudant and CouchDB expose REST APIs that map easily into native Python objects. As much as possible, Cloudant-Python uses native Python objects as shortcuts to the raw API, so that such convenience never obscures what's going on underneath. For example:
importcloudant# connect to http://localhost:5984account=cloudant.Account()
db=account.database('test')
same_db=account['test']
assertdb.uri==same_db.uri# TrueCloudant-Python 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:
importcloudantaccount=cloudant.Account('garbados')
db_name='test'db=account.database(db_name)
doc=db.document('test_doc')
# create the documentresp=doc.put(params={
'_id': 'hello_world',
'herp': 'derp'
})
# delete the documentrev=resp.json()['_rev']
doc.delete(rev).raise_for_status()
# but this also creates a documentdb['hello_world'] = {'herp': 'derp'}
# and this deletes the databasedelaccount[db_name]Indexes, such as views and Cloudant's search indexes, act as iterators. Check it out:
importcloudantaccount=cloudant.Account('garbados')
db=account.database('test')
view=db.all_docs() # returns all docs in the databasefordocindb:
# iterates over every doc in the databasepassfordocinview:
# and so does this!passfordocinview.iter(descending=True):
# use `iter` to pass options to a view and then iterate over thempassBehind the scenes, Cloudant-Python yields documents only as you consume them, so you only load into memory the documents you're using.
If CouchDB has a special endpoint for something, it's in Cloudant-Python as a special method, so any special circumstances are taken care of automagically. As a rule, any endpoint like _METHOD is in Cloudant-Python as Object.METHOD. For example:
https://garbados.cloudant.com/_all_dbs->Account('garbados').all_dbs()http://localhost:5984/DB/_all_docs->Account().database(DB).all_docs()http://localhost:5984/DB/_design/DOC/_view/INDEX->Account().database(DB).design(DOC).view(INDEX)
If you instantiate an object with the async=True option, its HTTP request methods (such as get and post) will 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 get the Response object (waiting until it arrives if necessary) use the result method, like so:
importcloudantaccount=cloudant.Account(async=True)
db=account['test']
future=db.put()
response=future.result()
printdb.get().result().json()
# {'db_name': 'test', ...}As a result, any methods which must make an HTTP request return a Future object.
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 Account.database to inherit cookies and other settings from the Account object. For example:
importcloudantaccount=cloudant.Account('garbados')
db=account.database('test')
doc=db.document('test_doc')
url='https://garbados.cloudant.com'path='/test/test_doc'otherdoc=cloudant.Document(url+path)
assertdoc.uri==otherdoc.uri# TrueTo run Cloudant-Python's tests, just do:
python setup.py test
The API reference is automatically generated from the docstrings of each class and its methods. To install Cloudant-Python with the necessary extensions to build the docs, do this:
pip install -e cloudant[docs]
Then, in Cloudant-Python's root directory, do this:
python docs
Note: docstrings are in Markdown.
MIT, yo.