Install & Compatibility
Where this runs
tested against v2.15.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.660s · 21.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.1s · import 0.594s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Cloudant
✓ from cloudant.client import Cloudant
CloudantException
✓ from cloudant.error import CloudantException
✗ from cloudant.exceptions import CloudantException
Exceptions are in `cloudant.error`, not `cloudant.exceptions`.
Result
✓ from cloudant.result import Result
This quickstart demonstrates how to connect to a Cloudant/CouchDB instance, create a database, create, fetch, update, and delete a document, and finally delete the database. It uses environment variables for credentials, ensuring sensitive information is not hardcoded. Remember to replace placeholder values with your actual Cloudant credentials or a local CouchDB URL.
from cloudant.client import Cloudant
from cloudant.error import CloudantException
import os
# Configure credentials using environment variables
CLOUDANT_USERNAME = os.environ.get('CLOUDANT_USERNAME', 'testuser_example')
CLOUDANT_PASSWORD = os.environ.get('CLOUDANT_PASSWORD', 'testpass_example')
CLOUDANT_URL = os.environ.get('CLOUDANT_URL', 'http://localhost:5984') # Default for local CouchDB
client = None
try:
# Connect to the Cloudant service
client = Cloudant(CLOUDANT_USERNAME,
CLOUDANT_PASSWORD,
url=CLOUDANT_URL,
connect=True)
print(f"Connected to Cloudant/CouchDB at {CLOUDANT_URL}")
session = client.session()
print(f"User: {session['userCtx']['name']}")
db_name = 'my_sample_database'
# Attempt to create a database
my_database = client.create_database(db_name)
if my_database.exists():
print(f"Database '{db_name}' created or already exists.")
# Create a document
doc_data = {'name': 'Alice', 'city': 'New York', 'age': 30}
new_document = my_database.create_document(doc_data)
if new_document.exists():
print(f"Document created with ID: {new_document['_id']}")
print(f"Current document content: {new_document}")
# Fetch the document by ID
fetched_document = my_database[new_document['_id']]
print(f"Fetched document content: {fetched_document}")
# Update the document (requires fetching it first to get the _rev)
fetched_document['age'] = 31
fetched_document['status'] = 'active'
fetched_document.save()
print(f"Updated document content: {my_database[new_document['_id']]}")
# Delete the document
fetched_document.delete()
print(f"Document '{new_document['_id']}' deleted.")
# Delete the database
if client.get_database(db_name).exists():
client.delete_database(db_name)
print(f"Database '{db_name}' deleted.")
except CloudantException as ce:
print(f"Cloudant Error: {ce}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
finally:
if client:
client.disconnect()
print("Disconnected from Cloudant service.")
Debug
Known issues
deprecatedThe `cloudant` Python library is no longer under active development. As of October 2021, customers are encouraged to use the `python-couchdb` library instead, as it is actively maintained and provides a similar interface for CouchDB (and by extension, Cloudant).fixFor new projects, consider using `pip install python-couchdb`. For existing projects, be aware that no further updates or bug fixes are expected for `cloudant`.
affects: All versions (since 2.15.0 was the last release)
gotchaWhen updating an existing document, you must first fetch the document to obtain its `_rev` field. Cloudant/CouchDB requires this revision ID for all update and delete operations to prevent conflicts.fixAlways fetch the document before modifying and saving it. For example: `doc = db[doc_id]`; `doc['field'] = 'new_value'`; `doc.save()`.
affects: All versions
gotchaThe `Document` context manager (e.g., `with my_database['doc_id'] as doc:`) in versions prior to 2.12.0 could perform a remote save even if an uncaught exception occurred within the `with` block, leading to unintended data writes.fixUpgrade to `cloudant` version 2.12.0 or newer to ensure correct behavior where saves only occur on successful exit from the `with` block. Alternatively, manually manage document saves outside the context manager.
affects: < 2.12.0
breakingIAM (Identity and Access Management) authentication for IBM Cloudant was introduced in version 2.11.0. Older versions of the `cloudant` library will not support connecting to Cloudant instances that require IAM tokens.fixIf connecting to an IBM Cloudant service that uses IAM authentication, ensure you are using `cloudant` version 2.11.0 or newer.
affects: < 2.11.0
Errors
Common errors & fixes
NameError: name 'Cloudant' is not defined
The main Cloudant client class has not been imported.
fixAdd `from cloudant.client import Cloudant` at the top of your script.
cloudant.error.CloudantException: forbidden (reason='_reader access is required for this request')
The provided credentials (username/password or API key) do not have sufficient permissions to perform the requested operation on the database or instance.
fixVerify that your Cloudant service credentials have the necessary read/write/admin permissions for the database or account you are trying to access. Check the IAM access policies in your IBM Cloud account.
cloudant.error.CloudantException: not_found (reason='Database does not exist.')
The specified database name either does not exist or is misspelled. This can also occur if the user lacks permissions to list databases.
fixDouble-check the database name for typos. Ensure the database exists or create it using `client.create_database('my_db_name')` if appropriate and your credentials have permission. TypeError: 'builtin_function_or_method' object is not subscriptable (when accessing document fields like `doc['field']`)
You might be trying to access document fields on a `Document` object that has not been properly initialized or fetched, or you're confusing it with a dict-like object.
fixEnsure `doc` is a valid `Document` object, usually obtained by `my_database.create_document()` or `my_database[doc_id]`. If `doc` is a fresh `Document` object created without data or a fetch, it might not behave as expected until `save()` or `fetch()` is called.
Upgrade
Version history
2.15.0latest on PyPI · released Aug 26, 2021
Audit
Dependencies
requestsrequiredUsed for HTTP communication with the Cloudant/CouchDB API.