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.
pip install ibmcloudantVerified import paths — ran on the pinned version, not inferred.
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.
Review applications using `AUTH_DISABLE_SSL` with `COUCHDB_SESSION` and adjust logic or environment settings as necessary.
Pin the `ibmcloudant` version in your `requirements.txt` or `pyproject.toml` (e.g., `ibmcloudant==0.11.5`).
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.
Refer to the `KNOWN_ISSUES.md` file in the GitHub repository or the official documentation for specific guidance on handling `application/json` attachments.
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 the correct package and update your import statements to use `ibmcloudant`. If you still need the old `cloudant` package for legacy reasons, ensure it is installed alongside the new SDK in a compatible Python environment. ```python pip install --upgrade ibmcloudant # Replace old imports like: # from cloudant.client import Cloudant # with: from ibmcloudant.cloudant_v1 import CloudantV1 from ibm_cloud_sdk_core.authenticators import IAMAuthenticator ```
Verify that you are using the correct IBM Cloudant service URL and a valid IAM API key as your password, or the correct username/password if using legacy authentication. Ensure the API key has the required access policies for your Cloudant instance. ```python # Using IAM Authenticator (recommended for IBM Cloud) from ibmcloudant.cloudant_v1 import CloudantV1 from ibm_cloud_sdk_core.authenticators import IAMAuthenticator api_key = "YOUR_API_KEY" service_url = "YOUR_CLOUDANT_URL" authenticator = IAMAuthenticator(api_key) client = CloudantV1(authenticator=authenticator) client.set_service_url(service_url) # Or, for username/password (less common for new IBM Cloud instances): # from ibmcloudant.cloudant_v1 import CloudantV1 # from ibm_cloud_sdk_core.authenticators import BasicAuthenticator # # username = "YOUR_CLOUDANT_USERNAME" # password = "YOUR_CLOUDANT_PASSWORD" # service_url = "YOUR_CLOUDANT_URL" # # authenticator = BasicAuthenticator(username, password) # client = CloudantV1(authenticator=authenticator) # client.set_service_url(service_url) ```
Ensure that the `client.connect()` method is explicitly called, or pass `connect=True` during the client initialization, to establish the session before attempting any operations that require an active connection. ```python from ibmcloudant.cloudant_v1 import CloudantV1 from ibm_cloud_sdk_core.authenticators import IAMAuthenticator api_key = "YOUR_API_KEY" service_url = "YOUR_CLOUDANT_URL" authenticator = IAMAuthenticator(api_key) client = CloudantV1(authenticator=authenticator) client.set_service_url(service_url) # Explicitly connect after client initialization # client.connect() # (This method is more common in older `python-cloudant` library) # For `ibmcloudant`, operations inherently connect on first use or upon service URL setting. # However, if using older `cloudant` library, ensure `connect=True` during client instantiation # or call `client.connect()` before operations like `session = client.session()` # Example for older `cloudant` library: # from cloudant.client import CouchDB # client = CouchDB(username, password, url=service_url, connect=True) # session = client.session() ```
Access the actual document content via the `['doc']` key within each row of the query result.
```python
from ibmcloudant.cloudant_v1 import CloudantV1, PostAllDocsOptions
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
# ... (client initialization as above) ...
db_name = "your_database"
all_docs_options = PostAllDocsOptions(include_docs=True, limit=10)
response = client.post_all_docs(db=db_name, post_all_docs_options=all_docs_options).get_result()
for row in response['rows']:
if 'doc' in row:
document = row['doc']
print(f"Document ID: {document['_id']}, Content: {document}")
else:
print(f"Row without doc: {row}")
```