IBM Cloudant Python SDK

Warnings

• breaking 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.
  Fix: Review applications using `AUTH_DISABLE_SSL` with `COUCHDB_SESSION` and adjust logic or environment settings as necessary.
• gotcha 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.
  Fix: Pin the `ibmcloudant` version in your `requirements.txt` or `pyproject.toml` (e.g., `ibmcloudant==0.11.5`).
• deprecated The previous Python client library, `python-cloudant` (module name `cloudant`), is End-of-Life (EOL) and no longer supported. Users should migrate to `ibmcloudant`.
  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.
• gotcha 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.
  Fix: Refer to the `KNOWN_ISSUES.md` file in the GitHub repository or the official documentation for specific guidance on handling `application/json` attachments.
• gotcha 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.
  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.

Install

• pip install ibmcloudant Install latest version

Imports

• CloudantV1

  from ibmcloudant.cloudant_v1 import CloudantV1

  The `cloudant` library is the old, End-of-Life Python Cloudant client. `ibmcloudant` is its replacement.
• IAMAuthenticator

  from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

• Document

  from ibmcloudant.cloudant_v1 import Document

Quickstart

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.

import os
from ibmcloudant.cloudant_v1 import CloudantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Retrieve credentials from environment variables (recommended)
service_url = os.environ.get('CLOUDANT_URL', 'YOUR_CLOUDANT_URL')
api_key = os.environ.get('CLOUDANT_APIKEY', 'YOUR_IAM_API_KEY')

# Ensure credentials are provided
if not service_url or not api_key:
    print("Error: CLOUDANT_URL and CLOUDANT_APIKEY environment variables must be set.")
    exit(1)

# Authenticate and create client
authenticator = IAMAuthenticator(api_key)
service = CloudantV1(authenticator=authenticator)
service.set_service_url(service_url)

# Example: List all databases
try:
    all_dbs = service.get_all_dbs().get_result()
    print("Databases:")
    for db in all_dbs:
        print(f"- {db}")
except Exception as e:
    print(f"An error occurred: {e}")