async with S3Client(config) as s3:
    await s3.put_bytes("notes/hello.txt", b"hello world", content_type=S3ContentType.PLAIN)
    content = await s3.get_bytes("notes/hello.txt")

import asyncio
from async_s3 import S3Client, S3Config, S3ContentType


async def main() -> None:
    config = S3Config(
        endpoint_url="https://s3.example.com",
        region="us-east-1",
        bucket="my-bucket",
        access_key_id="YOUR_ACCESS_KEY",
        secret_access_key="YOUR_SECRET_KEY",
    )

    async with S3Client(config) as s3:
        await s3.put_bytes("notes/hello.txt", b"hello world", content_type=S3ContentType.PLAIN)

        content = await s3.get_bytes("notes/hello.txt")
        print(content.decode())  # hello world


asyncio.run(main())

async with S3Client(config) as s3:
    await s3.put_bytes("data/record.json", payload, content_type=S3ContentType.JSON)
    raw = await s3.get_bytes("data/record.json")

from pathlib import Path

async with S3Client(config) as s3:
    await s3.put_file("backups/report.csv", Path("report.csv"))
    await s3.get_file("backups/report.csv", Path("downloads/report.csv"), overwrite=True)

async with S3Client(config) as s3:
    # Stream upload from any BinaryIO
    with open("big-video.mp4", "rb") as f:
        await s3.put_stream("media/big-video.mp4", f, content_type=S3ContentType.MP4)

    # Stream download into any writable BinaryIO
    with open("local-copy.mp4", "wb") as f:
        bytes_written = await s3.get_stream("media/big-video.mp4", f)

    print(f"Downloaded {bytes_written} bytes")

from async_s3 import S3ObjectNotFoundError

async with S3Client(config) as s3:
    if await s3.exists("images/cat.png"):
        data = await s3.get_bytes("images/cat.png")
        print(f"downloaded {len(data)} bytes")

    try:
        await s3.get_bytes("images/missing.png")
    except S3ObjectNotFoundError as e:
        print(f"not found: {e.key}")

async with S3Client(config) as s3:
    # All keys under a prefix — pagination is handled automatically
    keys = await s3.list_keys("uploads/")
    print(keys)  # ["uploads/a.txt", "uploads/b.txt", ...]

    # Immediate logical "subdirectories" one level deep
    prefixes = await s3.list_subprefixes("projects/")
    print(prefixes)  # ["projects/alpha/", "projects/beta/"]

    # Both accept None or "" to mean the bucket root
    all_keys = await s3.list_keys()

async with S3Client(config) as s3:
    # Delete a single object
    await s3.delete_key("tmp/old-file.txt")

    # Delete a specific set of keys (batched automatically, up to 1000 per request)
    deleted = await s3.delete_keys(["tmp/a.txt", "tmp/b.txt", "tmp/c.txt"])
    print(f"Deleted {deleted} objects")

    # Delete everything under a prefix
    deleted = await s3.delete_prefix("tmp/")
    print(f"Deleted {deleted} objects")

    # Delete the entire bucket contents — requires explicit opt-in
    deleted = await s3.delete_prefix("", allow_root=True)

async with S3Client(config) as s3:
    await s3.move(
        source_key="uploads/video.mp4",
        target_key="archive/video.mp4",
        overwrite=False,  # raises ValueError if target already exists
    )

# Join path segments into a clean S3 key (strips stray slashes)
key = S3Client.join("users", "42", "avatar.png")
print(key)    # users/42/avatar.png

# Split a key back into parts (ignores leading/trailing/repeated slashes)
parts = S3Client.split("/users/42/avatar.png/")
print(parts)  # ["users", "42", "avatar.png"]

s3 = S3Client(config)
await s3.open()
try:
    await s3.put_bytes("notes/manual.txt", b"manual lifecycle")
finally:
    await s3.close()

await s3.put_bytes("model.onnx", data, content_type="application/octet-stream")

from async_s3 import (
    S3OperationError,
    S3ObjectNotFoundError,
    S3BatchDeleteError,
    S3MoveObjectError,
)

try:
    await s3.move("uploads/video.mp4", "archive/video.mp4")
except S3ObjectNotFoundError as e:
    print(f"source key missing: {e.key}")
except S3MoveObjectError as e:
    # e.stage is "copy" or "delete_source"
    print(f"move failed at '{e.stage}' stage: {e.source_key} -> {e.target_key}")
except S3OperationError as e:
    print(f"s3 error in bucket '{e.bucket}': {e}")