Registry / database / ibmcloudant

ibmcloudant

JSON →
library0.11.10pypypi✓ verified 24d ago

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 ibmcloudant
INSTALL
IMPORT
SIG · IBMCLOUDANT
I
ibmcloudant
databasepythonv0.11.10
Install
2.6s avg
Import
498ms
Disk
23MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.11.10 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.516s · 24.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.6s · import 0.480s · 25MB
23MB installed
● package 23MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CloudantV1
from ibmcloudant.cloudant_v1 import CloudantV1
from cloudant.client import Cloudant
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

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}")
Debug
Known issues
breakingThe 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.
affects: >=0.11.0
gotchaThe 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`).
affects: <1.0.0
deprecatedThe 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.
affects: All versions of `python-cloudant`
gotchaThere 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.
affects: All current 0.x versions
gotchaAuthentication 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cloudant'
The Python SDK for IBM Cloudant transitioned from the `cloudant` package to `ibmcloudant`. This error occurs when code attempts to import the old, deprecated package.
fix
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
```
{ "error": "unauthorized", "reason": "Name or password is incorrect." }
This error indicates that the provided credentials (API key or username/password) for connecting to the IBM Cloudant service are incorrect or lack the necessary permissions. It can also occur if using legacy credentials with IAM-based authentication.
fix
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)
```
AttributeError: 'NoneType' object has no attribute 'info'
This error typically arises when attempting to access session or client information before the `ibmcloudant` client has successfully established a connection and authenticated with the Cloudant service. The client object, or a part of its internal session, is `None` because the connection step was skipped or failed.
fix
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()
```
Documents returned with 'includeDocs: true' do not contain full document bodies directly
When querying documents with `includeDocs: true`, the full document content is nested under a `doc` attribute within each row of the response, rather than being at the top level of the row object. Developers often expect the document to be directly accessible from the row itself.
fix
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}")
```
Upgrade
Version history
0.11.10latest on PyPI · released Aug 10, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or above.
ibm-cloud-sdk-corerequiredCore functionalities shared across IBM Cloud SDKs.
requestsrequiredHTTP client library for making requests.
pyjwtrequiredJSON Web Token support.
python-dateutilrequiredDate and time utilities.
Agent activity
29 hits · last 30 days
node
24
OpenAI (training)
1
Resources
ibmcloudant — pip install ibmcloudant · libregistry