{"id":8726,"library":"tos","title":"Volcengine TOS SDK for Python","description":"The `tos` Python SDK enables developers to interact with Volcengine Object Storage (TOS), allowing for operations on buckets and objects. It provides a programmatic interface for cloud storage functionalities like uploading, downloading, and managing files. The library is actively maintained, with version 2.9.0 released recently, indicating a consistent development cadence.","status":"active","version":"2.9.0","language":"en","source_language":"en","source_url":"https://github.com/volcengine/ve-tos-python-sdk","tags":["cloud storage","object storage","Volcengine","SDK","blob storage"],"install":[{"cmd":"pip install tos","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required Python version for the SDK functionality.","package":"Python 3.7+"}],"imports":[{"note":"The primary client class is `TosClientV2`, not `TosClient` from older versions or other SDKs.","wrong":"from tos import TosClient","symbol":"TosClientV2","correct":"import tos\nclient = tos.TosClientV2(...)"},{"note":"Specific exception for client-side errors (e.g., invalid parameters, network issues).","symbol":"TosClientError","correct":"from tos.exceptions import TosClientError"},{"note":"Specific exception for server-side errors (e.g., HTTP status codes from TOS service).","symbol":"TosServerError","correct":"from tos.exceptions import TosServerError"}],"quickstart":{"code":"import os\nimport tos\nfrom tos.exceptions import TosClientError, TosServerError\n\n# Ensure environment variables are set for authentication\n# os.environ['TOS_ACCESS_KEY'] = 'YOUR_ACCESS_KEY'\n# os.environ['TOS_SECRET_KEY'] = 'YOUR_SECRET_KEY'\n# os.environ['TOS_ENDPOINT'] = 'http://tos-cn-beijing.volces.com' # Example endpoint\n# os.environ['TOS_REGION'] = 'cn-beijing' # Example region\n\nak = os.environ.get('TOS_ACCESS_KEY', '')\nsk = os.environ.get('TOS_SECRET_KEY', '')\nendpoint = os.environ.get('TOS_ENDPOINT', '')\nregion = os.environ.get('TOS_REGION', '')\n\nbucket_name = 'your-example-bucket'\nobject_key = 'your-example-object'\n\nclient = None\ntry:\n    # Initialize TosClientV2 with credentials and endpoint\n    client = tos.TosClientV2(ak, sk, endpoint, region)\n    \n    # Example: List buckets\n    print(f\"Listing buckets for endpoint: {endpoint}\")\n    response = client.list_buckets()\n    print(\"Buckets:\")\n    for bucket in response.buckets:\n        print(f\"- {bucket.name}\")\n\n    # Example: Check if a specific object exists (simplified for quickstart)\n    try:\n        response = client.head_object(bucket_name, object_key)\n        print(f\"Object '{object_key}' exists in bucket '{bucket_name}'.\")\n    except TosServerError as e:\n        if e.status == 404:\n            print(f\"Object '{object_key}' not found in bucket '{bucket_name}'.\")\n        else:\n            raise # Re-raise other server errors\n\nexcept TosClientError as e:\n    print(f\"Client-side error: {e}\")\nexcept TosServerError as e:\n    print(f\"Server-side error: Status {e.status}, Code {e.code}, Message: {e.message}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if client: # Ensure client is closed if it manages connections\n        pass # No explicit close method documented for TosClientV2 in examples, usually handled internally\n","lang":"python","description":"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."},"warnings":[{"fix":"Be aware that 'Tinder Object Storage' refers to Volcengine Object Storage in this context.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Store the `TosClientV2` instance in a global variable or pass it around within your application's scope to avoid repeated initialization overhead.","message":"For optimal performance and stability, initialize `TosClientV2` once and reuse the instance for multiple operations rather than creating a new client for each request.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"Required environment variables are missing (AK, SK, Endpoint, Region)."},{"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.","cause":"The bucket specified in your API call (e.g., `create_bucket`, `get_object`) does not exist in the specified region for your account.","error":"tos.exceptions.TosServerError: Status 404, Code NoSuchBucket, Message: The specified bucket does not exist."},{"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.","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.","error":"tos.exceptions.TosServerError: Status 403, Code AccessDenied, Message: Access Denied."}]}