s3-storage

Simple and reusable S3 file upload/delete utilities for Python applications.

Works with FastAPI, Flask, Django, or any plain Python project.

Features

• Upload files, images, videos, and documents.
• Async support via thread pool.
• File type and size validation.
• Delete and replace files.
• Works with AWS S3 and S3-compatible services (MinIO, Wasabi, DigitalOcean Spaces, etc.).
• Configurable via environment variables or explicit settings.

Installation

pip install s3-storage

For FastAPI integration:

pip install s3-storage[fastapi]

Configuration

Set the following environment variables:

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION_NAME=us-east-1
AWS_BUCKET_NAME=your_bucket_name
AWS_DEFAULT_ACL=public-read  # optional

Or create an S3StorageSettings instance manually:

from s3_storage import S3StorageSettings

settings = S3StorageSettings(
    access_key_id="your_access_key",
    secret_access_key="your_secret_key",
    region_name="us-east-1",
    bucket_name="your_bucket_name",
    default_acl="public-read",
)

Usage

FastAPI example

from fastapi import FastAPI, UploadFile, File
from s3_storage import upload_image_async

app = FastAPI()

@app.post("/upload-avatar")
async def upload_avatar(file: UploadFile = File(...)):
    url = await upload_image_async(file, folder="users/avatars")
    return {"url": url}

Synchronous example

from s3_storage import upload_file

with open("report.pdf", "rb") as f:
    url = upload_file(f, folder="documents", max_size_mb=10)
    print(url)

Delete a file

from s3_storage import delete_file_async

await delete_file_async("https://bucket.s3.region.amazonaws.com/users/avatars/old.jpg")

Replace a file

from s3_storage import replace_file

new_url = await replace_file(
    old_file_url="https://bucket.s3.region.amazonaws.com/users/avatars/old.jpg",
    new_file=new_file,
    folder="users/avatars",
)

Upload multiple files

from s3_storage import upload_multiple_async

urls = await upload_multiple_async(files, folder="gallery")

S3-compatible services

For MinIO or similar services:

settings = S3StorageSettings(
    access_key_id="minioadmin",
    secret_access_key="minioadmin",
    region_name="us-east-1",
    bucket_name="mybucket",
    endpoint_url="http://localhost:9000",
    path_style=True,
    default_acl="public-read",
)

url = await upload_file_async(file, folder="uploads", settings=settings)

Development

git clone https://github.com/yourusername/s3-storage.git
cd s3-storage
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

Running tests

pytest

License

MIT