{"id":7087,"library":"cloudant","title":"Cloudant Python Client Library","description":"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.","status":"maintenance","version":"2.15.0","language":"en","source_language":"en","source_url":"https://github.com/cloudant/python-cloudant","tags":["cloudant","couchdb","database","ibmcloud","nosql"],"install":[{"cmd":"pip install cloudant","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for HTTP communication with the Cloudant/CouchDB API.","package":"requests","optional":false}],"imports":[{"symbol":"Cloudant","correct":"from cloudant.client import Cloudant"},{"note":"Exceptions are in `cloudant.error`, not `cloudant.exceptions`.","wrong":"from cloudant.exceptions import CloudantException","symbol":"CloudantException","correct":"from cloudant.error import CloudantException"},{"symbol":"Result","correct":"from cloudant.result import Result"}],"quickstart":{"code":"from cloudant.client import Cloudant\nfrom cloudant.error import CloudantException\nimport os\n\n# Configure credentials using environment variables\nCLOUDANT_USERNAME = os.environ.get('CLOUDANT_USERNAME', 'testuser_example')\nCLOUDANT_PASSWORD = os.environ.get('CLOUDANT_PASSWORD', 'testpass_example')\nCLOUDANT_URL = os.environ.get('CLOUDANT_URL', 'http://localhost:5984') # Default for local CouchDB\n\nclient = None\ntry:\n    # Connect to the Cloudant service\n    client = Cloudant(CLOUDANT_USERNAME,\n                      CLOUDANT_PASSWORD,\n                      url=CLOUDANT_URL,\n                      connect=True)\n\n    print(f\"Connected to Cloudant/CouchDB at {CLOUDANT_URL}\")\n    session = client.session()\n    print(f\"User: {session['userCtx']['name']}\")\n\n    db_name = 'my_sample_database'\n    # Attempt to create a database\n    my_database = client.create_database(db_name)\n\n    if my_database.exists():\n        print(f\"Database '{db_name}' created or already exists.\")\n\n        # Create a document\n        doc_data = {'name': 'Alice', 'city': 'New York', 'age': 30}\n        new_document = my_database.create_document(doc_data)\n\n        if new_document.exists():\n            print(f\"Document created with ID: {new_document['_id']}\")\n            print(f\"Current document content: {new_document}\")\n\n            # Fetch the document by ID\n            fetched_document = my_database[new_document['_id']]\n            print(f\"Fetched document content: {fetched_document}\")\n\n            # Update the document (requires fetching it first to get the _rev)\n            fetched_document['age'] = 31\n            fetched_document['status'] = 'active'\n            fetched_document.save()\n            print(f\"Updated document content: {my_database[new_document['_id']]}\")\n\n            # Delete the document\n            fetched_document.delete()\n            print(f\"Document '{new_document['_id']}' deleted.\")\n\n    # Delete the database\n    if client.get_database(db_name).exists():\n        client.delete_database(db_name)\n        print(f\"Database '{db_name}' deleted.\")\n\nexcept CloudantException as ce:\n    print(f\"Cloudant Error: {ce}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if client:\n        client.disconnect()\n        print(\"Disconnected from Cloudant service.\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"The `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).","severity":"deprecated","affected_versions":"All versions (since 2.15.0 was the last release)"},{"fix":"Always fetch the document before modifying and saving it. For example: `doc = db[doc_id]`; `doc['field'] = 'new_value'`; `doc.save()`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"< 2.12.0"},{"fix":"If connecting to an IBM Cloudant service that uses IAM authentication, ensure you are using `cloudant` version 2.11.0 or newer.","message":"IAM (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.","severity":"breaking","affected_versions":"< 2.11.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add `from cloudant.client import Cloudant` at the top of your script.","cause":"The main Cloudant client class has not been imported.","error":"NameError: name 'Cloudant' is not defined"},{"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.","cause":"The provided credentials (username/password or API key) do not have sufficient permissions to perform the requested operation on the database or instance.","error":"cloudant.error.CloudantException: forbidden (reason='_reader access is required for this request')"},{"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.","cause":"The specified database name either does not exist or is misspelled. This can also occur if the user lacks permissions to list databases.","error":"cloudant.error.CloudantException: not_found (reason='Database does not exist.')"},{"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.","cause":"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.","error":"TypeError: 'builtin_function_or_method' object is not subscriptable (when accessing document fields like `doc['field']`)"}]}