{"id":4569,"library":"ibm-cos-sdk-core","title":"IBM COS SDK Core for Python","description":"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.","status":"active","version":"2.16.1","language":"en","source_language":"en","source_url":"https://github.com/ibm/ibm-cos-sdk-python-core","tags":["ibm","cloud","object-storage","cos","sdk","low-level","s3-compatible"],"install":[{"cmd":"pip install ibm-cos-sdk-core","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides the underlying low-level client architecture and service definitions, this library is a fork/wrapper of botocore.","package":"botocore","optional":false},{"reason":"Used for querying JSON data, a common dependency of botocore and related AWS/S3 compatible SDKs.","package":"jmespath","optional":false}],"imports":[{"symbol":"get_session","correct":"from ibm_cos_sdk_core.session import get_session"},{"note":"ClientCreator is located within the 'client' submodule, not directly under the package root.","wrong":"from ibm_cos_sdk_core import ClientCreator","symbol":"ClientCreator","correct":"from ibm_cos_sdk_core.client import ClientCreator"}],"quickstart":{"code":"import os\nfrom ibm_cos_sdk_core.session import get_session\n\n# Configure IBM Cloud Object Storage credentials and endpoint\n# These usually map to 'aws_access_key_id' and 'aws_secret_access_key' for S3 compatibility\nIBM_API_KEY_ID = os.environ.get('IBM_COS_API_KEY_ID', 'YOUR_IBM_API_KEY')\nIBM_SERVICE_INSTANCE_ID = os.environ.get('IBM_COS_SERVICE_INSTANCE_ID', 'YOUR_IBM_SERVICE_INSTANCE_ID')\nIBM_COS_REGION = os.environ.get('IBM_COS_REGION', 'us-south')\nIBM_COS_ENDPOINT = os.environ.get('IBM_COS_ENDPOINT', f'https://s3.{IBM_COS_REGION}.cloud-object-storage.appdomain.cloud')\n\nif 'YOUR_' in IBM_API_KEY_ID or 'YOUR_' in IBM_SERVICE_INSTANCE_ID:\n    print(\"Please set IBM_COS_API_KEY_ID and IBM_COS_SERVICE_INSTANCE_ID environment variables for authentication.\")\n    print(\"Falling back to dummy credentials. This example will likely fail without proper auth.\")\n\n# Get a session object\nsession = get_session()\n\n# Create a low-level client for the S3-compatible service\n# Note: IBM COS uses 's3' service model for its S3-compatible API\ntry:\n    client = session.create_client(\n        's3',\n        region_name=IBM_COS_REGION,\n        endpoint_url=IBM_COS_ENDPOINT,\n        aws_access_key_id=IBM_API_KEY_ID,\n        aws_secret_access_key=IBM_SERVICE_INSTANCE_ID\n    )\n\n    # Example: List buckets\n    print(f\"Attempting to list buckets in region {IBM_COS_REGION}...\")\n    response = client.list_buckets()\n    print(\"Buckets:\")\n    for bucket in response.get('Buckets', []):\n        print(f\"  - {bucket['Name']}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure your IBM COS credentials and endpoint are correctly configured.\")","lang":"python","description":"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."},"warnings":[{"fix":"For most applications, use `pip install ibm-cos-sdk` and import from `ibm_boto3` instead of `ibm_cos_sdk_core`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor `botocore` release notes and ensure compatibility when upgrading either `ibm-cos-sdk-core` or `botocore` dependencies in your project.","message":"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.","severity":"breaking","affected_versions":"All versions, especially major `botocore` upgrades"},{"fix":"Always specify the `endpoint_url` corresponding to your bucket's region and ensure `region_name` is also set appropriately.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}