Metadata-Version: 2.5
Name: storage-kernel-provider-aws-s3
Version: 0.1.0a1
Summary: AWS S3 provider package for Storage Kernel.
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: boto3
Requires-Dist: storage-kernel-contracts<0.2.0,>=0.1.0a1
Requires-Dist: storage-kernel-core<0.2.0,>=0.1.0a1
Description-Content-Type: text/markdown

# 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

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

## Usage

```python
from storage_kernel.contracts import StorageClientOptions, StorageLocation, StoragePath
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(StoragePath("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

| Option | Purpose |
| --- | --- |
| `region` | AWS region used by the SDK and default public URL generation |
| `credentials` | Explicit credentials dictionary passed to the SDK factory |
| `public_base_url` | Optional CDN/custom base URL for `get_public_url` |
| `client` | Optional caller-owned boto3 S3 client |

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