Python client library for IBM Cloudant
Project description
IBM Cloudant Python SDK Version 0.0.29
Python client library to interact with the IBM Cloudant APIs.
Disclaimer: this SDK is being released initially as a pre-release version. Changes might occur which impact applications that use this SDK.
Table of Contents
Overview
The IBM Cloudant Python SDK allows developers to programmatically
interact with IBM 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 for them: develop.
Reasons why you should consider using Cloudant Python SDK in your project:
- Supported by IBM Cloudant.
- Server compatibility with:
- IBM Cloudant "Classic"
- Cloudant "Standard on Transaction Engine" for APIs compatible with Cloudant "Classic" (see the Feature Parity page for further details).
- Apache CouchDB 3.x for data operations
- Includes all the most popular and latest supported endpoints for applications.
- Handles the authentication.
- Familiar user experience of IBM Cloud SDKs.
- Flexibility to use either built-in models or byte-based requests and responses for documents.
- Instances of the client are unconditionally thread-safe.
Prerequisites
Installation
To install, use pip
or easy_install
:
pip install --upgrade "ibmcloudant>=0.0.29"
or
easy_install --upgrade "ibmcloudant>=0.0.29"
Authentication
This library requires some of your Cloudant service credentials to authenticate with your account.
IAM
,COUCHDB_SESSION
,BASIC
orNOAUTH
authentication type.- IAM authentication is highly recommended when your
back-end database server is Cloudant. This
authentication type requires a server-generated
apikey
instead of a user-given password. You can create one here. - Session cookie (
COUCHDB_SESSION
) authentication is recommended for Apache CouchDB or for Cloudant when IAM is unavailable. It exchanges username and password credentials for anAuthSession
cookie from the/_session
endpoint. - Basic (or legacy) authentication is a fallback
for both Cloudant and Apache CouchDB
back-end database servers. This authentication type requires the good old
username
andpassword
credentials. - Noauth authentication does not need any credentials. Note that this authentication type will only work for queries against a database with read access for everyone.
- IAM authentication is highly recommended when your
back-end database server is Cloudant. This
authentication type requires a server-generated
- The service
url
.
There are several ways to set these properties:
- As environment variables
- The programmatic approach
- With an external credentials file
Authentication with environment variables
IAM authentication
For Cloudant IAM authentication set the following environmental variables by
replacing <url>
and <apikey>
with your proper
service credentials. There is no need to set
CLOUDANT_AUTH_TYPE
to IAM
because it is the default.
CLOUDANT_URL=<url>
CLOUDANT_APIKEY=<apikey>
Session cookie authentication
For COUCHDB_SESSION
authentication set the following environmental variables
by replacing <url>
, <username>
and <password>
with your proper
service credentials.
CLOUDANT_AUTH_TYPE=COUCHDB_SESSION
CLOUDANT_URL=<url>
CLOUDANT_USERNAME=<username>
CLOUDANT_PASSWORD=<password>
Basic authentication
For Basic authentication set the following environmental variables by
replacing <url>
, <username>
and <password>
with your proper
service credentials.
CLOUDANT_AUTH_TYPE=BASIC
CLOUDANT_URL=<url>
CLOUDANT_USERNAME=<username>
CLOUDANT_PASSWORD=<password>
Note: We recommend using IAM for Cloudant and Session for CouchDB authentication.
Authentication with external configuration
To use an external configuration file, the Cloudant API docs, or the general SDK usage information will guide you.
Programmatic authentication
To learn more about how to use programmatic authentication, see the related documentation in the Cloudant API docs or in the Python SDK Core document about authentication.
Using the SDK
For general IBM Cloud SDK usage information, please see IBM Cloud SDK Common.
Code examples
The code examples below will follow the authentication with environment variables.
1. Retrieve information from an existing database
Note: this example code assumes that animaldb
database does not exist in your account.
This example code gathers some information about an existing database hosted on
the https://examples.cloudant.com/ service url
. To do this, you need to
extend your environment variables with the service url and authentication
type to use NOAUTH
authentication while reaching the animaldb
database.
This step is necessary for the SDK to distinguish the EXAMPLES
custom service
name from the default service name which is CLOUDANT
.
EXAMPLES_URL=https://examples.cloudant.com
EXAMPLES_AUTH_TYPE=NOAUTH
Once the environment variables are set, you can try out the code examples.
import json
from ibmcloudant.cloudant_v1 import CloudantV1
# 1. Create a Cloudant client with "EXAMPLES" service name ============
client = CloudantV1.new_instance(service_name="EXAMPLES")
# 2. Get server information ===========================================
server_information = client.get_server_information(
).get_result()
print(f'Server Version: {server_information["version"]}')
# 3. Get database information for "animaldb" ==========================
db_name = "animaldb"
db_information = client.get_database_information(
db=db_name
).get_result()
# 4. Show document count in database ==================================
document_count = db_information["doc_count"]
print(f'Document count in \"{db_information["db_name"]}\" '
f'database is {document_count}.')
# 5. Get zebra document out of the database by document id ============
document_about_zebra = client.get_document(
db=db_name,
doc_id="zebra"
).get_result()
print(f'Document retrieved from database:\n'
f'{json.dumps(document_about_zebra, indent=2)}')
The result of the code is similar to the following output.
Server Version: 2.1.1
Document count in "animaldb" database is 11.
Document retrieved from database:
{
"_id": "zebra",
"_rev": "3-750dac460a6cc41e6999f8943b8e603e",
"wiki_page": "http://en.wikipedia.org/wiki/Plains_zebra",
"min_length": 2,
"max_length": 2.5,
"min_weight": 175,
"max_weight": 387,
"class": "mammal",
"diet": "herbivore"
}
2. Create your own database and add a document
Note: this example code assumes that orders
database does not exist in your account.
Now comes the exciting part of creating your own orders
database and adding
a document about Bob Smith with your own IAM or
Basic service credentials.
Create code example
import logging
from ibm_cloud_sdk_core import ApiException
from ibmcloudant.cloudant_v1 import CloudantV1, Document
# Set logging level to show only critical logs
logging.basicConfig(level=logging.CRITICAL)
# 1. Create a client with `CLOUDANT` default service name ============
client = CloudantV1.new_instance()
# 2. Create a database ===============================================
example_db_name = "orders"
# Try to create database if it doesn't exist
try:
put_database_result = client.put_database(
db=example_db_name
).get_result()
if put_database_result["ok"]:
print(f'"{example_db_name}" database created.')
except ApiException as ae:
if ae.code == 412:
print(f'Cannot create "{example_db_name}" database, ' +
'it already exists.')
# 3. Create a document ===============================================
# Create a document object with "example" id
example_doc_id = "example"
example_document: Document = Document(id=example_doc_id)
# Add "name" and "joined" fields to the document
example_document.name = "Bob Smith"
example_document.joined = "2019-01-24T10:42:99.000Z"
# Save the document in the database
create_document_response = client.post_document(
db=example_db_name,
document=example_document
).get_result()
# Keep track of the revision number from the `example` document object
example_document.rev = create_document_response["rev"]
print(f'You have created the document:\n{example_document}')
"orders" database created.
You have created the document:
{
"_id": "example",
"_rev": "1-1b403633540686aa32d013fda9041a5d",
"name": "Bob Smith",
"joined": "2019-01-24T10:42:99.000Z"
}
3. Update your previously created document
Note: this example code assumes that you have created both the orders
database and the example
document by
running this previous example code
successfully, otherwise you get the Cannot update document because either "orders" database or "example" document was not found.
message.
Update code example
import json
import logging
from ibm_cloud_sdk_core import ApiException
from ibmcloudant.cloudant_v1 import CloudantV1
# Set logging level to show only critical logs
logging.basicConfig(level=logging.CRITICAL)
# 1. Create a client with `CLOUDANT` default service name ============
client = CloudantV1.new_instance()
# 2. Update the document =============================================
example_db_name = "orders"
example_doc_id = "example"
# Try to get the document if it previously existed in the database
try:
document = client.get_document(
db=example_db_name,
doc_id=example_doc_id
).get_result()
# Add Bob Smith's address to the document
document["address"] = "19 Front Street, Darlington, DL5 1TY"
# Remove the joined property from document object
if "joined" in document:
document.pop("joined")
# Update the document in the database
update_document_response = client.post_document(
db=example_db_name,
document=document
).get_result()
# Keep track with the revision number of the document object:
document["_rev"] = update_document_response["rev"]
print(f'You have updated the document:\n' +
json.dumps(document, indent=2))
except ApiException as ae:
if ae.code == 404:
print('Cannot delete document because either ' +
f'"{example_db_name}" database or "{example_doc_id}" ' +
'document was not found.')
{
"_id": "example",
"_rev": "2-4e2178e85cffb32d38ba4e451f6ca376",
"name": "Bob Smith",
"address": "19 Front Street, Darlington, DL5 1TY"
}
4. Delete your previously created document
Note: this example code assumes that you have created both the orders
database and the example
document by
running this previous example code
successfully, otherwise you get the Cannot delete document because either "orders" database or "example" document was not found.
message.
Delete code example
import logging
from ibm_cloud_sdk_core import ApiException
from ibmcloudant.cloudant_v1 import CloudantV1
# Set logging level to show only critical logs
logging.basicConfig(level=logging.CRITICAL)
# 1. Create a client with `CLOUDANT` default service name ============
client = CloudantV1.new_instance()
# 2. Delete the document =============================================
example_db_name = "orders"
example_doc_id = "example"
# Try to get the document if it previously existed in the database
try:
document = client.get_document(
db=example_db_name,
doc_id=example_doc_id
).get_result()
delete_document_response = client.delete_document(
db=example_db_name,
doc_id=example_doc_id,
rev=document["_rev"]
).get_result()
if delete_document_response["ok"]:
print('You have deleted the document.')
except ApiException as ae:
if ae.code == 404:
print('Cannot delete document because either ' +
f'"{example_db_name}" database or "{example_doc_id}"' +
'document was not found.')
You have deleted the document.
Error handling
For sample code on handling errors, please see Cloudant API docs.
Raw IO
For endpoints that read or write document content it is possible to bypass usage of the built-in models and send or receive a bytes response. For examples of using byte streams, see the API reference documentation ("Example request as a stream" section).
- Bulk modify multiple documents in a database
- Query a list of all documents in a database
- Query the database document changes feed
Further resources
- Cloudant API docs: API examples for Cloudant Python SDK.
- Cloudant docs: The official documentation page for Cloudant.
- Cloudant Learning Center: The official learning center with several useful videos which help you to use Cloudant successfully.
- Cloudant blog: Many useful articles how to optimize Cloudant for common problems.
Questions
If you are having difficulties using this SDK or have a question about the IBM Cloud services, please ask a question on Stack Overflow.
Issues
If you encounter an issue with the project, you are welcome to submit a bug report. Before that, please search for similar issues. It's possible that someone has already reported the problem.
Open source @ IBM
Find more open source projects on the IBM Github Page.
Contributing
See CONTRIBUTING.
License
This SDK is released under the Apache 2.0 license. The license's full text can be found in LICENSE.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.