Metadata-Version: 2.4
Name: s3-storage
Version: 0.1.0
Summary: Simple and reusable S3 file upload/delete utilities for Python applications.
Author-email: Cristian Escobar <caes1996@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/s3-storage
Project-URL: Repository, https://github.com/yourusername/s3-storage
Project-URL: Issues, https://github.com/yourusername/s3-storage/issues
Keywords: s3,aws,upload,storage,boto3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3>=1.28.0
Requires-Dist: pydantic-settings>=2.0.0
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
Requires-Dist: python-multipart>=0.0.6; extra == "fastapi"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: moto[s3]>=4.0.0; extra == "dev"
Dynamic: license-file

# s3-storage

[![Tests](https://github.com/yourusername/s3-storage/actions/workflows/tests.yml/badge.svg)](https://github.com/yourusername/s3-storage/actions/workflows/tests.yml)
[![PyPI version](https://badge.fury.io/py/s3-storage.svg)](https://badge.fury.io/py/s3-storage)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install s3-storage
```

For FastAPI integration:

```bash
pip install s3-storage[fastapi]
```

## Configuration

Set the following environment variables:

```bash
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:

```python
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

```python
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

```python
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

```python
from s3_storage import delete_file_async

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

### Replace a file

```python
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

```python
from s3_storage import upload_multiple_async

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

## S3-compatible services

For MinIO or similar services:

```python
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

```bash
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

```bash
pytest
```

## License

MIT
