Alibaba Cloud Tea OpenAPI

alibabacloud_tea_openapi is the foundational client library underneath Alibaba Cloud’s Python SDKs. Rather than being used directly by most application developers, it’s the transport and signing layer that per-product SDKs (ECS, OSS, RAM, and dozens of others) are code-generated to depend on: it builds and signs HTTP requests in either RPC style (query-string signatures) or ROA style (header-based ACS3 signatures), resolves credentials from access keys, STS tokens, or bearer tokens, retries failed calls with configurable backoff, and raises typed exceptions carrying Alibaba Cloud’s request IDs and error codes.

Both synchronous and asyncio-based call paths are implemented for every request method, and a bundled WebSocket client handles reconnect/heartbeat logic for Alibaba Cloud’s streaming APIs. It’s Apache-2.0 licensed, part of a larger Darabonba-generated SDK family that also ships Go, Java, TypeScript, PHP, C#, Swift, and C++ equivalents from the same repository, kept in sync across nine language implementations.

What You Get

• A Client class implementing signed RPC-style and ROA-style HTTP requests against Alibaba Cloud OpenAPI endpoints, each with a synchronous and an async (_async) variant.
• Config, OpenApiRequest, and GlobalParameters model classes for structuring endpoint, credential, proxy, TLS, and retry configuration in one place.
• A Utils helper module implementing canonical query-string construction, HMAC-SHA1 and ACS3 (HMAC-SHA256/RSA-SHA256/SM3) request signing, nonce/timestamp generation, and form encoding.
• A typed exception hierarchy (ClientException, ServerException, ThrottlingException, AlibabaCloudException) that carries request IDs, API error codes, and structured detail/description fields.
• A bundled WebSocket client with configurable reconnect, ping/pong, and handshake-timeout behavior for Alibaba Cloud’s streaming product APIs.

Common Use Cases

• Alibaba Cloud’s generated per-product Python SDKs (ECS, OSS, RAM, and others) declare this package as their transport and signing dependency instead of reimplementing request signing themselves.
• Teams building an integration against an Alibaba Cloud API with no published product SDK construct a Client directly with a Config and call do_rpcrequest/do_roarequest themselves.
• Applications authenticating via STS-assumed roles or bearer tokens (federated identity, RAM role assumption) rely on the client’s built-in credential-type detection rather than hardcoding access keys.
• Services consuming Alibaba Cloud’s WebSocket-based streaming APIs use the bundled websocket_utils client instead of building reconnect and heartbeat handling from scratch.

Under The Hood

Architecture The package centers on a single Client class (alibabacloud_tea_openapi/client.py, roughly 2,700 lines) exposing four request-execution methods — do_rpcrequest, do_roarequest, do_roarequest_with_form, and their _async twins — each running its own retry loop driven by DaraCore.should_retry/get_backoff_time from the darabonba-core runtime. Configuration flows in once through a Config object (utils_models/_config.py), whose fields are copied onto private underscore-prefixed attributes at __init__ and then re-assembled into a per-call _runtime dict (key/cert/ca/timeouts/proxies/retry options) on every request, trading some duplication for explicit per-request override via a separate RuntimeOptions argument. Credential resolution happens once at construction — access-key+secret, bearer token, STS security token, or a caller-supplied CredentialClient are inspected in Config and collapsed into a single self._credential, then re-queried per request (get_credential/get_credential_async) so long-lived clients pick up rotated credentials without reconstruction. Because dozens of per-product SDKs depend on this client’s exact method signatures and Config field names, any change to this core abstraction is a breaking change across the entire Alibaba Cloud Python SDK family.

Tech Stack Built for Python 3.7 through 3.12, pinned to darabonba-core>=1.0.8,<2.0.0 (the code-generation runtime providing DaraCore/DaraRequest/RuntimeOptions/RetryPolicyContext), alibabacloud_credentials>=1.0.2,<2.0.0 for credential resolution, alibabacloud_gateway_spi>=0.0.2,<1.0.0 for pluggable gateway extension points, and alibabacloud_tea_util>=0.3.13,<1.0.0 for shared Tea-runtime utilities. Cryptography is provided by the cryptography package, version-gated per Python release (with the upper bound explicitly raised to unblock a recent CVE fix), used for RSA-SHA256 signing alongside a hand-rolled SM3 hash implementation for the ACS3-HMAC-SM3 scheme used by some China-region APIs. Packaging is plain setuptools with no build backend or Dockerfile — this is a library, not a deployable service.

Code Quality Testing is unusually thorough for a generated SDK: tests/test_client.py alone runs over 2,500 lines exercising both RPC/ROA request paths and their async counterparts against mocked HTTP (via httpretty for sync, aioresponses for async), covering credential types, retry/backoff, parameter merging, and error-response parsing; a separate 500+ line suite covers the signing and canonicalization helpers directly. CI runs the full suite across Python 3.7–3.12 with coverage reported to Codecov. Every source file is explicitly marked auto-generated, which explains the repeated retry/signing boilerplate across the four do_*request variants rather than a shared helper — a deliberate code-generation tradeoff. Error handling is typed and explicit, with exceptions carrying status codes, error codes, and request IDs rather than swallowing failures, and the retry loop distinguishes throttling from hard client/server errors. Type hints are present throughout, but there is no linter, formatter, or mypy configuration in the repository, relying on generation correctness over static enforcement.

API Design The public surface is deliberately minimal: construct one Config, pass it to Client, then call do_rpcrequest/do_roarequest with action/version/protocol/method/authType/bodyType plus an OpenApiRequest — a uniform shape that lets dozens of generated per-product SDKs share one client instead of each hand-rolling HTTP logic. That uniformity is the tradeoff: there’s no fluent, idiomatic high-level call like client.get(...), body_type is passed as a raw string rather than an enum, and package-level documentation is thin (a two-line install snippet plus a changelog), since day-to-day usage happens through generated product SDKs that wrap this client rather than through this package’s own docs.