Migrating to the cloudant-python-sdk library

March 9, 2022 · View on GitHub

This document is to assist in migrating from the python-cloudant (module: cloudant) to the newly supported cloudant-python-sdk (module: ibmcloudant).

Initializing the client connection

There are several ways to create a client connection in cloudant-python-sdk:

See the README for code examples on using environment variables.

Other differences

The cloudant-python-sdk library does not support local dictionary caching of database and document objects.
There are no context managers in cloudant-python-sdk. To reproduce the behaviour of the python-cloudant context managers in cloudant-python-sdk users need to explicitly call the specific operations against the remote HTTP API. For example, in the case of the document context manager, this would mean doing both a get_document to fetch and a put_document to save.
In cloudant-python-sdk View, Search, and Query (aka _find endpoint) operation responses contain raw JSON content like using raw_result=True in python-cloudant.
Replay adapters are replaced by the automatic retries feature for failed requests.
Error handling is not transferable from python-cloudant to cloudant-python-sdk. For more information go to the Error handling section in our API docs.
Custom HTTP client configurations in python-cloudant can be set differently in cloudant-python-sdk. For more information go to the Configuring the HTTP client section in the IBM Cloud SDK Common README.

Troubleshooting

Authentication errors occur during service instantiation. For example, the code service = CloudantV1.new_instance(service_name="EXAMPLE") will fail with ValueError: At least one of iam_profile_name or iam_profile_id must be specified. if required environment variables prefixed with EXAMPLE are not set.
Server errors occur when running a request against the service. We suggest to check server errors with getServerInformation which is the new alternative of metadata().

Request mapping

Here's a list of the top 5 most frequently used python-cloudant operations and the cloudant-python-sdk equivalent API operation documentation link:

`python-cloudant` operation	`cloudant-python-sdk` API operation documentation link
`Document('db_name', 'docid').fetch()`	`getDocument`
`db.get_view_result()`	`postView`
`db.get_query_result()`	`postFind`
`doc.exists()`	`headDocument`
`Document('db_name', 'docid').save()`	`putDocument`

A table with the whole list of operations is provided at the end of this guide.

The cloudant-python-sdk library is generated from a more complete API spec and provides a significant number of operations that do not exist in python-cloudant. See the IBM Cloud API Documentation to review request parameter and body options, code examples, and additional details for every endpoint.

Known Issues

There's an outline of known issues in the cloudant-python-sdk repository.

Reference table

The table below contains a list of python-cloudant functions and the cloudant-python-sdk equivalent API operation documentation link. The cloudant-python-sdk operation documentation link will contain the new function in a code sample e.g. getServerInformation link will contain a code example with get_server_information().

Note: There are many API operations included in the new cloudant-python-sdk that are not available in the python-cloudant library. The API documentation contains the full list of operations.

`python-cloudant` function	`cloudant-python-sdk` API operation documentation link
`metadata()`	`getServerInformation`
`all_dbs()`	`getAllDbs`
`db_updates()/infinite_db_updates()`	`getDbUpdates`
`Replicator.stop_replication()`	`deleteReplicationDocument`
`Replicator.replication_state()`	`getReplicationDocument`
`Replicator.create_replication()`	`putReplicationDocument`
`Scheduler.get_doc()`	`getSchedulerDocument`
`Scheduler.list_docs()`	`getSchedulerDocs`
`Scheduler.list_jobs()`	`getSchedulerJobs`
`session()`	`getSessionInformation`
`uuids()`	`getUuids`
`db.delete()`	`deleteDatabase`
`db.metadata()`	`getDatabaseInformation`
`db.create_document()`	`postDocument`
`db.create()`	`putDatabase`
`db.all_docs()/db.keys()`	`postAllDocs`
`db.bulk_docs()`	`postBulkDocs`
`db.changes()/db.infinite_changes()`	`postChanges`
`DesignDocument(db, '_design/doc').delete()`	`deleteDesignDocument`
`db.get_design_document()/DesignDocument(db, '_design/doc').fetch()`	`getDesignDocument`
`DesignDocument(db, '_design/doc').save()`	`putDesignDocument`
`DesignDocument(db, '_design/doc').info()`	`getDesignDocumentInformation`
`db.get_search_result()`	`postSearch`
`db.get_view_result()`	`postView`
`db.list_design_documents()`	`postDesignDocs`
`db.get_query_result()`	`postFind`
`db.get_query_indexes()`	`getIndexesInformation`
`db.create_query_index()`	`postIndex`
`db.delete_query_index()`	`deleteIndex`
`Document(db, '_local/docid').fetch()`	`getLocalDocument`
`Document(db, '_local/docid').save()`	`putLocalDocument`
`Document(db, '_local/docid').delete()`	`deleteLocalDocument`
`db.missing_revisions()/db.revisions_diff()`	`postRevsDiff`
`db.partition_metadata()`	`getPartitionInformation`
`db.partitioned_all_docs()`	`postPartitionAllDocs`
`db.get_partitioned_search_result()`	`postPartitionSearch`
`db.get_partitioned_view_result()`	`postPartitionView`
`db.get_partitioned_query_result()`	`postPartitionFind`
`db.get_security_document()/db.security_document()`	`getSecurity`
`db.share_database()`	`putSecurity`
`db.shards()`	`getShardsInformation`
`Document(db, 'docid').delete()`	`deleteDocument`
`Document(db, 'docid').fetch()`	`getDocument`
`Document(db, 'docid').exists()`	`headDocument`
`Document(db, 'docid').save()`	`putDocument`
`Document(db, 'docid').delete_attachment()`	`deleteAttachment`
`Document(db, 'docid').get_attachment()`	`getAttachment`
`Document(db, 'docid').put_attachment()`	`putAttachment`
`generate_api_key()`	`postApiKeys`
`SecurityDocument().save()`	`putCloudantSecurityConfiguration`
`cors_configuration()/cors_origin()`	`getCorsInformation`
`update_cors_configuration()`	`putCorsConfiguration`