ChatStorage3

A boto3-inspired object storage library powered by chat platforms.

Store and retrieve files using platforms like Bale and Telegram with a simple object storage API.

---

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.

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:

Bucket + Key
      |
      v
   File ID
      |
      v
 Stored File

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

---

Installation

pip install chatstorage3

---

Quick Start

import chatstorage3


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

---

Upload File

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

---

Download File

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

---

Upload Object

Upload raw bytes directly:

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

---

Get Object

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

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

print(content)

Output:

b'Hello ChatStorage3!'

---

File Objects

ChatStorage3 supports file-like objects:

from io import BytesIO


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


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

Download:

output = BytesIO()


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


output.seek(0)

print(output.read())

---

Object Metadata

Retrieve object metadata:

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

Example:

{
    "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

chatstorage3

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

---

Testing

Run tests:

pytest -v

Current tests cover:

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

---

Roadmap

• Bale provider
• Telegram provider
• SQLite object index
• boto3-inspired API
• File upload/download
• 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

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