IBM COS SDK Core for Python

2.16.1 · active · verified Sun Apr 12

ibm-cos-sdk-core provides the low-level, data-driven core functionality for the IBM Cloud Object Storage (COS) SDK for Python. It is based on `botocore` and exposes similar low-level client interfaces. The current version is 2.16.1. It has a moderate release cadence, with several patch and minor releases per year, often aligning with `botocore` updates and adding new COS features.

Warnings

gotcha Most users should install and use the `ibm-cos-sdk` package instead of `ibm-cos-sdk-core`. The core library is low-level, similar to `botocore`, and is primarily intended for extending the SDK or for very specific low-level interactions.
Fix: For most applications, use `pip install ibm-cos-sdk` and import from `ibm_boto3` instead of `ibm_cos_sdk_core`.
gotcha Credential mapping for IBM COS S3-compatible API: The `ibm-cos-sdk-core` (like `botocore`) expects `aws_access_key_id` and `aws_secret_access_key`. For IBM COS, your IBM Cloud API Key should be provided as `aws_access_key_id`, and your IBM Cloud Service Instance ID should be provided as `aws_secret_access_key`.
Fix: When creating a client, pass your IBM API Key to `aws_access_key_id` and your IBM Service Instance ID to `aws_secret_access_key`.
gotcha The API is low-level and requires manual handling of service models, operations, and response parsing, similar to `botocore`. This means more boilerplate code compared to the high-level client in `ibm-cos-sdk`.
Fix: Be prepared to work with raw JSON responses and define explicit parameters for each API call. Consider using `ibm-cos-sdk` for a more Pythonic and abstracted interface.
breaking This library is tightly coupled with `botocore` versions. Breaking changes or new features introduced in `botocore` can directly impact `ibm-cos-sdk-core`'s behavior or require updates.
Fix: Monitor `botocore` release notes and ensure compatibility when upgrading either `ibm-cos-sdk-core` or `botocore` dependencies in your project.
gotcha Correct endpoint and region configuration are critical. IBM COS has various endpoints based on geographic regions. Using an incorrect endpoint or region for your bucket will result in connectivity or authorization errors.
Fix: Always specify the `endpoint_url` corresponding to your bucket's region and ensure `region_name` is also set appropriately.

Install

pip install ibm-cos-sdk-core Install stable version

Imports

get_session

from ibm_cos_sdk_core.session import get_session

ClientCreator
```
from ibm_cos_sdk_core.client import ClientCreator
```
ClientCreator is located within the 'client' submodule, not directly under the package root.

Quickstart

This quickstart demonstrates how to create a low-level S3-compatible client using `ibm-cos-sdk-core`'s session and client creation capabilities. It shows how to map IBM Cloud Object Storage credentials (API Key and Service Instance ID) to the `aws_access_key_id` and `aws_secret_access_key` parameters required by the S3-compatible client. The example then attempts to list available buckets. Most users are recommended to use the higher-level `ibm-cos-sdk` package for simpler interactions.

import os
from ibm_cos_sdk_core.session import get_session

# Configure IBM Cloud Object Storage credentials and endpoint
# These usually map to 'aws_access_key_id' and 'aws_secret_access_key' for S3 compatibility
IBM_API_KEY_ID = os.environ.get('IBM_COS_API_KEY_ID', 'YOUR_IBM_API_KEY')
IBM_SERVICE_INSTANCE_ID = os.environ.get('IBM_COS_SERVICE_INSTANCE_ID', 'YOUR_IBM_SERVICE_INSTANCE_ID')
IBM_COS_REGION = os.environ.get('IBM_COS_REGION', 'us-south')
IBM_COS_ENDPOINT = os.environ.get('IBM_COS_ENDPOINT', f'https://s3.{IBM_COS_REGION}.cloud-object-storage.appdomain.cloud')

if 'YOUR_' in IBM_API_KEY_ID or 'YOUR_' in IBM_SERVICE_INSTANCE_ID:
    print("Please set IBM_COS_API_KEY_ID and IBM_COS_SERVICE_INSTANCE_ID environment variables for authentication.")
    print("Falling back to dummy credentials. This example will likely fail without proper auth.")

# Get a session object
session = get_session()

# Create a low-level client for the S3-compatible service
# Note: IBM COS uses 's3' service model for its S3-compatible API
try:
    client = session.create_client(
        's3',
        region_name=IBM_COS_REGION,
        endpoint_url=IBM_COS_ENDPOINT,
        aws_access_key_id=IBM_API_KEY_ID,
        aws_secret_access_key=IBM_SERVICE_INSTANCE_ID
    )

    # Example: List buckets
    print(f"Attempting to list buckets in region {IBM_COS_REGION}...")
    response = client.list_buckets()
    print("Buckets:")
    for bucket in response.get('Buckets', []):
        print(f"  - {bucket['Name']}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure your IBM COS credentials and endpoint are correctly configured.")

view raw JSON →