From 9d33016df05dd2b2ee4fdd667e45678a04fea5e5 Mon Sep 17 00:00:00 2001 From: jonathan343 Date: Thu, 20 Aug 2026 18:43:21 -0400 Subject: [PATCH 1/4] checkpoint --- docs/index.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 118 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 31cb0f2..56e0fd1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,120 @@ # AWS SDK for Python ---8<-- "README.md:2" +Async-first clients for AWS services, distributed as one lightweight package +per service. + +Unlike [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html), +these clients are built from the ground up on Python's `async`/`await`. They +target select AWS services that benefit most from asynchronous I/O, such as +streaming and real-time inference APIs. Each client is generated from its +service's [Smithy](https://smithy.io/) model and is fully type-annotated, so +your editor can autocomplete operations, inputs, and response shapes without +extra stub packages. + +!!! warning "Developer Preview — not for production use" + + This SDK is in Developer Preview and is intended for evaluation and testing + in pre-production environments only. APIs and behavior may change before + general availability. For production workloads, use + [Boto3](https://github.com/boto/boto3) — the generally available AWS SDK + for Python with full coverage of all AWS services. + +## Highlights + +- **Async first**: Every operation is a coroutine, designed for + `asyncio`-based applications. +- **Per-service packages**: Install only the clients you need. Each package is + versioned and released independently. +- **Fully typed**: Generated dataclass models and annotated signatures for + every operation. +- **Streaming support**: First-class support for event streams and + bidirectional streaming operations. + +## Installation + +Each service client is its own package on PyPI and requires Python 3.12 or +later. Create and activate a virtual environment and then install the clients +you need: + +```bash +pip install aws-sdk-bedrock-runtime +``` + +See [Available Clients](clients/index.md) for the full list of service +packages. + +## Quick example + +Send a message to a model with the Amazon Bedrock Runtime client: + +```python +import asyncio + +from aws_sdk_bedrock_runtime.client import BedrockRuntimeClient, ConverseInput +from aws_sdk_bedrock_runtime.config import Config +from aws_sdk_bedrock_runtime.models import ContentBlockText, Message +from smithy_aws_core.identity import EnvironmentCredentialsResolver + + +async def main(): + client = BedrockRuntimeClient( + config=Config( + region="us-east-1", + aws_credentials_identity_resolver=EnvironmentCredentialsResolver(), + ) + ) + + response = await client.converse( + ConverseInput( + model_id="global.anthropic.claude-opus-4-8", # (1)! + messages=[ + Message( + role="user", + content=[ContentBlockText(value="Tell me a fun fact about Python.")], + ) + ], + ) + ) + + print(response.output.value.content[0].value) + + +asyncio.run(main()) +``` + +1. This model may not be the latest available and could be deprecated in the + future. See [Models at a glance](https://docs.aws.amazon.com/bedrock/latest/userguide/model-cards.html) + in the Amazon Bedrock User Guide for the current list of models and their + IDs. + +## Explore + +
+ +- **Available Clients** + + --- + + Browse the full API reference for every service client in the SDK. + + [:octicons-arrow-right-24: Available Clients](clients/index.md) + +- **Contributing** + + --- + + Learn how to report issues, propose changes, and set up a development + environment. + + [:octicons-arrow-right-24: Contributing](contributing.md) + +- **Feedback** + + --- + + We welcome all feedback while we develop, and we use it to drive the + direction of the SDK. Tell us what you like, dislike, or want to see next. + + [:octicons-arrow-right-24: Open a GitHub issue](https://github.com/aws/aws-sdk-python/issues/new/choose) + +
From 74ba2381030f76a9586a76de80dad5104a26fef7 Mon Sep 17 00:00:00 2001 From: jonathan343 Date: Thu, 20 Aug 2026 22:51:56 -0400 Subject: [PATCH 2/4] updates --- docs/index.md | 54 ++++++++++++++++++++------------------------------- 1 file changed, 21 insertions(+), 33 deletions(-) diff --git a/docs/index.md b/docs/index.md index 56e0fd1..dd6b6ca 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,11 +33,19 @@ extra stub packages. ## Installation Each service client is its own package on PyPI and requires Python 3.12 or -later. Create and activate a virtual environment and then install the clients -you need: +later. Create and activate a virtual environment, then install the clients you +need: ```bash -pip install aws-sdk-bedrock-runtime +pip install aws-sdk-dynamodb +``` + +If your application uses several services, you can instead install the +`aws-sdk-python` meta-package and select clients as extras. It coordinates +compatible client versions through its own `MAJOR.MINOR` version: + +```bash +pip install "aws-sdk-python[bedrock_runtime,sts]" ``` See [Available Clients](clients/index.md) for the full list of service @@ -45,48 +53,28 @@ packages. ## Quick example -Send a message to a model with the Amazon Bedrock Runtime client: +List your DynamoDB tables with the Amazon DynamoDB client: ```python import asyncio -from aws_sdk_bedrock_runtime.client import BedrockRuntimeClient, ConverseInput -from aws_sdk_bedrock_runtime.config import Config -from aws_sdk_bedrock_runtime.models import ContentBlockText, Message -from smithy_aws_core.identity import EnvironmentCredentialsResolver +from aws_sdk_dynamodb.client import AsyncDynamoDBClient +from aws_sdk_dynamodb.config import AsyncDynamoDBConfig +from aws_sdk_dynamodb.models import ListTablesInput async def main(): - client = BedrockRuntimeClient( - config=Config( - region="us-east-1", - aws_credentials_identity_resolver=EnvironmentCredentialsResolver(), - ) - ) - - response = await client.converse( - ConverseInput( - model_id="global.anthropic.claude-opus-4-8", # (1)! - messages=[ - Message( - role="user", - content=[ContentBlockText(value="Tell me a fun fact about Python.")], - ) - ], - ) - ) - - print(response.output.value.content[0].value) + config = await AsyncDynamoDBConfig.resolve(region="us-east-1") + + async with AsyncDynamoDBClient(config=config) as client: + response = await client.list_tables(input=ListTablesInput(limit=10)) + for table in response.table_names or []: + print(table) asyncio.run(main()) ``` -1. This model may not be the latest available and could be deprecated in the - future. See [Models at a glance](https://docs.aws.amazon.com/bedrock/latest/userguide/model-cards.html) - in the Amazon Bedrock User Guide for the current list of models and their - IDs. - ## Explore
From 8743ceda5a67db78a3d5c8875c0238af727eb845 Mon Sep 17 00:00:00 2001 From: jonathan343 Date: Thu, 20 Aug 2026 23:59:23 -0400 Subject: [PATCH 3/4] Improve API reference overview and add Developer Preview banner --- docs/index.md | 134 ++++++++++++++++--------------------- docs/stylesheets/extra.css | 26 +++++++ overrides/main.html | 8 +++ zensical.toml | 7 ++ 4 files changed, 100 insertions(+), 75 deletions(-) create mode 100644 overrides/main.html diff --git a/docs/index.md b/docs/index.md index dd6b6ca..8bf388b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,59 +1,64 @@ # AWS SDK for Python -Async-first clients for AWS services, distributed as one lightweight package -per service. - -Unlike [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html), -these clients are built from the ground up on Python's `async`/`await`. They -target select AWS services that benefit most from asynchronous I/O, such as -streaming and real-time inference APIs. Each client is generated from its -service's [Smithy](https://smithy.io/) model and is fully type-annotated, so -your editor can autocomplete operations, inputs, and response shapes without -extra stub packages. - -!!! warning "Developer Preview — not for production use" - - This SDK is in Developer Preview and is intended for evaluation and testing - in pre-production environments only. APIs and behavior may change before - general availability. For production workloads, use - [Boto3](https://github.com/boto/boto3) — the generally available AWS SDK - for Python with full coverage of all AWS services. - -## Highlights - -- **Async first**: Every operation is a coroutine, designed for - `asyncio`-based applications. -- **Per-service packages**: Install only the clients you need. Each package is - versioned and released independently. -- **Fully typed**: Generated dataclass models and annotated signatures for - every operation. +The AWS SDK for Python provides async-first clients for select AWS services. +Each client is distributed as a lightweight, per-service package. + +!!! warning "Developer Preview: Not for production use" + + This SDK is intended for evaluation and testing in pre-production + environments. APIs and behavior may change before general availability. For + production workloads, use + [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html). + +[Browse clients](clients/index.md){ .md-button .md-button--primary } +[View source](https://github.com/aws/aws-sdk-python){ .md-button } + +## What it provides + +Use these clients when your application needs non-blocking access to supported +AWS services, including services with streaming and real-time APIs. The clients +are built on Python's `async`/`await` and generated from +[Smithy](https://smithy.io/) service models. + +- **Async operations**: Call AWS services without blocking an `asyncio` + application. +- **Per-service packages**: Install only the clients your application needs. +- **Type annotations**: Get editor completion and type checking for operations, + input models, and response models without separate stub packages. - **Streaming support**: First-class support for event streams and bidirectional streaming operations. -## Installation +## Packages -Each service client is its own package on PyPI and requires Python 3.12 or -later. Create and activate a virtual environment, then install the clients you -need: +The clients require Python 3.12 or later. Choose a per-service package or use +the `aws-sdk-python` meta-package for a compatible set of clients. -```bash -pip install aws-sdk-dynamodb -``` +=== "One service" -If your application uses several services, you can instead install the -`aws-sdk-python` meta-package and select clients as extras. It coordinates -compatible client versions through its own `MAJOR.MINOR` version: + Install only the client you need. For example, install the Amazon DynamoDB + client with: -```bash -pip install "aws-sdk-python[bedrock_runtime,sts]" -``` + ```bash + pip install aws-sdk-dynamodb + ``` + +=== "Multiple services" + + Select clients as extras of the `aws-sdk-python` meta-package. The + meta-package selects compatible client versions for you: + + ```bash + pip install "aws-sdk-python[bedrock_runtime,sts]" + ``` See [Available Clients](clients/index.md) for the full list of service packages. -## Quick example +## Example -List your DynamoDB tables with the Amazon DynamoDB client: +After you [configure AWS credentials](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) +and grant permission to call `dynamodb:ListTables`, you can list your DynamoDB +tables: ```python import asyncio @@ -65,44 +70,23 @@ from aws_sdk_dynamodb.models import ListTablesInput async def main(): config = await AsyncDynamoDBConfig.resolve(region="us-east-1") + client = AsyncDynamoDBClient(config=config) - async with AsyncDynamoDBClient(config=config) as client: - response = await client.list_tables(input=ListTablesInput(limit=10)) - for table in response.table_names or []: - print(table) + response = await client.list_tables(input=ListTablesInput(limit=10)) + for table in response.table_names or []: + print(table) asyncio.run(main()) ``` -## Explore - -
- -- **Available Clients** - - --- - - Browse the full API reference for every service client in the SDK. - - [:octicons-arrow-right-24: Available Clients](clients/index.md) - -- **Contributing** - - --- - - Learn how to report issues, propose changes, and set up a development - environment. - - [:octicons-arrow-right-24: Contributing](contributing.md) - -- **Feedback** - - --- - - We welcome all feedback while we develop, and we use it to drive the - direction of the SDK. Tell us what you like, dislike, or want to see next. +The configuration resolver can load credentials and other shared settings from +the standard AWS configuration sources. Each client operation accepts a typed +input model and returns a typed response model. - [:octicons-arrow-right-24: Open a GitHub issue](https://github.com/aws/aws-sdk-python/issues/new/choose) +## Next steps -
+- Browse the [available clients and API reference](clients/index.md). +- Learn how to [contribute to the SDK](contributing.md). +- [Open a GitHub issue](https://github.com/aws/aws-sdk-python/issues/new/choose) + to report a problem or share feedback. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 4e555dd..d04cb0f 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -12,3 +12,29 @@ p:has(span.breadcrumb) { [data-md-color-scheme="default"] .md-header__button.md-logo img { content: url('../assets/aws-logo-dark.svg'); } + +/* Keep the Developer Preview announcement prominent across the docs site. */ +.md-banner { + background-color: #ffe0a3; + color: #291b00; +} + +[data-md-color-scheme="slate"] .md-banner { + background-color: #332407; + color: #fff4d6; +} + +.md-banner__inner { + font-size: 0.72rem; +} + +.md-banner__inner strong, +.md-banner__inner a { + font-weight: 700; +} + +.md-banner__inner a { + color: inherit; + text-decoration: underline; + text-underline-offset: 0.1em; +} diff --git a/overrides/main.html b/overrides/main.html new file mode 100644 index 0000000..2735af0 --- /dev/null +++ b/overrides/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block announce %} + Developer Preview: + This SDK is not for production use, and its APIs and behavior may change. + For production workloads, use + Boto3. +{% endblock %} diff --git a/zensical.toml b/zensical.toml index 708c629..d1aab20 100644 --- a/zensical.toml +++ b/zensical.toml @@ -30,15 +30,21 @@ nav = [ { "Bedrock AgentCore" = "clients/bedrock-agentcore/index.md" }, { "Bedrock AgentCore Control" = "clients/bedrock-agentcore-control/index.md" }, { "Bedrock Data Automation" = "clients/bedrock-data-automation/index.md" }, + { "Bedrock Data Automation Runtime" = "clients/bedrock-data-automation-runtime/index.md" }, { "Bedrock Runtime" = "clients/bedrock-runtime/index.md" }, + { "CloudTrail" = "clients/cloudtrail/index.md" }, + { "Cognito Identity" = "clients/cognito-identity/index.md" }, { "ConnectHealth" = "clients/connecthealth/index.md" }, + { "DynamoDB" = "clients/dynamodb/index.md" }, { "GuardDuty" = "clients/guardduty/index.md" }, { "Lambda" = "clients/lambda/index.md" }, { "Lex Runtime V2" = "clients/lex-runtime-v2/index.md" }, { "Polly" = "clients/polly/index.md" }, { "QBusiness" = "clients/qbusiness/index.md" }, { "SageMaker Runtime HTTP2" = "clients/sagemaker-runtime-http2/index.md" }, + { "Secrets Manager" = "clients/secrets-manager/index.md" }, { "SNS" = "clients/sns/index.md" }, + { "SQS" = "clients/sqs/index.md" }, { "STS" = "clients/sts/index.md" }, { "Transcribe Streaming" = "clients/transcribe-streaming/index.md" }, ] }, @@ -55,6 +61,7 @@ extra_javascript = [{ path = "javascript/nav-expand.js", defer = true }] # ---------------------------------------------------------------------------- [project.theme] language = "en" +custom_dir = "overrides" features = [ # Zensical includes an announcement bar. This feature allows users to From f04bbc000cd77fffd7bd230d194ab966093e6960 Mon Sep 17 00:00:00 2001 From: jonathan343 Date: Fri, 21 Aug 2026 01:43:16 -0400 Subject: [PATCH 4/4] unslop --- docs/index.md | 78 ++++++++++++++++++++++++--------------------------- 1 file changed, 37 insertions(+), 41 deletions(-) diff --git a/docs/index.md b/docs/index.md index 8bf388b..b04544f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,64 +1,61 @@ # AWS SDK for Python -The AWS SDK for Python provides async-first clients for select AWS services. -Each client is distributed as a lightweight, per-service package. +The AWS SDK for Python provides asynchronous clients for supported AWS services. +Each service has its own package. -!!! warning "Developer Preview: Not for production use" +!!! warning "Developer preview: Not for production use" - This SDK is intended for evaluation and testing in pre-production - environments. APIs and behavior may change before general availability. For - production workloads, use - [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html). + Use this SDK for evaluation and pre-production testing. Interfaces and + behavior may change before general availability. Use + [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) + for production workloads. [Browse clients](clients/index.md){ .md-button .md-button--primary } [View source](https://github.com/aws/aws-sdk-python){ .md-button } -## What it provides +## Features -Use these clients when your application needs non-blocking access to supported -AWS services, including services with streaming and real-time APIs. The clients -are built on Python's `async`/`await` and generated from -[Smithy](https://smithy.io/) service models. +- **Async operations.** Every service operation is an `async` method that works + with `asyncio`. +- **Per-service packages.** Install only the clients your application uses. +- **Type annotations.** Operations, input models, and response models include + type annotations, so editors and type checkers do not need separate stub + packages. +- **Streaming support.** Clients for streaming services support event streams + and bidirectional streaming. -- **Async operations**: Call AWS services without blocking an `asyncio` - application. -- **Per-service packages**: Install only the clients your application needs. -- **Type annotations**: Get editor completion and type checking for operations, - input models, and response models without separate stub packages. -- **Streaming support**: First-class support for event streams and - bidirectional streaming operations. +The code generator builds each client from its service's +[Smithy](https://smithy.io/) model. -## Packages +## Install a client -The clients require Python 3.12 or later. Choose a per-service package or use -the `aws-sdk-python` meta-package for a compatible set of clients. +The clients require Python 3.12 or later. -=== "One service" +=== "One client" - Install only the client you need. For example, install the Amazon DynamoDB - client with: + Install the Amazon DynamoDB client from its service package: ```bash pip install aws-sdk-dynamodb ``` -=== "Multiple services" +=== "Several clients" - Select clients as extras of the `aws-sdk-python` meta-package. The - meta-package selects compatible client versions for you: + The `aws-sdk-python` meta-package keeps its client dependencies on + compatible versions. Select the clients you need through package extras: ```bash pip install "aws-sdk-python[bedrock_runtime,sts]" ``` -See [Available Clients](clients/index.md) for the full list of service -packages. +The [available clients](clients/index.md) page lists every service package. -## Example +## List DynamoDB tables After you [configure AWS credentials](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) -and grant permission to call `dynamodb:ListTables`, you can list your DynamoDB -tables: +and grant `dynamodb:ListTables` permission, use the +[Amazon DynamoDB client](clients/dynamodb/index.md) to list up to ten tables in +`us-east-1`: ```python import asyncio @@ -80,13 +77,12 @@ async def main(): asyncio.run(main()) ``` -The configuration resolver can load credentials and other shared settings from -the standard AWS configuration sources. Each client operation accepts a typed -input model and returns a typed response model. +`AsyncDynamoDBConfig.resolve()` loads credentials and other shared settings +from the standard AWS configuration sources. The `region` argument overrides +the configured region for this client. -## Next steps +## Documentation and support -- Browse the [available clients and API reference](clients/index.md). -- Learn how to [contribute to the SDK](contributing.md). -- [Open a GitHub issue](https://github.com/aws/aws-sdk-python/issues/new/choose) - to report a problem or share feedback. +- [Browse client API references](clients/index.md) +- [Contribute to the SDK](contributing.md) +- [Report a bug or request a feature](https://github.com/aws/aws-sdk-python/issues/new/choose)