IBM Cloud Object Storage SDK for Python

Warnings

• breaking Migration from 1.x to 2.x versions of ibm-cos-sdk requires changing import statements from `boto3` to `ibm_boto3`. This was introduced in version 2.0 to allow co-existence with the official `boto3` library for AWS services.
  Fix: Update `import boto3` to `import ibm_boto3` and `from botocore.client import Config` to `from ibm_botocore.client import Config` in your code.
• gotcha When creating a client, ensure all required IBM-specific parameters (`ibm_api_key_id`, `ibm_service_instance_id`, `ibm_auth_endpoint`, `endpoint_url`) are provided, and `config=Config(signature_version='oauth')` is included for API key authentication. Missing or incorrect parameters will result in authentication failures.
  Fix: Carefully provide the API key, service instance ID, authentication endpoint, and service endpoint, and ensure `Config(signature_version='oauth')` is passed to the client or resource creation. These details can be found in your IBM Cloud Object Storage service credentials.
• deprecated Support for Python 2.7 and Python 3.4 has been dropped. Newer versions of the SDK require Python 3.8 or higher.
  Fix: Upgrade your Python environment to version 3.8 or newer.
• gotcha The SDK aligns with `boto3` and `botocore` versions, meaning while it offers an S3-compatible API, specific `boto3`/`botocore` versions used by `ibm-cos-sdk` might not always perfectly match the very latest AWS versions. Compatibility issues could arise if expecting exact feature parity or behavior from a specific `boto3` version.
  Fix: Refer to the `ibm-cos-sdk` changelog and `setup.py` for the exact `boto3`/`botocore` versions it aligns with (e.g., `ibm-cos-sdk-core` and `ibm-cos-sdk-s3transfer` dependencies), and consult the IBM COS documentation for supported S3 API features.

Install

• pip install ibm-cos-sdk Install with pip

Imports

• ibm_boto3

  import ibm_boto3

  The IBM COS SDK is a fork of boto3. For IBM Cloud Object Storage, you must import `ibm_boto3` instead of `boto3`. Using `boto3` will target AWS services by default.
• Config

  from ibm_botocore.client import Config

  Required for configuring the client with specific IBM COS authentication and endpoint details.

Quickstart

This quickstart demonstrates how to establish a connection to IBM Cloud Object Storage, list existing buckets, and perform basic file upload and download operations. It uses environment variables for secure credential handling. Ensure you replace placeholder values or set corresponding environment variables with your IBM Cloud API Key, resource instance ID, IAM authentication endpoint, and service endpoint.

import os
import ibm_boto3
from ibm_botocore.client import Config

# --- Environment Variables (Replace with your actual credentials/endpoints) ---
# Get these values from your IBM Cloud Object Storage service credentials.
# Set them as environment variables or replace directly in code (not recommended for production).
API_KEY = os.environ.get('IBM_COS_API_KEY_ID', 'YOUR_API_KEY_ID')
SERVICE_INSTANCE_ID = os.environ.get('IBM_COS_RESOURCE_INSTANCE_ID', 'YOUR_SERVICE_INSTANCE_ID')
AUTH_ENDPOINT = os.environ.get('IBM_COS_AUTH_ENDPOINT', 'https://iam.cloud.ibm.com/identity/token') # e.g., 'https://iam.cloud.ibm.com/identity/token'
SERVICE_ENDPOINT = os.environ.get('IBM_COS_ENDPOINT', 'https://s3.us.cloud-object-storage.appdomain.cloud') # e.g., 'https://s3.us.cloud-object-storage.appdomain.cloud'

if not all([API_KEY, SERVICE_INSTANCE_ID, AUTH_ENDPOINT, SERVICE_ENDPOINT]):
    print("Error: Missing one or more required environment variables for IBM COS configuration.")
    print("Please set IBM_COS_API_KEY_ID, IBM_COS_RESOURCE_INSTANCE_ID, IBM_COS_AUTH_ENDPOINT, IBM_COS_ENDPOINT.")
    exit(1)

try:
    # Create client object
    cos_client = ibm_boto3.client(
        's3',
        ibm_api_key_id=API_KEY,
        ibm_service_instance_id=SERVICE_INSTANCE_ID,
        ibm_auth_endpoint=AUTH_ENDPOINT,
        config=Config(signature_version='oauth'),
        endpoint_url=SERVICE_ENDPOINT
    )

    print("Successfully connected to IBM Cloud Object Storage. Listing buckets...")

    # List buckets
    response = cos_client.list_buckets()
    for bucket in response['Buckets']:
        print(f"Bucket Name: {bucket['Name']}")

    # Example: Upload a simple text file
    bucket_name = "my-test-bucket-12345" # Replace with an existing bucket or create a new one
    object_name = "hello_cos.txt"
    data = "Hello from IBM COS Python SDK!"
    try:
        cos_client.put_object(Bucket=bucket_name, Key=object_name, Body=data)
        print(f"Successfully uploaded '{object_name}' to bucket '{bucket_name}'.")

        # Example: Download the file
        obj = cos_client.get_object(Bucket=bucket_name, Key=object_name)
        downloaded_data = obj['Body'].read().decode('utf-8')
        print(f"Downloaded '{object_name}': {downloaded_data}")

    except cos_client.exceptions.NoSuchBucket:
        print(f"Warning: Bucket '{bucket_name}' not found. Skipping upload/download examples.")
    except Exception as e:
        print(f"An error occurred during object operations: {e}")

except Exception as e:
    print(f"Failed to connect to IBM Cloud Object Storage: {e}")