ibmcloudant
Python client library for IBM Cloudant
Description
[](https://github.com/IBM/cloudant-python-sdk/actions/workflows/test.yml) [](https://github.com/IBM/cloudant-python-sdk/releases/latest) [](https://ibm.github.io/cloudant-python-sdk/) # IBM Cloudant Python SDK Version 0.11.5 IBM Cloudant Python SDK is a client library that interacts with the [IBM Cloudant APIs](https://cloud.ibm.com/apidocs/cloudant?code=python). Disclaimer: This library is still a 0.x release. We do consider this library production-ready and capable, but there are still some limitations we’re working to resolve, and refinements we want to deliver. We are working really hard to minimise the disruption from now until the 1.0 release, but there may still be some changes that impact applications using this SDK. For now, be sure to pin versions to avoid surprises. <details> <summary>Table of Contents</summary> <!-- toc --> - [Overview](#overview) - [Features](#features) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Using the SDK](#using-the-sdk) * [Authentication](#authentication) * [Automatic retries](#automatic-retries) * [Request timeout configuration](#request-timeout-configuration) * [Code examples](#code-examples) * [Error handling](#error-handling) * [Raw IO](#raw-io) * [Model classes vs dictionaries](#model-classes-vs-dictionaries) * [Further resources](#further-resources) - [Questions](#questions) - [Issues](#issues) - [Versioning and LTS support](#versioning-and-lts-support) - [Open source at IBM](#open-source-at-ibm) - [Contributing](#contributing) - [License](#license) </details> ## Overview The IBM Cloudant Python SDK allows developers to programmatically interact with [IBM Cloudant](https://cloud.ibm.com/apidocs/cloudant) with the help of the `ibmcloudant` package. ## Features The purpose of this Python SDK is to wrap most of the HTTP request APIs provided by Cloudant and supply other functions to ease the usage of Cloudant. This SDK should make life easier for programmers to do what’s really important to them: developing software. Reasons why you should consider using Cloudant Python SDK in your project: - Supported by IBM Cloudant. - Server compatibility with: - IBM Cloudant. - [Apache CouchDB 3.x](https://docs.couchdb.org/en/stable/) for data operations. - Includes all the most popular and latest supported endpoints for applications. - Handles the authentication. - Familiar user experience with IBM Cloud SDKs. - Flexibility to use either built-in models or byte-based requests and responses for documents. - Built-in [Changes feed follower](https://github.com/IBM/cloudant-python-sdk/tree/v0.11.5/docs/Changes_Follower.md) - Built-in [Pagination](https://github.com/IBM/cloudant-python-sdk/tree/v0.11.5/docs/Pagination.md) - Instances of the client are unconditionally thread-safe. ## Prerequisites - A [Cloudant](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-getting-started-with-cloudant) service instance or a [CouchDB](https://docs.couchdb.org/en/latest/install/index.html) server. - Python 3.10, 3.11, 3.12, 3.13 or 3.14 ## Installation To install, use `pip` or `easy_install`: ```bash pip install --upgrade "ibmcloudant>=0.11.5" ``` or ```bash easy_install --upgrade "ibmcloudant>=0.11.5" ``` ## Using the SDK For fundamental SDK usage information and config options, please see the common [IBM Cloud SDK](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.md) documentation. This library requires configuration with a service URL and [Cloudant service credentials][service-credentials] to authenticate with your account. There are several ways to **set** these authentication properties: 1. As [environment variables](https://github.com/IBM/cloudant-python-sdk/tree/v0.11.5/docs/Authentication.md#authentication-with-environment-variables) 2. The [programmatic approach](https://github.com/IBM/cloudant-python-sdk/tree/v0.11.5/docs/Authentication.md#programmatic-authentication) 3. With an [external credentials file](https://github.com/IBM/cloudant-python-sdk/tree/v0.11.5/docs/Authentication.md#authentication-with-external-configuration) The following section describes the different authentication types and provides environment variable examples. Examples for other configuration methods are available by following the provided links. ### Authentication Consult the [authentication document](https://github.com/IBM/cloudant-python-sdk/tree/v0.11.5/docs/Authentication.md) for comprehensive details of all the available authentication methods and how to configure them with environment settings or programmatically. Quick start for Cloudant with an IAM API key: ```sh CLOUDANT_URL=https://~replace-with-cloudant-host
Release History
| Version | Changes | Urgency | Date |
|---|---|---|---|
| 0.11.5 | Imported from PyPI (0.11.5) | Low | 4/21/2026 |
| v0.11.5 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Updated documentation. | Low | 3/17/2026 |
| v0.11.4 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Pagination feature is no longer marked as beta. * Documented known issue about `application/json` attachments. | Low | 2/9/2026 |
| v0.11.3 | **Note: APIs may be subject to change.** Changes: * Fixed missing capability to set the default analyzer for `perfield` analyzers. * Updated dependencies. * Updated documentation. | Low | 1/15/2026 |
| v0.11.2 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Updated documentation. | Low | 12/2/2025 |
| v0.11.1 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Updated documentation. _Runtime changes_: * Added Python 3.14 to supported versions. | Low | 11/5/2025 |
| v0.11.0 | **Note: APIs may be subject to change.** _Breaking Changes_: * Fixed the `AUTH_DISABLE_SSL` environment variable from impacting the `AUTH_TYPE=COUCHDB_SESSION` authenticator configuration. Note there is no effect if you did not use this configuration combination. Changes: * Updated dependencies. * Updated documentation. | Low | 10/8/2025 |
| v0.10.7 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Updated documentation. | Low | 9/12/2025 |
| v0.10.6 | **Note: APIs may be subject to change.** Changes: * Fixed behavior of nullable required properties in responses. * Updated dependencies. * Updated documentation. | Low | 8/27/2025 |
| v0.10.5 | **Note: APIs may be subject to change.** New features: * [Pagination (beta)](https://github.com/IBM/cloudant-python-sdk/tree/v0.10.5#pagination-beta) - convenience APIs for paginating documents, queries, searches and views. Changes: * Changes follower feature is no longer considered beta. * Updated dependencies. * Updated documentation. | Low | 7/18/2025 |
| v0.10.4 | **Note: APIs may be subject to change.** Changes: * Updated `requests` dependency version minimum to latest `2.32.4`. | Low | 6/11/2025 |
| v0.10.3 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. | Low | 6/4/2025 |
| v0.10.2 | **Note: APIs may be subject to change.** Changes: * Added constant for the `simple_asciifolding` text analyzer. * Improved changes follower to avoid polling waits in one-off usage case. * Updated dependencies. * Updated documentation. | Low | 4/24/2025 |
| v0.10.1 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Add operations for `/_api/v2/user/current/databases` and `/_api/v2/user/capacity/databases` APIs. | Low | 3/10/2025 |
| v0.10.0 | **Note: APIs may be subject to change.** _Breaking Changes_: * Corrected mapping level of faceted search ranges API model. The existing model was incorrect and resulted in unsuccessful requests. As such this API change should have no impact. * Corrected sort direction values in explain map reduce options model. This is unlikely to break callers as the string value is returned. Changes: * Added `GET` `/{db}/_design/{ddoc}/_search_disk_size/{index}` operation. * Added `POST` `_replicato | Low | 1/15/2025 |
| v0.9.3 | **Note: APIs may be subject to change.** Changes: * Added new allow fallback option to find query options models. * Fixed setting of `since` parameter in changes follower. * Improved error message output and added trace ID to error responses. * Updated dependencies. * Updated documentation. | Low | 11/8/2024 |
| v0.9.2 | **Note: APIs may be subject to change.** Changes: * Improved validation of properties. * Updated dependencies. * Updated documentation. | Low | 9/20/2024 |
| v0.9.1 | **Note: APIs may be subject to change.** Changes: * Updated `ibm-cloud-sdk-core` to `3.20.3` to workaround issues when using `requests==2.32.3`. | Low | 7/11/2024 |
| v0.9.0 | **Note: APIs may be subject to change.** _Breaking Changes_: * The default service URL changed from `http://localhost:5984` to `https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud`. This change is only breaking for users that do not configure the client with a URL and connect to a local server running on port `5984` (for example a test CouchDB server). Changes: * Add missing `owner` field for replication documents. * Allow retrieval of additional vendor properties from | Low | 7/10/2024 |
| v0.8.2 | **Note: APIs may be subject to change.** Changes: * Add `instance_start_time` to detect database recreation in database information model. * Updated dependencies. * Avoid `requests==2.32.3` that is incompatible with `ibm-cloud-sdk-core<=3.20.0` and causes certificate errors. | Low | 6/4/2024 |
| v0.8.1 | **Note: APIs may be subject to change.** Changes: * New model extensions for `_explain` index analysis. * Removed incorrect `accept` header parameter from `POST /{db}/_design_docs`. * Updated dependencies. * Updated documentation. | Low | 5/7/2024 |
| v0.8.0 | **Note: APIs may be subject to change.** _Breaking Changes_: * For the full list of code changes needed for this version see [`0.8.0` API changes](https://github.com/IBM/cloudant-python-sdk/blob/main/api-changes.md#080) * Preserve leading `_` metadata names in models that also accept user-defined properties (i.e. documents) to eliminate the risk of clashing e.g. `_id` and a user-defined `id` (see https://github.com/IBM/cloudant-python-sdk/issues/490). Changes: * Fix unexpected `401` res | Low | 3/13/2024 |
| v0.7.3 | **Note: APIs may be subject to change.** Changes: * Added missing parameters for CouchDB global changes (not applicable to Cloudant). * Updated dependencies. * Updated documentation. Deprecations: * The update to `python-sdk-core` [`3.19.0`](https://github.com/IBM/python-sdk-core/releases/tag/v3.19.0) replaces the `code` property with `status_code` to access the HTTP status code on exceptions. This now matches the `status_code` property of responses. The `code` property will be removed | Low | 2/13/2024 |
| v0.7.2 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. | Low | 1/5/2024 |
| v0.7.1 | **Note: APIs may be subject to change.** Changes: * Added Python 3.12 to supported platforms. * Updated dependencies. **Full Changelog**: https://github.com/IBM/cloudant-python-sdk/compare/v0.7.0...v0.7.1 | Low | 11/21/2023 |
| v0.7.0 | **Note: APIs may be subject to change.** Changes: * Improve typing for optionals. * Updated dependencies. * Updated documentation. | Low | 10/30/2023 |
| v0.6.0 | **Note: APIs may be subject to change.** _Breaking Changes_: * Corrected model for `_explain` responses * Renamed `covered` to `covering` in line with Apache CouchDB changes. * Removed `range` member that does not exist in server responses. * Added models for `opts` and `mrargs` members. * Removed unused `def` member from `_index` request models; the correct member `index` was already present. The `def` member is used only on response models and was already correctly included | Low | 9/25/2023 |
| v0.5.0 | **Note: APIs may be subject to change.** New features: * [Changes follower (beta)](https://github.com/IBM/cloudant-python-sdk/tree/v0.5.0#changes-feed-follower-beta) - a convenience API for consuming a database changes feed. Changes: * Updated dependencies. * Updated documentation. | Low | 8/30/2023 |
| v0.4.4 | **Note: APIs may be subject to change.** Changes: * Updated known issues documentation. * Updated dependencies. * Removed EOL Python 3.7 from supported versions. | Low | 7/13/2023 |
| v0.4.3 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. | Low | 6/21/2023 |
| v0.4.2 | **Note: APIs may be subject to change.** Changes: * Added `covered` attribute to `_explain` results. * Updated dependencies. * Docmentation updates. | Low | 5/24/2023 |
| v0.4.1 | **Note: APIs may be subject to change.** Changes: * Added `updates_pending` for get design document information response model. * Updated dependencies. | Low | 4/25/2023 |
| v0.4.0 | **Note: APIs may be subject to change.** _Breaking Changes_: * Removed the `stable` parameter from partitioned view queries. The parameter is not valid on this type of request. * The `status` and `task` properties are removed from the `_active_tasks` response model. These properties were included in error and are not returned. * Invalid JSON responses now raise an exception instead of returning a successful response with a string body. Changes: * Added additional properties that were m | Low | 3/27/2023 |
| v0.3.3 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. | Low | 2/9/2023 |
| v0.3.2 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. | Low | 1/5/2023 |
| v0.3.1 | **Note: APIs may be subject to change.** Changes: * Allow `dict` type arguments for some operations where these previously threw an exception * Updated dependencies | Low | 11/30/2022 |
| v0.3.0 | **Note: APIs may be subject to change.** _Breaking Changes_: * Corrected path validation on document requests using raw IO or alternative `Content-Type` operations. Changes: * Updated dependencies. * Improved documentation. * Added missing "deleted" optional property to docs result row value. * Added new "use_bulk_get" replicator options to model. * Fixed handling of `${SERVICE}_AUTH_DISABLE_SSL` environment variable for `COUCHDB_SESSION` auth. * Added Python 3.11 support. | Low | 10/27/2022 |
| v0.2.1 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Fix serialization of `None` properties. * Validate required path parameters are not empty string. * Remove duplicated enums. | Low | 9/30/2022 |
| v0.2.0 | **Note: APIs may be subject to change.** _Breaking Changes_: * Removed deprecated geospatial APIs. Changes: * Added `winning_revs_only` option to replication documents (usable with [Cloudant build 8335](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-classic-release-notes#cloudant-aug0522) or newer). * Updated dependencies. * Improved documentation. | Low | 8/23/2022 |
| v0.1.4 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Documentation fixes. | Low | 7/6/2022 |
| v0.1.3 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Added example code. | Low | 5/27/2022 |
| v0.1.2 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. | Low | 4/28/2022 |
| v0.1.1 | **Note: APIs may be subject to change.** _Breaking Changes_: * Corrected view names to match langauge casing style - `startkey` `startkey_docid` `endkey` `endkey_docid` are replaced respectively with `start_key` `start_key_doc_id` `end_key` `end_key_doc_id` * Removed `account` from database information (this field was included in error and never populated). Changes: * Modified the User-Agent header. * Updated dependencies. * Changed the format of the User-Agent header. * Docum | Low | 3/29/2022 |
| v0.0.43 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Automatic session authentication uses `application/json` instead of `application/x-www-form-urlencoded`. | Low | 2/16/2022 |
| v0.0.42 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Align with core support of env var `AUTH_TYPE` alias `AUTHTYPE`. | Low | 1/25/2022 |
| v0.0.41 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Improved documentation. | Low | 12/3/2021 |
| v0.0.40 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. | Low | 11/18/2021 |
| v0.0.39 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. | Low | 11/11/2021 |
| v0.0.38 | **Note: APIs may be subject to change.** Changes: * Set 2.5 minutes default read timeout. * Updated dependencies. * Fixed made `error` available in `_dbs_info` response. * Added new `Basic` auth sections to replication source and target schemas. * Documentation updates. Breaking changes * Removed function accessing `_missing_revs` endpoint (superseded by `_revs_diff`). * Remove 'updates' property from the design document schema. | Low | 10/5/2021 |
| v0.0.37 | **Note: APIs may be subject to change.** Changes: * Updated dependencies. * Fixed type of `validate_doc_update` in design documents. * Documentation updates | Low | 9/10/2021 |
| v0.0.36 | **Note: APIs may be subject to change.** Changes: * Document IDs and attachment names are now rejected if they could cause an unexpected Cloudant request. We have seen that some applications pass unsanitized document IDs to SDK functions (e.g. direct from user requests). In response to this we have updated many functions to reject obviously invalid paths. However, for complete safety applications must still validate that document IDs and attachment names match expected patterns. * Updated d | Low | 8/26/2021 |