Skip to content
This repository has been archived by the owner on Aug 30, 2024. It is now read-only.

Latest commit

 

History

History
114 lines (101 loc) · 11.2 KB

MIGRATION.md

File metadata and controls

114 lines (101 loc) · 11.2 KB
Raw

Migrating to the cloudant-python-sdk library

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:

  1. Environment variables
  2. External configuration file
  3. Programmatically

See the README for code examples on using environment variables.

Other differences

  1. The cloudant-python-sdk library does not support local dictionary caching of database and document objects.
  2. 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.
  3. 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.
  4. Replay adapters are replaced by the automatic retries feature for failed requests.
  5. 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.
  6. 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

  1. 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.
  2. 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