Metadata-Version: 2.4
Name: tiny-object-storage
Version: 0.1.1
Summary: A lightweight S3-compatible object storage server for local development and learning.
Author: Ehsan Bitaraf
License: MIT
Project-URL: Homepage, https://github.com/EhsanBitaraf/tiny-object-storage
Project-URL: Repository, https://github.com/EhsanBitaraf/tiny-object-storage
Project-URL: Bug Tracker, https://github.com/EhsanBitaraf/tiny-object-storage/issues
Keywords: s3,object-storage,minio,aws-s3,emulator,s3-compatible,mock,testing,fastapi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1.0.0,>=0.115.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.30.0
Requires-Dist: pydantic<3.0.0,>=2.8.0
Requires-Dist: pydantic-settings<3.0.0,>=2.4.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.1
Requires-Dist: python-multipart<1.0.0,>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
Requires-Dist: pytest-cov<6.0.0,>=5.0.0; extra == "dev"
Requires-Dist: httpx<1.0.0,>=0.27.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.6.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.11.0; extra == "dev"
Requires-Dist: bandit<2.0.0,>=1.7.9; extra == "dev"
Requires-Dist: safety<4.0.0,>=3.2.0; extra == "dev"
Requires-Dist: pre-commit<4.0.0,>=3.8.0; extra == "dev"
Dynamic: license-file

<div align="center">
  <img src="assets/logo.png" alt="tiny-object-storage logo" width="180" height="auto" />
  <h1>🪣 tiny-object-storage</h1>
  <p><i>A lightweight, S3-compatible object storage server for local development, testing, and learning.</i></p>

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg?logo=python&logoColor=white)](https://www.python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-009688.svg?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Mypy Strict](https://img.shields.io/badge/mypy-strict-success.svg)](https://mypy.readthedocs.io/en/stable/)
[![Security: Bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![Coverage: 91%](https://img.shields.io/badge/Coverage-91%25-brightgreen.svg)](https://pytest-cov.readthedocs.io/en/latest/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

</div>

---

## 📖 Overview

`tiny-object-storage` is a fast, minimalistic object storage server written in Python using FastAPI. It acts as a local emulator that mimics the core functionality of Amazon S3, allowing developers to test S3-integrated applications locally without relying on external cloud services or heavy containers like MinIO.

## ✨ Features

- **S3 Compatibility**: Supports core S3 XML responses and basic HTTP methods (`GET`, `PUT`, `HEAD`, `DELETE`).
- **Bucket Management**: Create, list, and delete buckets.
- **Object Operations**: Upload, download, metadata lookup, listing (`list-type=2`), and deletion.
- **Persistent Storage**: Filesystem-based persistence with dedicated metadata and data separation.
- **Developer Experience**: Interactive Swagger UI and OpenAPI schema built-in.
- **Enterprise Code Quality**: Enforced static typing (Mypy strict), linting (Ruff), and security analysis (Bandit).
- **Flexible Configuration**: Configurable via CLI arguments, environment variables, or `.env` files.

---

## 🚀 Quick Start

### Installation

**From PyPI (Recommended)**
Install the package globally or in a virtual environment using `pip`:

```bash
pip install tiny-object-storage
```

**From Source (Development)**
Clone the repository and install it in a virtual environment:

```bash
git clone https://github.com/EhsanBitaraf/tiny-object-storage.git
cd tiny-object-storage
python -m venv .venv

# On Linux/macOS:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install the application and development dependencies
pip install -e ".[dev]"
```

### Running the Server

Start the server using the built-in CLI:

```bash
tos-server
```

Or run it directly with `uvicorn`:
```bash
uvicorn tiny_object_storage.main:app --reload --host 0.0.0.0 --port 9000
```

---

## ⚙️ Configuration

The server reads configuration in the following priority (highest to lowest):
1. **Command-line arguments**
2. **Environment variables**
3. **`.env` file**

### CLI Usage Examples

```bash
# View all available options
tos-server --help

# Load from a specific .env file
tos-server --env-file .env.custom

# Override host and port
tos-server --host 127.0.0.1 --port 9001 --reload

# Customize storage directories and log level
tos-server --data-dir ./storage_data --log-dir ./logs --log-level debug
```

---

## 🔌 S3 Client Compatibility

`tiny-object-storage` acts as a local emulator and has been successfully verified against the following official SDKs and tools:

- **MinIO Python SDK**
- **Boto3 (AWS SDK for Python)**
- **AWS CLI**

> **Note:** For official SDKs to interact locally, configure them with `secure=False` (or `--no-verify-ssl`) and point the `endpoint_url` to `http://127.0.0.1:9000` with any dummy credentials.

Sample scripts for verifying SDK interactions are included in the repository root (e.g., `test_boto3_sdk.py`, `test_minio_sdk.py`).

---

## 🛠 Testing & Code Quality

The project includes an extensive test suite built with `pytest` achieving **100% test pass rate** over 63 edge-case scenarios.

### Running Tests

```bash
pytest
```
*(Optionally, use `pytest --cov=src` to generate a coverage report).*

### Code Quality Tools

We use `pre-commit` to maintain our code quality. The suite includes:
- **Ruff**: For ultra-fast linting and code formatting.
- **Mypy**: For strict static type checking.
- **Bandit**: For security vulnerability scanning.

To run checks manually on all files:
```bash
pre-commit run --all-files
```

---

## 🌐 API Endpoints (Examples)

After starting the server, visit `/docs` for the interactive Swagger UI. Below are standard `curl` examples targeting common S3 actions:

**Health check**
```bash
curl http://127.0.0.1:9000/health
```

**Create a bucket**
```bash
curl -X PUT http://127.0.0.1:9000/photos
```

**Upload an object**
```bash
curl -X PUT --data-binary @"cat.jpg" http://127.0.0.1:9000/photos/cat.jpg
```

**Download an object**
```bash
curl http://127.0.0.1:9000/photos/cat.jpg --output cat.jpg
```

**List objects (S3 Format)**
```bash
curl "http://127.0.0.1:9000/photos?list-type=2"
```

**Debug endpoints (JSON format)**
```bash
curl http://127.0.0.1:9000/_debug/buckets
curl http://127.0.0.1:9000/_debug/photos
```

---

## 🤝 Contributing

Contributions are welcome and highly appreciated! Please review our [Contributing Guidelines](CONTRIBUTING.md) to get started. By participating in this project, you agree to abide by the [Code of Conduct](.github/CODE_OF_CONDUCT.md).

## 🔒 Security

For instructions on reporting security vulnerabilities, please refer to our [Security Policy](SECURITY.md).

## 📜 License

This project is licensed under the MIT License - see the `LICENSE` file for details.
