aws / aws/aws-sdk-python

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

Đang mở
#90 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
announcement
Ngôn ngữ chính
Python
Star
169
Fork
19
Merge trung bình
1 ngày 20 giờ
Pull request đã merge (30 ngày)
11

Mô tả

## 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.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
aws, python
Lĩnh vực
documentation
Loại issue
Tài liệu
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Cần làm rõ
Mức phù hợp với người mới
25/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.