search

IBM / cloudant-python-sdk

Cloudant SDK for Python
Apache License 2.0
47 stars 19 forks source link

readme

Build Status Release Docs

IBM Cloudant Python SDK Version 0.9.3

IBM Cloudant Python SDK is a client library that interacts with the IBM Cloudant APIs.

Disclaimer: This library is still a 0.x release. We do consider this library production-ready and capable, but there are still some limitations we’re working to resolve, and refinements we want to deliver. We are working really hard to minimise the disruption from now until the 1.0 release, but there may still be some changes that impact applications using this SDK. For now, be sure to pin versions to avoid surprises.

Table of Contents - [Overview](#overview) - [Features](#features) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Using the SDK](#using-the-sdk) * [Authentication](#authentication) + [Authentication with environment variables](#authentication-with-environment-variables) - [IAM API key authentication](#iam-api-key-authentication) - [IAM Trusted profile (container) authentication](#iam-trusted-profile-container-authentication) - [IAM Trusted profile (VPC) authentication](#iam-trusted-profile-vpc-authentication) - [Session cookie authentication](#session-cookie-authentication) + [Authentication with external configuration](#authentication-with-external-configuration) + [Programmatic authentication](#programmatic-authentication) * [Automatic retries](#automatic-retries) * [Request timeout configuration](#request-timeout-configuration) * [Code examples](#code-examples) + [1. Create a database and add a document](#1-create-a-database-and-add-a-document) + [2. Retrieve information from an existing database](#2-retrieve-information-from-an-existing-database) + [3. Update your previously created document](#3-update-your-previously-created-document) + [4. Delete your previously created document](#4-delete-your-previously-created-document) + [Further code examples](#further-code-examples) * [Error handling](#error-handling) * [Raw IO](#raw-io) * [Model classes vs dictionaries](#model-classes-vs-dictionaries) * [Further resources](#further-resources) * [Changes feed follower (beta)](#changes-feed-follower-beta) + [Introduction](#introduction) + [Modes of operation](#modes-of-operation) + [Configuring the changes follower](#configuring-the-changes-follower) + [Error suppression](#error-suppression) + [Follower operation](#follower-operation) + [Checkpointing](#checkpointing) + [Code examples](#code-examples-1) - [Initializing a changes follower](#initializing-a-changes-follower) - [Starting the changes follower](#starting-the-changes-follower) * [Start mode for continuous listening](#start-mode-for-continuous-listening) * [Start mode for one-off fetching](#start-mode-for-one-off-fetching) - [Processing changes](#processing-changes) * [Process continuous changes](#process-continuous-changes) * [Process one-off changes](#process-one-off-changes) - [Stopping the changes follower](#stopping-the-changes-follower) - [Questions](#questions) - [Issues](#issues) - [Versioning and LTS support](#versioning-and-lts-support) - [Open source at IBM](#open-source-at-ibm) - [Contributing](#contributing) - [License](#license)

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 to them: developing software.

Reasons why you should consider using Cloudant Python SDK in your project:

Prerequisites

Installation

To install, use pip or easy_install:

pip install --upgrade "ibmcloudant>=0.9.3"

or

easy_install --upgrade "ibmcloudant>=0.9.3"

Using the SDK

For fundamental SDK usage information and config options, please see the common IBM Cloud SDK documentation.

This library requires configuration with a service URL and Cloudant service credentials to authenticate with your account.

There are several ways to set these authentication properties:

  1. As environment variables
  2. The programmatic approach
  3. With an external credentials file

The following section describes the different authentication types and provides environment variable examples. Examples for other configuration methods are available by following the provided links.

Authentication

This library requires credentials to authenticate with IBM Cloudant. These credentials may be:

For other compatible APIs that are not Cloudant accounts (e.g. Apache CouchDB) non-IAM based authentication types must be used.

This table summarizes the available authentication types. The authentication types are listed in order of recommendation, preferably use the authentication type from the first row in the table that is compatible with your environment.

Authentication type Recommended for AUTH_TYPE Description
IAM Trusted Profiles compute resource (container) Cloudant
(SDK running in IBM Cloud IKS)		 CONTAINER Obtains a compute resource (CR) token from the container.
Exchanges the CR token for an IAM access_token.
Adds an Authorization: Bearer <access_token> header to each HTTP request.
Automatically renews the access token when needed.
IAM Trusted Profiles compute resource (VPC) Cloudant
(SDK running in IBM Cloud VPC)		 VPC Obtains an identity token from the VPC instance metadata.
Exchanges the identity token for an IAM access_token.
Adds an Authorization: Bearer <access_token> header to each HTTP request.
Automatically renews the access token when needed.
IAM API key Cloudant IAM Exchanges an IAM API key for an IAM access_token.
Adds an Authorization: Bearer <access_token> header to each HTTP request.
Automatically renews the access token when needed.
Session cookie Cloudant
(legacy credentials & instances without IAM)

Apache CouchDB		 COUCHDB_SESSION Exchanges credentials with /_session endpoint to retrieve a cookie.
Adds Cookie header and content to each HTTP request.
Automatically renews session when needed.
Bearer token Apache CouchDB
(using JWT authentication)		 BEARERTOKEN Adds an Authorization: Bearer <token> to each HTTP request.
No token management or renewal.
Also compatible with IAM access tokens managed independently of the SDK.
Basic Apache CouchDB
(if cookies are not enabled)		 BASIC Adds an Authorization: Basic <encoded username and password> header to each HTTP request.
None - NOAUTH Note that this authentication type only works for operations against a database allowing access for unauthenticated users.

The default authentication type for the SDK is CONTAINER unless APIKEY configuration is supplied, which changes the default authentication type to IAM.

Authentication with environment variables

The default service name is CLOUDANT so CLOUDANT_ prefixed names are used in these examples.

Any custom service name prefix can be used as long as the matching name is used to instantiate the SDK client and the same prefix is used for all configuration options.

IAM API key authentication

For Cloudant IAM API key authentication, set the following environmental variables by replacing the <url> and <apikey> with your proper service credentials. There is no need to set CLOUDANT_AUTH_TYPE to IAM because it is the default when an APIKEY is set.

CLOUDANT_URL=<url>
CLOUDANT_APIKEY=<apikey>
IAM Trusted profile (container) authentication

For Cloudant IAM Trusted profile compute resource container authentication, set the following environmental variables by replacing the <url> and <id> with your values. There is no need to set CLOUDANT_AUTH_TYPE to CONTAINER because it is the default.

CLOUDANT_URL=<url>
CLOUDANT_IAM_PROFILE_ID=<id>

Alternatively a profile name may be used instead of an ID by replacing CLOUDANT_IAM_PROFILE_ID with CLOUDANT_IAM_PROFILE_NAME.

IAM Trusted profile (VPC) authentication

For Cloudant IAM Trusted profile compute resource vpc authentication, set the following environmental variables by replacing the <url> and <id> with your values.

CLOUDANT_AUTH_TYPE=VPC
CLOUDANT_URL=<url>
CLOUDANT_IAM_PROFILE_ID=<id>

Alternatively a profile CRN may be used instead of an ID by replacing CLOUDANT_IAM_PROFILE_ID with CLOUDANT_IAM_PROFILE_CRN.

Session cookie authentication

For COUCHDB_SESSION authentication, set the following environmental variables by replacing the <url>, <username> and <password> with your proper service credentials.

CLOUDANT_AUTH_TYPE=COUCHDB_SESSION
CLOUDANT_URL=<url>
CLOUDANT_USERNAME=<username>
CLOUDANT_PASSWORD=<password>

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.

Automatic retries

The SDK supports a generalized retry feature that can automatically retry on common errors.

The automatic retries section has details on how to enable the retries with default values and customize the retries programmatically or with external configuration.

Request timeout configuration

No request timeout is defined, but a 2.5m read and a 60s connect timeout are set by default. Be sure to set a request timeout appropriate to your application usage and environment. The request timeout section contains details on how to change the value.

Note: System settings may take precedence over configured timeout values.

Code examples

The following code examples authenticate with the environment variables.

1. Create a database and add a document

Note: This example code assumes that orders database does not exist in your account.

This example code creates orders database and adds a new document "example" into it. To connect, you must set your environment variables with the service url, authentication type and authentication credentials of your Cloudant service.

Cloudant environment variable naming starts with a service name prefix that identifies your service. By default, this is CLOUDANT, see the settings in the authentication with environment variables section.

If you would like to rename your Cloudant service from CLOUDANT, you must use your defined service name as the prefix for all Cloudant related environment variables.

Once the environment variables are set, you can try out the code examples.

from ibm_cloud_sdk_core import ApiException
from ibmcloudant.cloudant_v1 import CloudantV1, Document

# 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.status_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"
# Setting `id` for the document is optional when "post_document"
# function is used for CREATE. When `id` is not provided the server
# will generate one for your document.
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:59.000Z"

# Save the document in the database with "post_document" function
create_document_response = client.post_document(
    db=example_db_name,
    document=example_document
).get_result()

# =====================================================================
# Note: saving the document can also be done with the "put_document"
# function. In this case `doc_id` is required for a CREATE operation:
"""
create_document_response = client.put_document(
    db=example_db_name,
    doc_id=example_doc_id,
    document=example_document
).get_result()
"""
# =====================================================================

# Keeping track of the revision number of the document object
# is necessary for further UPDATE/DELETE operations:
example_document.rev = create_document_response["rev"]
print(f'You have created the document:\n{example_document}')

When you run the code, you see a result 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"
}

2. Retrieve information from an existing database

Note: This example code assumes that you have created both the orders database and the example document by running the previous example code successfully. Otherwise, the following error message occurs, "Cannot delete document because either 'orders' database or 'example' document was not found."

Gather database information example ```py import json from ibmcloudant.cloudant_v1 import CloudantV1 # 1. Create a client with `CLOUDANT` default service name ============ client = CloudantV1.new_instance() # 2. Get server information =========================================== server_information = client.get_server_information( ).get_result() print(f'Server Version: {server_information["version"]}') # 3. Get database information for "orders" ========================== db_name = "orders" 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 "example" document out of the database by document id ============ document_example = client.get_document( db=db_name, doc_id="example" ).get_result() print(f'Document retrieved from database:\n' f'{json.dumps(document_example, indent=2)}') ```

When you run the code, you see a result similar to the following output.

Server Version: 2.1.1
Document count in "orders" database is 1.
Document retrieved from database:
{
  "_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 the previous example code successfully. Otherwise, the following error message occurs, "Cannot update document because either 'orders' database or 'example' document was not found."

Update code example ```py import json from ibm_cloud_sdk_core import ApiException from ibmcloudant.cloudant_v1 import CloudantV1 # 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() # ================================================================= # Note: for response byte stream use: """ document_as_byte_stream = client.get_document_as_stream( 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() # ================================================================= # Note 1: for request byte stream use: """ update_document_response = client.post_document( db=example_db_name, document=document_as_byte_stream ).get_result() """ # ================================================================= # ================================================================= # Note 2: updating the document can also be done with the # "put_document" function. `doc_id` and `rev` are required for an # UPDATE operation, but `rev` can be provided in the document # object as `_rev` too: """ update_document_response = client.put_document( db=example_db_name, doc_id=example_doc_id, # doc_id is a required parameter rev=document["_rev"], document=document # _rev in the document object CAN replace above `rev` parameter ).get_result() """ # ================================================================= # Keeping track of the latest revision number of the document # object is necessary for further UPDATE/DELETE operations: 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.status_code == 404: print('Cannot delete document because either ' + f'"{example_db_name}" database or "{example_doc_id}" ' + 'document was not found.') ```

When you run the code, you see a result similar to the following output.

{
  "_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 the previous example code successfully. Otherwise, the following error message occurs, "Cannot delete document because either 'orders' database or 'example' document was not found."

Delete code example ```py from ibm_cloud_sdk_core import ApiException from ibmcloudant.cloudant_v1 import CloudantV1 # 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, # `doc_id` is required for DELETE rev=document["_rev"] # `rev` is required for DELETE ).get_result() if delete_document_response["ok"]: print('You have deleted the document.') except ApiException as ae: if ae.status_code == 404: print('Cannot delete document because either ' + f'"{example_db_name}" database or "{example_doc_id}"' + 'document was not found.') ```

When you run the code, you see the following output.

You have deleted the document.

Further code examples

For a complete list of code examples, see the examples directory.

Error handling

For sample code on handling errors, see Cloudant API docs.

Raw IO

For endpoints that read or write document content it is possible to bypass usage of the built-in object with byte streams.

Depending on the specific SDK operation it may be possible to:

Request byte stream can be supplied for arguments that accept the BinaryIO type. For these cases you can pass this byte stream directly to the HTTP request body.

Response byte stream is supported in functions with the suffix of _as_stream. The returned byte stream allows the response body to be consumed without triggering JSON unmarshalling that is typically performed by the SDK.

The update document section contains examples for both request and response byte stream cases.

The API reference contains further examples of using byte streams. They are titled "Example request as stream" and are initially collapsed. Expand them to see examples of:

Model classes vs dictionaries

This SDK supports two possible formats to define an HTTP request. One approach uses only model classes and the other only dictionaries.

Example using model class structure ```py from ibmcloudant.cloudant_v1 import DesignDocument, CloudantV1, DesignDocumentOptions, SearchIndexDefinition client = CloudantV1.new_instance() price_index = SearchIndexDefinition( index='function (doc) { index("price", doc.price); }' ) design_document_options = DesignDocumentOptions( partitioned=True ) partitioned_design_doc = DesignDocument( indexes={'findByPrice': price_index}, options=design_document_options ) response = client.put_design_document( db='products', design_document=partitioned_design_doc, ddoc='appliances' ).get_result() print(response) ```
Same example using dictionary structure ```py from ibmcloudant.cloudant_v1 import CloudantV1 client = CloudantV1.new_instance() price_index = { 'index': 'function (doc) { index("price", doc.price); }' } partitioned_design_doc = { 'indexes': {'findByPrice': price_index}, 'options': {'partitioned': True}, } response = client.put_design_document( db='products', design_document=partitioned_design_doc, ddoc='appliances' ).get_result() print(response) ```

Since model classes and dicts are different data structures, they cannot be combined.

This solution will be invalid ```py from ibmcloudant.cloudant_v1 import CloudantV1, DesignDocument client = CloudantV1.new_instance() price_index = { 'index': 'function (doc) { index("price", doc.price); }' } partitioned_design_doc = DesignDocument( indexes={'findByPrice': price_index}, options={'partitioned': True} ) response = client.put_design_document( db='products', design_document=partitioned_design_doc, ddoc='appliances' ).get_result() print(response) ```

Further resources

Changes feed follower (beta)

Introduction

The SDK provides a changes feed follower utility (currently beta). This helper utility connects to the _changes endpoint and returns the individual change items. It removes some of the complexity of using the _changes endpoint by setting some options automatically and providing error suppression and retries.

Tip: the changes feed often does not meet user expectations or assumptions.

Consult the Cloudant changes feed FAQ to get a better understanding of the limitations and suitable use-cases before using the changes feed in your application.

Modes of operation

There are two modes of operation:

Configuring the changes follower

The SDK's model of changes feed options is also used to configure the follower. However, a subset of the options are invalid as they are configured internally by the implementation. Supplying these options when instantiating the follower causes an error. The invalid options are:

Note that the limit parameter will terminate the follower at the given number of changes in either operating mode.

The changes follower requires the client to have HTTP timeouts of at least 1 minute and will error during instantiation if it is insufficient. The default client configuration has sufficiently long timeouts.

For use-cases where these configuration limitations are deemed too restrictive then it is recommended to write code to use the SDK's POST _changes API instead of the follower.

Error suppression

By default, the changes follower will suppress transient errors indefinitely and attempt to run to completion or listen forever as dictated by the operating mode. For applications where that is not desirable an optional error tolerance duration may be specified to control the time since the last successful response that transient errors will be suppressed. This can be used, for example, by applications as a grace period before reporting an error and requiring intervention.

There are some additional points to consider for error suppression:

Follower operation

For both modes:

As is true for the _changes endpoint change items have at least once delivery and an individual item may be received multiple times. When using the follower change items may be repeated even within a limited number of changes (i.e. using the limit option) this is a minor difference from using limit on the HTTP native API.

The follower is not optimized for some use cases and it is not recommended to use it in cases where:

In these cases use-case specific control over the number of change requests made and the content size of the responses may be achieved by using the SDK's POST _changes API.

Checkpointing

The changes follower does not checkpoint since it has no information about whether a change item has been processed by the consuming application after being received. It is the application developer's responsibility to store the sequence IDs to have appropriate checkpoints and to re-initialize the follower with the required since value after, for example, the application restarts.

The frequency and conditions for checkpointing are application specific and some applications may be tolerant of dropped changes. This section is intended only to provide general guidance on how to avoid missing changes.

To guarantee processing of all changes the sequence ID from a change item must not be persisted until after the processing of the change item by the application has completed. As indicated previously change items are delivered at least once so application code must be able to handle repeated changes already and it is preferable to restart from an older since value and receive changes again than risk missing them.

The sequence IDs are available on each change item by default, but may be omitted from some change items when using the seq_interval configuration option. Infrequent sequence IDs may improve performance by reducing the amount of data that needs to be transferred, but the trade-off is that more changes will be repeated if it is necessary to resume the changes follower.

Extreme care should be taken with persisting sequences if choosing to process change items in parallel as there is a considerable risk of missing changes on a restart if the sequence is recorded out of order.

Code examples

Initializing a changes follower
import ChangesFollower
from ibmcloudant.cloudant_v1 import CloudantV1

client = CloudantV1.new_instance()

cf_params = {
    'db': 'example',  # Required: the database name.
    'limit': 100,  # Optional: return only 100 changes (including duplicates).
    'since': '3-g1AG3...'  # Optional: start from this sequence ID (e.g. with a value read from persistent storage).
}

changes_follower = ChangesFollower(
    service=client,  # Required: the Cloudant service client instance.
    error_tolerance=10000,  # Optional: suppress transient errors for at least 10 seconds before terminating.
    **cf_params  # Required: changes feed configuration options dict.
)
Starting the changes follower
Start mode for continuous listening
import Iterable

from ibmcloudant import ChangesFollower
from ibmcloudant.cloudant_v1 import CloudantV1, ChangesResultItem

client = CloudantV1.new_instance()

changes_follower = ChangesFollower(
    service=client,
    **{'db': 'example'})

changes_items: Iterable[ChangesResultItem] = changes_follower.start()
# Note: iterable will not do anything until it is iterated
# Create a for loop to iterate over the flow of changes
# for changes_item in changes_items: ...
Start mode for one-off fetching
import Iterable

from ibmcloudant import ChangesFollower
from ibmcloudant.cloudant_v1 import CloudantV1, ChangesResultItem

client = CloudantV1.new_instance()

changes_follower = ChangesFollower(
    service=client,
    **{'db': 'example'})

changes_items: Iterable[ChangesResultItem] = changes_follower.start_one_off()
# Note: iterable will not do anything until it is iterated
# Create a for loop to iterate over the flow of changes
# for changes_item in changes_items: ...
Processing changes
Process continuous changes
import ChangesFollower
from ibmcloudant.cloudant_v1 import CloudantV1

client = CloudantV1.new_instance()

# Start from a previously persisted seq
# Normally this would be read by the app from persistent storage
# e.g. previously_persisted_seq = your_app_persistence_read_func()
previously_persisted_seq = '3-g1AG3...'
changes_follower = ChangesFollower(
    service=client,
    **{'db': 'example', 'since': previously_persisted_seq})

changes_items = changes_follower.start()
for changes_item in changes_items:
    # do something with changes
    print(changes_item.id)
    for change in changes_item.changes:
        print(change.rev)
    # when change item processing is complete app can store seq
    seq = changes_item.seq
    # write seq to persistent storage for use as since if required to resume later
    # e.g. your_app_persistence_write_func(seq)
    # keep processing changes until the application is terminated or some other stop condition is reached

# Note: iterator above is blocking, code here will be unreachable
# until the iteration is stopped or another stop condition is reached.
# For long running followers careful consideration should be made of where to call stop on the iterator.
Process one-off changes
import ChangesFollower
from ibmcloudant.cloudant_v1 import CloudantV1

client = CloudantV1.new_instance()

# Start from a previously persisted seq
# Normally this would be read by the app from persistent storage
# e.g. previously_persisted_seq = your_app_persistence_read_func()
previously_persisted_seq = '3-g1AG3...'
changes_follower = ChangesFollower(
    service=client,
    **{'db': 'example', 'since': previously_persisted_seq})

changes_items = changes_follower.start_one_off()
for changes_item in changes_items:
    # do something with changes
    print(changes_item.id)
    for change in changes_item.changes:
        print(change.rev)
    # when change item processing is complete app can store seq
    seq = changes_item.seq
    # write seq to persistent storage for use as since if required to resume later
    # e.g. your_app_persistence_write_func(seq)

# Note: iterator above is blocking, code here will be unreachable
# until all changes are processed (or another stop condition is reached).
Stopping the changes follower
import ChangesFollower
from ibmcloudant.cloudant_v1 import CloudantV1

client = CloudantV1.new_instance()
changes_follower = ChangesFollower(
    service=client,
    **{'db': 'example'})
changes_items = changes_follower.start()

for changes_item in changes_items:
    # Option 1: call stop after some condition
    # Note that since the iterator is blocking at least one item
    # must be returned from it to reach to this point.
    # Additional changes may be processed before the iterator stops.
    changes_follower.stop()

# Option 2: call stop method when you want to end the continuous loop from
# outside the iterator.  For example, you've put the changes follower in a
# separate thread and need to call stop on the main thread.
# Note: in this context the call must be made from a different thread because
# code immediately following the iterator is unreachable until the iterator
# has stopped.
changes_follower.stop()

Questions

If you are having difficulties using this SDK or have a question about the IBM Cloud services, ask a question on Stack Overflow.

Issues

If you encounter an issue with the project, you are welcome to submit a bug report.

Before you submit a bug report, search for similar issues and review the KNOWN_ISSUES file to verify that your issue hasn't been reported yet.

Please consult the security policy before opening security related issues.

Versioning and LTS support

This SDK follows semantic versioning with respect to the definition of user facing APIs. This means under some circumstances breaking changes may occur within a major or minor version of the SDK related to changes in supported language platforms.

The SDK is supported on the available LTS releases of the language platform. The LTS language versions are listed in the prerequisites:

Incompatible changes from new language versions are not added to the SDK until they are available in the minimum supported language version.

When language LTS versions move out of support the following will happen:

Open source at IBM

Find more open source projects on the IBM GitHub page.

Contributing

For more information, see CONTRIBUTING.

License

This SDK is released under the Apache 2.0 license. To read the full text of the license, see LICENSE.