IBM Cloud Docs
Python

Python

Given its ease of use and adoption for data science applications, Python support is imperative to increase adoption of your IBM Cloud service. Supporting Python applications using Flask, Django, Jupyter, and functional programming paradigms introduces special considerations that need to be observed by your SDK.

Environment support

  • Your Python SDK should be written to support all Python >=3.5 releases.
  • Ensure your SDK is compatible with data science usecases, such as Jupyter Notebooks.

Publishing

All Python SDKs should be publicly available on an IBM GitHub organization. The releases of these SDKs should be published on PyPI.

Your SDK should follow the semantic versioning best practices.

Community support

Allow your users to find answers to their questions. Users should be able to report problems on GitHub by raising issues on your SDK repository. Having a public Slack channel is a great way to engage with users who have questions specific to their use cases.

Style guidelines

You should follow the PEP8 style guide for Python, with a few modifications, like four spaces instead of tabs for indentation.

You should use the standard development tools for Python to check style and code coverage.

Docstrings

All non-trivial methods should have docstrings. Docstrings should follow the PEP257 guidelines. For more examples, see the Google style guide regarding docstrings.

Dependencies

Your Python SDK should use synchronous network calls, using a library like requests.

PyJWT is recommended for encoding and decoding JSON web tokens.

Your SDK should use logging to assist users with low-level debugging.

Standard features

Authentication

You are not required to use a particular library to provide the authentication for your service.

Your SDK must support all of the authentication methods for your service.

Configuration

In the interests of making your SDK easy to consume and cloud native, you should provide the ability to read in environment variables. Abstracting the application logic from the environment logic allows your users to focus on using your service capabilities their applications.

If you build this capability into your SDK, you must document this mechanism clearly with examples.

Using python-sdk-core

IBM python-sdk-core provides configuration and authentication support. You can use the existing functionality provided by this dependency in your SDK.

Documentation

Your SDK is not useful if your audience cannot understand how to consume it in order to do the basic operations for your service. Your SDK needs to contain the following resources to help your users:

Samples

For your Python SDK, you will want some simple code samples and explanations of what each does. Linking out to the API reference documentation for more advanced use is strongly encouraged.

At minimum, the samples should be included in the README.md file. They should communicate how to install the library, and complete the basic operations provided by your API.

The samples should include simple installation and initialization instructions for the popular frameworks and data science tools. Additional examples should be available in an /examples directory for more advanced operations which can be copied and pasted in to user applications.