Breaking changes in 0.11.0: deprecated client aliases and default HTTP transport

Issue mô tả các bí danh client, transport, việc dọn dẹp và các ví dụ migration cho 0.11.0, nhưng không nêu tệp nào trong repository, test hay điểm bắt đầu của tài liệu. Trước tiên, hãy xác định vị trí tài liệu dự kiến và xác nhận phạm vi mà các maintainer mong muốn; công việc được xem là hoàn tất khi đã thống nhất mục tiêu và các tiêu chí nghiệm thu bao quát những breaking changes được ghi lại.

Breaking changes in 0.11.0 release

Starting with version 0.11.0, the aws-sdk-* client packages include breaking changes to client names and default HTTP transports. This release also adds automatic cleanup of client HTTP resources.

Async-prefixed client names

Seven clients currently expose both an Async-prefixed client name and a deprecated unprefixed alias. Starting with version 0.11.0, these deprecated aliases are removed and only the Async<ServiceId>Client names remain. All other clients already expose only an Async-prefixed name and are not affected by this change.

The following deprecated aliases are removed:

Deprecated alias removed	Use instead
BedrockRuntimeClient	AsyncBedrockRuntimeClient
ConnectHealthClient	AsyncConnectHealthClient
LexRuntimeV2Client	AsyncLexRuntimeV2Client
PollyClient	AsyncPollyClient
QBusinessClient	AsyncQBusinessClient
SageMakerRuntimeHTTP2Client	AsyncSageMakerRuntimeHTTP2Client
TranscribeStreamingClient	AsyncTranscribeStreamingClient

For example, for Bedrock Runtime:

# Before
from aws_sdk_bedrock_runtime.client import BedrockRuntimeClient

must now be:

# 0.11.0 and later
from aws_sdk_bedrock_runtime.client import AsyncBedrockRuntimeClient

AIOHTTPClient is now the default transport

All clients now default to the AIOHTTPClient transport, which uses the aiohttp library to send HTTP requests. This changes the default transport for the following client packages, which previously used AWSCRTHTTPClient:

• aws-sdk-bedrock-agent-runtime
• aws-sdk-bedrock-agentcore
• aws-sdk-bedrock-runtime
• aws-sdk-connecthealth
• aws-sdk-lambda
• aws-sdk-lex-runtime-v2
• aws-sdk-polly
• aws-sdk-qbusiness
• aws-sdk-sagemaker-runtime-http2
• aws-sdk-transcribe-streaming

[!IMPORTANT]
AIOHTTPClient does not support HTTP/2 or bidirectional event streams. Applications that require either must install the awscrt optional extra and explicitly configure the CRT transport.

For example, install the Bedrock Runtime client with CRT support:

python -m pip install "aws-sdk-bedrock-runtime[awscrt]"

Then pass an AWSCRTHTTPClient to the service-specific configuration:

from smithy_http.aio.crt import AWSCRTHTTPClient

from aws_sdk_bedrock_runtime.client import AsyncBedrockRuntimeClient
from aws_sdk_bedrock_runtime.config import AsyncBedrockRuntimeConfig

config = await AsyncBedrockRuntimeConfig.resolve(
    region="us-west-2",
    transport=AWSCRTHTTPClient(),
)

async with AsyncBedrockRuntimeClient(config=config) as client:
    ...

Applications that do not require HTTP/2, bidirectional event streams, or other CRT-specific functionality do not need to override the transport.

Client resource cleanup

Clients are now asynchronous context managers. Exiting the context automatically closes the underlying transport and cleans up HTTP resources such as sessions and connection pools.

from aws_sdk_bedrock_runtime.client import AsyncBedrockRuntimeClient

async with AsyncBedrockRuntimeClient() as client:
    ...

We recommend using clients as asynchronous context managers. Applications that manage the client lifecycle directly can instead call close():

from aws_sdk_bedrock_runtime.client import AsyncBedrockRuntimeClient

client = AsyncBedrockRuntimeClient()
try:
    ...
finally:
    await client.close()

A client cannot be reused after its context exits or after close() is called.

Migrating existing applications

Update client usage as follows:

1. Replace affected unprefixed client names with the corresponding Async<ServiceId>Client name.
2. If your application requires the CRT transport, install the client package with its awscrt optional extra, resolve an Async<ServiceId>Config with transport=AWSCRTHTTPClient(), and pass that configuration to the client.
3. Use the client as an asynchronous context manager or call await client.close() when the client is no longer needed.

For example:

# Before
from aws_sdk_bedrock_runtime.client import BedrockRuntimeClient
from aws_sdk_bedrock_runtime.config import AsyncBedrockRuntimeConfig

config = await AsyncBedrockRuntimeConfig.resolve(
    region="us-west-2",
)

client = BedrockRuntimeClient(
    config=config,
)

becomes:

# 0.11.0 and later
from smithy_http.aio.crt import AWSCRTHTTPClient

from aws_sdk_bedrock_runtime.client import AsyncBedrockRuntimeClient
from aws_sdk_bedrock_runtime.config import AsyncBedrockRuntimeConfig

config = await AsyncBedrockRuntimeConfig.resolve(
    region="us-west-2",
    transport=AWSCRTHTTPClient(),
)

async with AsyncBedrockRuntimeClient(config=config) as client:
    ...

The explicit CRT transport in this example is only required for applications that need HTTP/2, bidirectional event streams, or other CRT-specific functionality.

Installing the latest version

Upgrade an existing client package with pip:

python -m pip install --upgrade aws-sdk-<service-id>

For example:

python -m pip install --upgrade aws-sdk-bedrock-runtime

To install the optional CRT transport:

python -m pip install --upgrade "aws-sdk-bedrock-runtime[awscrt]"

To explicitly require version 0.11.0 or later:

python -m pip install "aws-sdk-bedrock-runtime>=0.11.0"

Pinning versions

To avoid unexpected breaking changes when installing or deploying your application, we recommend pinning aws-sdk-* client packages to a specific version or compatible version range.

To pin to an exact version:

python -m pip install "aws-sdk-bedrock-runtime==0.11.0"

To allow compatible patch releases while avoiding newer minor releases:

python -m pip install "aws-sdk-bedrock-runtime~=0.11.0"

This is important while the SDK is pre-1.0.0, when minor releases may include breaking changes.