Metadata-Version: 2.4
Name: chatstorage3
Version: 0.0.3
Summary: S3-like file storage using messaging platforms
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

<p align="center">
  <img src="https://raw.githubusercontent.com/MrMrProgrammer/chatstorage3/main/assets/logo.png" alt="ChatStorage3 Logo" width="300">
</p>

<h1 align="center">ChatStorage3</h1>

<p align="center">
  A boto3-inspired object storage library powered by chat platforms.
</p>

<p align="center">
  Store and retrieve files using platforms like Bale and Telegram with a simple object storage API.
</p>

<p align="center">
  <a href="https://pypi.org/project/chatstorage3/">
    <img src="https://badge.fury.io/py/chatstorage3.svg" alt="PyPI version">
  </a>
  <img src="https://img.shields.io/badge/python-3.10%2B-blue">
</p>

---

# ChatStorage3

ChatStorage3 is a lightweight object storage library inspired by `boto3`.

Instead of relying on traditional object storage services, ChatStorage3 uses chat platforms as storage backends and provides a simple API for uploading, downloading, and managing files.

It is designed for applications that need lightweight storage for:

- Product images
- User uploads
- Documents
- Small videos
- Media assets

without managing additional storage infrastructure.

---

# Features

- Boto3-inspired object storage API
- Upload and download files
- Upload from file objects
- Download to file objects
- Object metadata management
- Persistent object indexing using SQLite
- Provider-based architecture
- Multiple storage backend support
- Support for Bale and Telegram
- Designed for Django and FastAPI integrations

---

# How It Works

ChatStorage3 separates storage logic from storage providers.

```text
Application
    |
    v
ChatStorage3 Client
    |
    +----------------+
    |                |
    v                v
Object Index     Provider
(SQLite)         (Bale/Telegram)
                    |
                    v
             Chat Platform
```

Files are stored on the chat platform.

ChatStorage3 maintains the mapping between:

```text
Bucket + Key
      |
      v
   File ID
      |
      v
 Stored File
```

The index layer allows ChatStorage3 to provide a storage API similar to object storage systems.

---

# Installation

```bash
pip install chatstorage3
```

---

# Quick Start

```python
import chatstorage3


storage = chatstorage3.client(
    "s3",
    provider="bale",
    token="YOUR_BOT_TOKEN",
    chat_id="YOUR_CHAT_ID",
)
```

---

# Upload File

```python
storage.upload_file(
    "image.jpg",
    "products",
    "image.jpg",
)
```

---

# Download File

```python
storage.download_file(
    "products",
    "image.jpg",
    "downloaded.jpg",
)
```

---

# Upload Object

Upload raw bytes directly:

```python
storage.put_object(
    Bucket="products",
    Key="hello.txt",
    Body=b"Hello ChatStorage3!",
    ContentType="text/plain",
)
```

---

# Get Object

```python
response = storage.get_object(
    Bucket="products",
    Key="hello.txt",
)

content = response["Body"].read()

print(content)
```

Output:

```text
b'Hello ChatStorage3!'
```

---

# File Objects

ChatStorage3 supports file-like objects:

```python
from io import BytesIO


file = BytesIO(
    b"Hello from file object"
)


storage.upload_fileobj(
    file,
    "products",
    "file.txt",
)
```

Download:

```python
output = BytesIO()


storage.download_fileobj(
    "products",
    "file.txt",
    output,
)


output.seek(0)

print(output.read())
```

---

# Object Metadata

Retrieve object metadata:

```python
metadata = storage.head_object(
    Bucket="products",
    Key="image.jpg",
)
```

Example:

```python
{
    "ContentLength": 1710092,
    "ContentType": "image/png",
    "FileName": "image.jpg",
    "FileId": "..."
}
```

---

# Providers

ChatStorage3 uses a provider architecture.

| Provider | Status |
|----------|--------|
| Bale | ✅ Available |
| Telegram | ✅ Available |

Adding a new provider only requires implementing the provider interface.

---

# Architecture

```text
chatstorage3

├── Client
│
├── Providers
│   ├── BaleProvider
│   └── TelegramProvider
│
└── Index
    └── SQLiteIndex
```

---

# Testing

Run tests:

```bash
pytest -v
```

Current tests cover:

- File upload lifecycle
- File download verification
- SQLite index operations
- Object lookup errors
- Multiple storage providers

---

# Roadmap

- [x] Bale provider
- [x] Telegram provider
- [x] SQLite object index
- [x] boto3-inspired API
- [x] File upload/download
- [x] File object support
- [ ] Django Storage backend
- [ ] Async API
- [ ] Object deletion support
- [ ] More storage providers

---

# License

MIT License

---

# Author

Developed by **MrMrProgrammer**

For more projects and information:

- GitHub: https://github.com/MrMrProgrammer
- Website: https://mrmrprogrammer.ir

---

# Links


<p align="center">


  <a href="https://pypi.org/project/chatstorage3/">
    <img src="https://img.shields.io/badge/PyPI-chatstorage3-blue?logo=pypi">
  </a>

  <a href="https://github.com/MrMrProgrammer/chatstorage3">
    <img src="https://img.shields.io/badge/GitHub-chatstorage3-black?logo=github">
  </a>

  <a href="https://mrmrprogrammer.ir/">
    <img src="https://img.shields.io/badge/Website-mrmrprogrammer.ir-blue">
  </a>
</p>

- PyPI: https://pypi.org/project/chatstorage3
- GitHub: https://github.com/MrMrProgrammer/chatstorage3
- Website: https://mrmrprogrammer.ir
