Skip to main content

Python client library for IBM Cloudant

Project description

Build Status

IBM Cloudant Python SDK Version 0.0.25

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 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.
  • Includes all the most popular and latest supported endpoints for applications.
  • Handles the authentication.
  • Familiar user experience of IBM Cloud SDKs.
  • Instances of the client are unconditionally thread-safe.

Prerequisites

  • An IBM Cloud account.
  • An IAM API key to allow the SDK to access your account. Create one here.
  • Python 3.5.3 or above.

Installation

To install, use pip or easy_install:

pip install --upgrade "ibmcloudant>=0.0.25"

or

easy_install --upgrade "ibmcloudant>=0.0.25"

Getting started

Authentication

This library requires some of your Cloudant service credentials to authenticate with your account.

  1. IAM, COUCHDB_SESSION, BASIC or NOAUTH authentication type.
    1. 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.
    2. Session cookie (COUCHDB_SESSION) authentication is recommended for Apache CouchDB or for Cloudant when IAM is unavailable. It exchanges username and password credentials for an AuthSession cookie from the /_session endpoint.
    3. 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 and password credentials.
    4. 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.
  2. The service url

You have to add these properties as your environment variables, because some examples that follow assume that these variables are set. To learn more about authentication configuration see the related documentation in the Cloudant API docs or in the general SDK usage information.

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.

Code examples

1. Retrieve information from an existing database

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 ============
examples_client = CloudantV1.new_instance(service_name="EXAMPLES")

# 2. Get server information ===========================================
server_information = examples_client.get_server_information(
).get_result()

print(f'Server Version: {server_information["version"]}')

# 3. Get database information for "animaldb" ==========================
db_name = "animaldb"

db_information = examples_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 = examples_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

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.

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"

'''
Try to get the document and set revision of example_document to the
latest one if it previously existed in the database
'''
try:
    document_info = client.get_document(
        db=example_db_name, doc_id=example_doc_id
    ).get_result()
    example_document.rev = document_info["_rev"]
    print(f'The document revision for {example_doc_id} document' +
          f'is set to {example_document.rev}.')
except ApiException as ae:
    if ae.code == 404:
        pass

# 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}')

The result of the code is similar to the following output.

"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.

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.')

The result of the code is similar to the following output.

{
  "_id": "example",
  "_rev": "2-70476cf75eb02f55c6c4061aa6941ec8",
  "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.

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.')

The result of the code is the following output.

You have deleted the document.

Using the SDK

For general SDK usage information, please see this link

Questions

If you are having difficulties using this SDK or have a question about the IBM Cloud services, please ask a question 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.

Further resources

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ibmcloudant-0.0.25.tar.gz (90.6 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page