diff --git a/docs/index.md b/docs/index.md index 31cb0f2..c82d97a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,114 @@ # AWS SDK for Python ---8<-- "README.md:2" +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" + + 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 } + +## Features + +- **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. + +The code generator builds each client from its service's +[Smithy](https://smithy.io/) model. + +## Install a client + +The clients require Python 3.12 or later. Follow the +[uv installation guide](https://docs.astral.sh/uv/getting-started/installation/), +then create and activate a virtual environment: + +```bash +uv venv --python 3.12 +source .venv/bin/activate +``` + +=== "One client" + + Install the Amazon DynamoDB client from its service package: + + ```bash + uv pip install aws-sdk-dynamodb + ``` + +=== "Several clients" + + Use the `aws-sdk-python` meta-package to install several clients at + compatible versions. Select clients with package extras: + + ```bash + uv pip install "aws-sdk-python[bedrock-runtime,sts]" + ``` + +See [available clients](clients/index.md) for a list of service packages. + +## List DynamoDB tables + +Before running the example, grant an identity `dynamodb:ListTables` permission +and configure AWS credentials. The default credential chain checks these +built-in sources: + +- Environment variables such as `AWS_ACCESS_KEY_ID`, + `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` +- Shared AWS config and credentials files, including `credential_process` + +Other supported providers come from `aws-credentials-*` packages. Install and +configure the package for your environment: + +- `aws-credentials-sts` for profile-based AssumeRole +- `aws-credentials-http` for Amazon ECS or Amazon EKS container credentials +- `aws-credentials-imds` for Amazon EC2 instance metadata + +The SDK detects installed provider packages and adds them to the chain +automatically. You do not need to pass a credential resolver or change the +client code. The IAM Identity Center (SSO) credential provider and the login +credentials provider are not yet supported. + +Use the [Amazon DynamoDB client](clients/dynamodb/index.md) to list up to ten +tables in `us-east-1`: + +```python +import asyncio + +from aws_sdk_dynamodb.client import AsyncDynamoDBClient +from aws_sdk_dynamodb.config import AsyncDynamoDBConfig +from aws_sdk_dynamodb.models import ListTablesInput + + +async def main(): + 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: + print(table) + + +asyncio.run(main()) +``` + +`AsyncDynamoDBConfig.resolve()` loads shared settings such as retry +configuration. Here, the `region` argument overrides a region set in the +environment or shared config. The client resolves credentials through the +default chain when it sends the request. + +## Documentation and support + +- [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) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 4e555dd..3a12674 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -12,3 +12,31 @@ 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; + border-bottom: 1px solid #d98b00; + color: #291b00; +} + +[data-md-color-scheme="slate"] .md-banner { + background-color: #332407; + border-bottom-color: #8f650b; + 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