storage-kernel-provider-aws-s3

AWS S3 provider for Storage Kernel.

This provider maps StorageLocation.bucket to an S3 bucket and StorageLocation.prefix to an object-key namespace.

Install

uv add storage-kernel-contracts storage-kernel-provider-aws-s3

Usage

from storage_kernel.contracts import StorageClientOptions, StorageLocation
from storage_kernel.provider_aws_s3 import (
    AwsS3StorageProviderOptions,
    create_aws_s3_storage_client,
)

storage = create_aws_s3_storage_client(
    StorageClientOptions(location=StorageLocation(bucket="my-bucket", prefix="prod")),
    AwsS3StorageProviderOptions(region="us-east-1"),
)

await storage.send_content("docs/readme.txt", "Hello")

The provider uses boto3 behind the provider boundary. When credentials and client are omitted, authentication follows the standard boto3 credential provider chain. An injected client is caller-owned and may be used for custom SDK configuration or tests.

Provider Options

Capabilities

• full binary and text reads/writes
• object read streams
• multipart-backed writable upload streams with explicit enablement, bounded part concurrency and optional part retention on errors
• prefix-based directory listing and recursive deletion
• same-provider native copy
• S3 presigned URLs
• public URLs through public_base_url or S3 bucket URL conventions

Provider SDK errors are normalized into Storage Kernel errors such as path not found, permission denied and provider error.