The `alibabacloud-tea-util` library is a core utility module for the Alibaba Cloud Python SDK. It provides common functionalities such as model handling, various helper methods for data manipulation and validation, and definitions for runtime options. The library is actively maintained, supports Python 3.6 and later, and serves as a foundational component for many other Alibaba Cloud SDKs.
Install & Compatibility
Where this runs
tested against v0.3.14 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.245s · 31.5MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 5.3s · import 0.214s · 34MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from alibabacloud_tea_util.client import Client as UtilClient
Commonly imported as 'UtilClient' to avoid naming conflicts with service-specific 'Client' classes.
models
✓ from alibabacloud_tea_util import models as util_models
Provides shared data models like `RuntimeOptions` for request configuration.
This quickstart demonstrates basic usage of `alibabacloud-tea-util`, showing how to import and instantiate common models like `RuntimeOptions` and use utility methods such as `get_timestamp` and `to_jsonstring`. This library typically works in conjunction with specific service SDKs or `alibabacloud-tea-openapi`.
import os
from alibabacloud_tea_util.client import Client as UtilClient
from alibabacloud_tea_util import models as util_models
# NOTE: In a real application, AccessKey ID and Secret should be
# managed securely, e.g., via environment variables or STS tokens.
# NEVER hardcode credentials in your source code.
# export ALIBABA_CLOUD_ACCESS_KEY_ID="your_access_key_id"
# export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your_access_key_secret"
# Example of using a utility method and a common model
def main():
try:
# Instantiate a common model provided by tea-util
runtime_options = util_models.RuntimeOptions(
connect_timeout=10000, # milliseconds
read_timeout=15000 # milliseconds
)
# You would typically pass these options to a service client,
# but here we'll just print its string representation
print(f"Created RuntimeOptions: {UtilClient.to_jsonstring(runtime_options)}")
# Example of a simple utility function - getting a current timestamp
timestamp = UtilClient.get_timestamp()
print(f"Current timestamp (GMT): {timestamp}")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == '__main__':
main()
Debug
Known issues
gotchaNever hardcode AccessKey ID or AccessKey Secret directly in your code. Always use environment variables (`ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET`) or more secure credential management solutions like RAM roles or STS tokens to prevent credential leakage.fixStore credentials in environment variables or use an STS token service. Access them via `os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID')`. affects: All versions
gotchaThe `alibabacloud-tea-util` library requires Python 3.6 or higher. Ensure your environment meets this minimum requirement to avoid compatibility issues.fixUpgrade your Python interpreter to version 3.6 or newer.
affects: < 0.1.0 (earlier versions might have been less strict, but current requires >=3.6)
gotchaWhile `tea-util` provides core utilities, it's typically used as a dependency for service-specific SDKs (e.g., `alibabacloud-airec`) or the generic `alibabacloud-tea-openapi` package. For full functionality, you'll usually need to install and integrate with these other packages.fixUnderstand `tea-util`'s role as a foundational layer. For API calls, install the relevant service SDK or `alibabacloud-tea-openapi`.
affects: All versions
gotchaWhen handling API responses or network operations, be prepared to catch `TeaException` for business-related errors or `TeaUnretryableException` for network/retry exhaustion. Direct exception handling is crucial for robust applications.fixImplement `try...except TeaException as e:` blocks to gracefully handle errors returned by Alibaba Cloud services.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'alibabacloud_tea_util'
The 'alibabacloud_tea_util' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install alibabacloud_tea_util'.
ModuleNotFoundError: No module named 'Tea'
The 'Tea' module, a dependency of 'alibabacloud_tea_util', is missing.
fixInstall the 'alibabacloud-tea' package using pip: 'pip install alibabacloud-tea'.
AttributeError: 'CredentialModel' object has no attribute 'provider_name'
An outdated 'alibabacloud_credentials' package version is incompatible with the code.
fixUpdate the 'alibabacloud_credentials' package to the latest version using pip: 'pip install --upgrade alibabacloud_credentials'.
Tea.exceptions.UnretryableException
The specified region does not support the service being called.
fixVerify that the service is available in the specified region and adjust the region parameter accordingly.
AttributeError: 'NoneType' object has no attribute 'get_access_key_id'
This error indicates that an attempt was made to access a method on an object that is `None`, often because AccessKey ID or other necessary authentication credentials were not properly provided or initialized when creating an Alibaba Cloud SDK client.
fixEnsure that `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET` environment variables are correctly set, or pass the credentials explicitly during client initialization. For example, `config.setAccessKeyId(os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'))`. Audit
Dependencies
No dependency data recorded yet.