{"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":"python","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,"search_vec":"'2.9.0':48 'activ':44 'allow':19 'blob':62 'bucket':23 'cadenc':55 'cloud':32,56 'consist':53 'develop':11,54 'download':37 'enabl':10 'file':40 'function':34 'indic':51 'interact':13 'interfac':30 'librari':42 'like':35 'maintain':45 'manag':39 'object':16,25,58 'oper':21 'programmat':29 'provid':27 'python':5,8 'recent':50 'releas':49 'sdk':3,9,61 'storag':17,33,57,59,63 'tos':2,7,18 'upload':36 'version':47 'volcengin':1,15,60","created_at":"2026-04-16T17:03:40.661975+00:00","updated_at":"2026-04-16T17:03:40.661975+00:00","problems":{"verify_error":"/tmp/tmp1e6tzd0t/venv/lib/python3.12/site-packages/tos/utils.py:1155: SyntaxWarning: invalid escape sequence '\\d'\n  p = re.compile('^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$')\nTraceback (most recent call last):\n  File \"<string>\", line 2, in <module>\n  File \"/tmp/tmp1e6tzd0t"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.9.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.volcengine.com/","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/tos/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["aws","http-networking","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"install_fail","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-09","install_tag":null}}