{"id":2065,"library":"ibmcloudant","title":"IBM Cloudant Python SDK","description":"The IBM Cloudant Python SDK is an actively maintained client library for interacting with IBM Cloudant APIs. Currently at version 0.11.5, it offers a unified IBM Cloud SDK experience, handles various authentication types, and provides a thread-safe client. While considered production-ready, it is still in a 0.x release series, meaning API changes may occur before its 1.0 release. It receives frequent patch releases.","status":"active","version":"0.11.5","language":"en","source_language":"en","source_url":"https://github.com/IBM/cloudant-python-sdk","tags":["IBM Cloud","Cloudant","NoSQL","database","SDK","client"],"install":[{"cmd":"pip install ibmcloudant","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.10 or above.","package":"python","optional":false},{"reason":"Core functionalities shared across IBM Cloud SDKs.","package":"ibm-cloud-sdk-core","optional":false},{"reason":"HTTP client library for making requests.","package":"requests","optional":false},{"reason":"JSON Web Token support.","package":"pyjwt","optional":false},{"reason":"Date and time utilities.","package":"python-dateutil","optional":false}],"imports":[{"note":"The `cloudant` library is the old, End-of-Life Python Cloudant client. `ibmcloudant` is its replacement.","wrong":"from cloudant.client import Cloudant","symbol":"CloudantV1","correct":"from ibmcloudant.cloudant_v1 import CloudantV1"},{"symbol":"IAMAuthenticator","correct":"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator"},{"symbol":"Document","correct":"from ibmcloudant.cloudant_v1 import Document"}],"quickstart":{"code":"import os\nfrom ibmcloudant.cloudant_v1 import CloudantV1\nfrom ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n\n# Retrieve credentials from environment variables (recommended)\nservice_url = os.environ.get('CLOUDANT_URL', 'YOUR_CLOUDANT_URL')\napi_key = os.environ.get('CLOUDANT_APIKEY', 'YOUR_IAM_API_KEY')\n\n# Ensure credentials are provided\nif not service_url or not api_key:\n    print(\"Error: CLOUDANT_URL and CLOUDANT_APIKEY environment variables must be set.\")\n    exit(1)\n\n# Authenticate and create client\nauthenticator = IAMAuthenticator(api_key)\nservice = CloudantV1(authenticator=authenticator)\nservice.set_service_url(service_url)\n\n# Example: List all databases\ntry:\n    all_dbs = service.get_all_dbs().get_result()\n    print(\"Databases:\")\n    for db in all_dbs:\n        print(f\"- {db}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize the Cloudant client using IAM authentication with environment variables and then lists all available databases. Ensure to replace placeholder environment variables with your actual IBM Cloudant service URL and IAM API Key."},"warnings":[{"fix":"Review applications using `AUTH_DISABLE_SSL` with `COUCHDB_SESSION` and adjust logic or environment settings as necessary.","message":"The behavior of the `AUTH_DISABLE_SSL` environment variable was fixed in v0.11.0, specifically impacting the `AUTH_TYPE=COUCHDB_SESSION` authenticator configuration. If you relied on the previous, incorrect behavior with this specific combination, your application might break.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Pin the `ibmcloudant` version in your `requirements.txt` or `pyproject.toml` (e.g., `ibmcloudant==0.11.5`).","message":"The SDK is still in a 0.x release series (e.g., 0.11.5). While considered production-ready, IBM explicitly states that APIs may be subject to change before the 1.0 release. It is highly recommended to pin your dependency version to avoid unexpected breaking changes.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Migrate your application to use `ibmcloudant`. This involves changing imports (e.g., from `cloudant.client` to `ibmcloudant.cloudant_v1`) and adapting to the new API structure as detailed in the official migration guide.","message":"The previous Python client library, `python-cloudant` (module name `cloudant`), is End-of-Life (EOL) and no longer supported. Users should migrate to `ibmcloudant`.","severity":"deprecated","affected_versions":"All versions of `python-cloudant`"},{"fix":"Refer to the `KNOWN_ISSUES.md` file in the GitHub repository or the official documentation for specific guidance on handling `application/json` attachments.","message":"There is a known issue regarding `application/json` attachments documented in v0.11.4 release notes. If working with attachments, consult the official documentation for details and potential workarounds.","severity":"gotcha","affected_versions":"All current 0.x versions"},{"fix":"Ensure `CLOUDANT_URL` and `CLOUDANT_APIKEY` (or other authentication-specific environment variables/programmatic arguments) are correctly set for your Cloudant instance. IAM authentication is generally recommended for IBM Cloudant.","message":"Authentication requires proper configuration of a service URL and Cloudant service credentials (e.g., API key, username/password). Incorrect or missing credentials are a common source of connection issues.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}