Aliyun OSS (Object Storage Service) SDK

Warnings

• breaking The `oss2` library is a complete rewrite of the previous Alibaba Cloud OSS Python SDK (version 0.x). It is not backward compatible. The package name was specifically changed to `oss2` to avoid conflicts with older installations.
  Fix: Migrate your code to use the `oss2` API. If you have an old `oss` installation, ensure you are importing `oss2` and not `oss`.
• gotcha When using `oss2.resumable_download` or `oss2.resumable_upload`, avoid calling these functions concurrently from multiple programs or threads targeting the same object and local file. This can lead to checkpoint file corruption, overwrites, or temporary file naming conflicts.
  Fix: Ensure that only one instance (program or thread) is performing a resumable operation on a specific object-to-local-file pair at any given time.
• gotcha For new OSS users accessing buckets in Chinese mainland regions, a custom domain name (CNAME) is required for data API operations starting March 20, 2025. Default public endpoints are restricted for these operations.
  Fix: Configure a custom domain name (CNAME) and bind it to your bucket for data API operations. If using HTTPS, ensure a valid SSL certificate is bound to the custom domain.
• deprecated Python 2.6 and Python 3.3.0/3.3.1 are not recommended due to lack of core team support for 2.6 and a known Python issue (Issue 16658) for 3.3.0/3.3.1.
  Fix: Use supported Python versions, preferably Python 3.5+.

Install

• pip install oss2 Install stable version

Imports

• oss2

  import oss2

  Primary import for the SDK classes and functions.
• Auth

  from oss2 import Auth

  Used for authentication with AccessKeyID and AccessKeySecret.
• Bucket

  from oss2 import Bucket

  Represents an OSS bucket, used for bucket and object operations.
• ObjectIterator

  from oss2 import ObjectIterator

  Iterator for listing objects within a bucket.
• exceptions

  from oss2 import exceptions

  Contains custom exceptions thrown by the SDK, e.g., `oss2.exceptions.NoSuchKey`.

Quickstart

This quickstart demonstrates how to initialize the `oss2` SDK, upload a string to an object, download its content, list objects in the bucket, and then delete the uploaded object. It uses environment variables for secure credential management.

import os
import oss2

# Environment variables for credentials
ACCESS_KEY_ID = os.environ.get('OSS_ACCESS_KEY_ID', 'your-access-key-id')
ACCESS_KEY_SECRET = os.environ.get('OSS_ACCESS_KEY_SECRET', 'your-access-key-secret')
ENDPOINT = os.environ.get('OSS_ENDPOINT', 'http://oss-cn-hangzhou.aliyuncs.com') # e.g., 'http://oss-cn-hangzhou.aliyuncs.com'
BUCKET_NAME = os.environ.get('OSS_BUCKET_NAME', 'your-bucket-name')

# Ensure credentials and endpoint are set
if not all([ACCESS_KEY_ID, ACCESS_KEY_SECRET, ENDPOINT, BUCKET_NAME]):
    print("Please set OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET, OSS_ENDPOINT, and OSS_BUCKET_NAME environment variables.")
    exit(1)

try:
    # Initialize Auth and Bucket
    auth = oss2.Auth(ACCESS_KEY_ID, ACCESS_KEY_SECRET)
    bucket = oss2.Bucket(auth, ENDPOINT, BUCKET_NAME)

    # Object key
    key = 'hello_oss.txt'
    content = 'Hello Alibaba Cloud OSS!'

    # 1. Upload an object from memory
    bucket.put_object(key, content)
    print(f"Object '{key}' uploaded successfully.")

    # 2. Download the object content
    response = bucket.get_object(key)
    downloaded_content = response.read().decode('utf-8')
    print(f"Content of '{key}': {downloaded_content}")

    # 3. List objects in the bucket (optional)
    print("\nObjects in bucket:")
    for obj_info in oss2.ObjectIterator(bucket):
        print(f"  - {obj_info.key}")

    # 4. Delete the object
    bucket.delete_object(key)
    print(f"Object '{key}' deleted successfully.")

except oss2.exceptions.OssError as e:
    print(f"OSS Error: {e.code} - {e.message} (Request ID: {e.request_id})")
except Exception as e:
    print(f"An unexpected error occurred: {e}")