aws / aws/aws-sdk-python

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

Open
#90 0 comments 0 reactions 0 assignees View on GitHub
announcement
Dominant language
Python
Stars
169
Forks
19
Avg merge
1d 20h
Merged PRs (30d)
11

Description

## 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 `AsyncClient` 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:

```python
# Before
from aws_sdk_bedrock_runtime.client import BedrockRuntimeClient
```

must now be:

```python
# 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:

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

Then pass an `AWSCRTHTTPClient` to the service-specific configuration:

```python
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.

```python
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()`:

```python
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 `AsyncClient` name.
2. If your application requires the CRT transport, install the client package with its `awscrt` optional extra, resolve an `AsyncConfig` 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:

```python
# 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:

```python
# 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`:

```bash
python -m pip install --upgrade aws-sdk-
```

For example:

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

To install the optional CRT transport:

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

To explicitly require version `0.11.0` or later:

```bash
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:

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

To allow compatible patch releases while avoiding newer minor releases:

```bash
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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.