IBM Cloudant Python SDK

ibmcloudant is the officially maintained IBM Python SDK for interacting with the IBM Cloudant NoSQL database service and Apache CouchDB 3.x servers. It wraps the full Cloudant HTTP API — documents, design documents, views, Mango queries, search indexes, replication, and the changes feed — behind a single generated CloudantV1 client class with nearly a thousand typed operations.

Beyond the generated API surface, the SDK adds hand-written conveniences that plain HTTP clients don’t offer out of the box: a ChangesFollower helper that manages long-polling, retries, and error recovery on the changes feed; a Pagination module for iterating _all_docs, view, search, and Mango query results across page boundaries without manual bookmark/skip handling; and a CouchDbSessionAuthenticator for username/password session-cookie auth against self-hosted CouchDB. Requests support both typed model classes and plain dictionaries, plus raw byte-stream I/O for bulk document operations and large responses.

What You Get

• A generated CloudantV1 service class exposing nearly 1,000 typed methods covering documents, design documents, Mango queries, views, search indexes, replication, and server/database administration
• A ChangesFollower feature that manages long-polling, timeouts, and transient-error retry/backoff on the _changes feed so consumers don’t hand-roll that state machine
• A Pagination module (Pagination.new_pagination) that iterates _all_docs, view, search, and Mango find results page-by-page, hiding bookmark/skip/limit bookkeeping
• Multiple authentication strategies out of the box: IAM API key, bearer token, basic auth, and a CouchDB session authenticator for username/password cookie auth
• Dual request formats — typed model classes (e.g. Document, DesignDocument) or plain dictionaries — for every operation that accepts a request body
• Raw byte-stream support for bulk document uploads and _as_stream response variants, bypassing JSON marshalling for large payloads

Common Use Cases

• Building a Python backend that reads and writes documents in a Cloudant or CouchDB database with typed request/response models
• Following a database’s changes feed continuously (e.g. to power a search index or downstream event pipeline) using ChangesFollower instead of hand-written long-polling logic
• Paginating through large _all_docs, view, or Mango query result sets without manually tracking bookmarks or skip offsets
• Connecting to a self-hosted Apache CouchDB cluster with username/password session authentication rather than IBM Cloud IAM credentials
• Performing bulk document create/update/delete operations via post_bulk_docs, with configurable request timeouts and automatic retry on transient failures

Under The Hood

Architecture The package is organized around a single CloudantV1 class (ibmcloudant/cloudant_v1.py, ~20,000 lines) that subclasses a shared CloudantBaseService (cloudant_base_service.py). The base service layer patches in path-segment validation rules (e.g. rejecting invalid document/attachment/design-doc IDs before a request is sent) and CouchDB session-cookie authentication support on top of ibm_cloud_sdk_core.BaseService. Two opt-in feature modules — features/changes_follower.py and features/pagination.py — sit alongside the generated client and compose with it rather than modifying it, using threads and queues (ChangesFollower) and a Protocol/Generic-based pager abstraction (Pagination) to add stateful iteration on top of the otherwise stateless generated methods. Swapping the core CloudantV1 class would require regenerating the entire file from IBM’s OpenAPI spec, since it’s not meant to be hand-edited.

Tech Stack Python 3.10+ targeting Python, built with flit_core per pyproject.toml. Runtime dependencies are ibm_cloud_sdk_core (shared IBM Cloud SDK plumbing for auth, retries, and HTTP), requests for the underlying HTTP transport, python_dateutil for RFC3339 timestamp parsing, and PyJWT for token handling. No ORM or database driver beyond raw HTTP — every operation is a REST call against the Cloudant/CouchDB HTTP API. CI runs the test matrix against Python 3.10 through 3.14 with live apache/couchdb:3 and wiremock service containers rather than pure mocks.

Code Quality Tests are split into test/unit (using pytest, responses for HTTP mocking, and pytest-cov for coverage) and test/integration (exercising a real CouchDB container and a WireMock instance for timeout/error scenarios), plus a test/examples directory. test_cloudant_v1.py alone runs over 18,000 lines, reflecting the generated client’s operation count. pylint is configured and run in CI alongside the test suite. Error handling follows the IBM Cloud SDK convention of raising ApiException with structured status/message data rather than swallowing failures. The generated client code is typed throughout with Optional/Union/List annotations, though as auto-generated code its naming and structure follow the OpenAPI spec rather than idiomatic hand-written Python.

What Makes It Unique Most Cloudant/CouchDB users reach for a general HTTP client and hand-roll their own retry, pagination, and changes-feed logic against the raw REST API. This SDK’s differentiation is in the parts that aren’t generated: ChangesFollower implements the specific long-poll/timeout/backoff behavior IBM recommends for reliably consuming the changes feed without missing or duplicating events, and Pagination provides a single typed abstraction across four structurally different paginated endpoints (all-docs, view, search, find) rather than requiring separate bookmark-handling code per endpoint type.