Cloudant client library API

Cloudant / CouchDB Python client library API package

cloudant.cloudant(user, passwd, **kwargs)

Provides a context manager to create a Cloudant session and provide access to databases, docs etc.

Parameters:
  • user (str) – Username used to connect to Cloudant.
  • passwd (str) – Authentication token used to connect to Cloudant.
  • account (str) – The Cloudant account name. If the account parameter is present, it will be used to construct the Cloudant service URL.
  • url (str) – If the account is not present and the url parameter is present then it will be used to set the Cloudant service URL. The url must be a fully qualified http/https URL.
  • x_cloudant_user (str) – Override the X-Cloudant-User setting used to authenticate. This is needed to authenticate on one’s behalf, eg with an admin account. This parameter must be accompanied by the url parameter. If the url parameter is omitted then the x_cloudant_user parameter setting is ignored.
  • encoder (str) – Optional json Encoder object used to encode documents for storage. Defaults to json.JSONEncoder.

For example:

# cloudant context manager
from cloudant import cloudant

with cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME) as client:
    # Context handles connect() and disconnect() for you.
    # Perform library operations within this context.  Such as:
    print client.all_dbs()
    # ...
cloudant.cloudant_bluemix(vcap_services, instance_name=None, service_name=None, **kwargs)

Provides a context manager to create a Cloudant session and provide access to databases, docs etc.

Parameters:
  • vcap_services (dict or str) – VCAP_SERVICES environment variable
  • instance_name (str) – Optional Bluemix instance name. Only required if multiple Cloudant instances are available.
  • service_name (str) – Optional Bluemix service name.
  • encoder (str) – Optional json Encoder object used to encode documents for storage. Defaults to json.JSONEncoder.

Loads all configuration from the specified VCAP_SERVICES Cloud Foundry environment variable. The VCAP_SERVICES variable contains connection information to access a service instance. For example:

{
    "VCAP_SERVICES": {
        "cloudantNoSQLDB": [
            {
                "credentials": {
                    "apikey": "some123api456key"
                    "username": "example",
                    "password": "xxxxxxx",
                    "host": "example.cloudant.com",
                    "port": 443,
                    "url": "https://example:xxxxxxx@example.cloudant.com"
                },
                "syslog_drain_url": null,
                "label": "cloudantNoSQLDB",
                "provider": null,
                "plan": "Lite",
                "name": "Cloudant NoSQL DB"
            }
        ]
    }
}

See Cloud Foundry Environment Variables.

Example usage:

import os

# cloudant_bluemix context manager
from cloudant import cloudant_bluemix

with cloudant_bluemix(os.getenv('VCAP_SERVICES'), 'Cloudant NoSQL DB') as client:
    # Context handles connect() and disconnect() for you.
    # Perform library operations within this context.  Such as:
    print client.all_dbs()
    # ...
cloudant.cloudant_iam(account_name, api_key, **kwargs)

Provides a context manager to create a Cloudant session using IAM authentication and provide access to databases, docs etc.

Parameters:
  • account_name – Cloudant account name.
  • api_key – IAM authentication API key.

For example:

# cloudant context manager
from cloudant import cloudant_iam

with cloudant_iam(ACCOUNT_NAME, API_KEY) as client:
    # Context handles connect() and disconnect() for you.
    # Perform library operations within this context.  Such as:
    print client.all_dbs()
    # ...
cloudant.couchdb(user, passwd, **kwargs)

Provides a context manager to create a CouchDB session and provide access to databases, docs etc.

Parameters:
  • user (str) – Username used to connect to CouchDB.
  • passwd (str) – Passcode used to connect to CouchDB.
  • url (str) – URL for CouchDB server.
  • encoder (str) – Optional json Encoder object used to encode documents for storage. Defaults to json.JSONEncoder.

For example:

# couchdb context manager
from cloudant import couchdb

with couchdb(USERNAME, PASSWORD, url=COUCHDB_URL) as client:
    # Context handles connect() and disconnect() for you.
    # Perform library operations within this context.  Such as:
    print client.all_dbs()
    # ...
cloudant.couchdb_admin_party(**kwargs)

Provides a context manager to create a CouchDB session in Admin Party mode and provide access to databases, docs etc.

Parameters:
  • url (str) – URL for CouchDB server.
  • encoder (str) – Optional json Encoder object used to encode documents for storage. Defaults to json.JSONEncoder.

For example:

# couchdb_admin_party context manager
from cloudant import couchdb_admin_party

with couchdb_admin_party(url=COUCHDB_URL) as client:
    # Context handles connect() and disconnect() for you.
    # Perform library operations within this context.  Such as:
    print client.all_dbs()
    # ...