Registry / database / cloudant

cloudant

JSON →
library2.15.0pypypi✓ verified 86d ago

The `cloudant` Python client library provides a convenient interface for interacting with IBM Cloudant and Apache CouchDB databases. It allows developers to perform common database operations such as creating/deleting databases, managing documents, querying views, and using Cloudant-specific features. The library's last major release was 2.15.0 in August 2021, and it is currently in maintenance mode with no active development.

pip install cloudant
INSTALL
IMPORT
SIG · CLOUDANT
C
cloudant
databasepythonv2.15.0
Install
2.1s avg
Import
627ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.660s · 21.8MB
glibc
py 3.103.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).
fix
For 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.
fix
Always 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.
fix
Upgrade 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.
fix
If 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.
fix
Add `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.
fix
Verify 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.
fix
Double-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.
fix
Ensure `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.
Agent activity
18 hits · last 30 days
node
14
OpenAI (training)
1
Resources
cloudant — pip install cloudant · libregistry