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

Research direction

The issue describes 0.11.0 client aliases, transports, cleanup, and migration examples, but names no repository file, test, or documentation entry point. First identify the intended documentation location and confirm the maintainers' desired scope; done should have an agreed target and acceptance criteria covering the documented breaking changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.