Volcengine TOS SDK for Python

Common errors

• Required environment variables are missing (AK, SK, Endpoint, Region).

  cause The SDK attempts to retrieve credentials and endpoint information from environment variables (`TOS_ACCESS_KEY`, `TOS_SECRET_KEY`, `TOS_ENDPOINT`, `TOS_REGION`) but they are not set.
  fix Set the required environment variables: `export TOS_ACCESS_KEY='...'`, `export TOS_SECRET_KEY='...'`, `export TOS_ENDPOINT='...'`, `export TOS_REGION='...'`. Alternatively, pass these parameters directly to the `tos.TosClientV2` constructor.

• tos.exceptions.TosServerError: Status 404, Code NoSuchBucket, Message: The specified bucket does not exist.

  cause The bucket specified in your API call (e.g., `create_bucket`, `get_object`) does not exist in the specified region for your account.
  fix Verify that the `bucket_name` is correct and that it exists in the region configured for your `TosClientV2` instance. If creating a new bucket, ensure the name adheres to TOS naming conventions.

• tos.exceptions.TosServerError: Status 403, Code AccessDenied, Message: Access Denied.

  cause Your Access Key (AK) or Secret Key (SK) are incorrect, or the authenticated user/role does not have the necessary permissions to perform the requested operation on the specified resource.
  fix Double-check your `TOS_ACCESS_KEY` and `TOS_SECRET_KEY` for typos. Ensure the associated Volcengine IAM user or role has the required permissions for the TOS bucket and object operations you are attempting.

Warnings

• gotcha The official PyPI summary and GitHub README consistently refer to the service as 'Tinder Object Storage' instead of 'Volcengine Object Storage'. While functional, this typo can be confusing.
  Fix: Be aware that 'Tinder Object Storage' refers to Volcengine Object Storage in this context.
• breaking The SDK relies heavily on correct `ACCESS_KEY`, `SECRET_KEY`, `ENDPOINT`, and `REGION`. Incorrect or missing credentials will lead to `TosClientError` or `TosServerError` depending on the stage of the request.
  Fix: Ensure `TOS_ACCESS_KEY`, `TOS_SECRET_KEY`, `TOS_ENDPOINT`, and `TOS_REGION` environment variables are correctly set, or pass them directly during `TosClientV2` initialization. Consult your Volcengine account for the correct values.
• gotcha For optimal performance and stability, initialize `TosClientV2` once and reuse the instance for multiple operations rather than creating a new client for each request.
  Fix: Store the `TosClientV2` instance in a global variable or pass it around within your application's scope to avoid repeated initialization overhead.
• gotcha The library differentiates between client-side errors (`TosClientError`) and server-side errors (`TosServerError`). `TosClientError` often indicates invalid request parameters or network issues, while `TosServerError` reflects issues reported by the TOS service itself, including HTTP status codes.
  Fix: Implement robust `try...except` blocks to catch both `tos.exceptions.TosClientError` and `tos.exceptions.TosServerError` for comprehensive error handling. Check `e.status` and `e.code` for `TosServerError` for specific diagnostics.

Install

• pip install tos Install stable version

Imports

• TosClientV2
  wrong:

  from tos import TosClient

  correct:

  import tos
  client = tos.TosClientV2(...)

  The primary client class is `TosClientV2`, not `TosClient` from older versions or other SDKs.
• TosClientError

  from tos.exceptions import TosClientError

  Specific exception for client-side errors (e.g., invalid parameters, network issues).
• TosServerError

  from tos.exceptions import TosServerError

  Specific exception for server-side errors (e.g., HTTP status codes from TOS service).

Quickstart

This quickstart demonstrates how to initialize the `TosClientV2` using environment variables for authentication and endpoint configuration. It then performs a basic operation like listing buckets and checking for an object, including essential error handling for both client-side and server-side issues.

import os
import tos
from tos.exceptions import TosClientError, TosServerError

# Ensure environment variables are set for authentication
# os.environ['TOS_ACCESS_KEY'] = 'YOUR_ACCESS_KEY'
# os.environ['TOS_SECRET_KEY'] = 'YOUR_SECRET_KEY'
# os.environ['TOS_ENDPOINT'] = 'http://tos-cn-beijing.volces.com' # Example endpoint
# os.environ['TOS_REGION'] = 'cn-beijing' # Example region

ak = os.environ.get('TOS_ACCESS_KEY', '')
sk = os.environ.get('TOS_SECRET_KEY', '')
endpoint = os.environ.get('TOS_ENDPOINT', '')
region = os.environ.get('TOS_REGION', '')

bucket_name = 'your-example-bucket'
object_key = 'your-example-object'

client = None
try:
    # Initialize TosClientV2 with credentials and endpoint
    client = tos.TosClientV2(ak, sk, endpoint, region)
    
    # Example: List buckets
    print(f"Listing buckets for endpoint: {endpoint}")
    response = client.list_buckets()
    print("Buckets:")
    for bucket in response.buckets:
        print(f"- {bucket.name}")

    # Example: Check if a specific object exists (simplified for quickstart)
    try:
        response = client.head_object(bucket_name, object_key)
        print(f"Object '{object_key}' exists in bucket '{bucket_name}'.")
    except TosServerError as e:
        if e.status == 404:
            print(f"Object '{object_key}' not found in bucket '{bucket_name}'.")
        else:
            raise # Re-raise other server errors

except TosClientError as e:
    print(f"Client-side error: {e}")
except TosServerError as e:
    print(f"Server-side error: Status {e.status}, Code {e.code}, Message: {e.message}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    if client: # Ensure client is closed if it manages connections
        pass # No explicit close method documented for TosClientV2 in examples, usually handled internally