Metadata-Version: 2.4
Name: BaleClient
Version: 1.0.9
Author-email: "foad.kheirabady" <foad.kheirabady@gmail.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4.0,>=3.9
Requires-Dist: aiofiles<24.0,>=23.1
Requires-Dist: colorama<1.0,>=0.4.6
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: typing_extensions<5.0,>=4.0
Requires-Dist: blackboxprotobuf<2.0,>=1.0.1
Requires-Dist: magic-filter<2.0,>=1.0
Dynamic: license-file

# BaleClient

⚡ **BaleClient** is a maintained fork / rework of **Aiobale**, an asynchronous Python client for **Bale Messenger**.

The original library is great but contains several bugs and incomplete implementations.
This project fixes those issues and adds improvements for reliability, stability, and usability.

---

## Installation

Install from PyPI:

```bash
pip install baleclient
```

Upgrade to the latest version:

```bash
pip install -U baleclient
```

Install from source:

```bash
git clone https://github.com/Foad-KhAb/baleclient.git
cd baleclient
pip install -e .
```

---

## Requirements

* Python **3.11+**

---

## Quick Example

```python
from baleclient import Client

async def main():
    async with Client("session") as client:
        me = await client.get_me()
        print(me)
```

---

## Features

* Fully **asynchronous** API
* Lightweight and fast
* Improved parsing reliability
* Better error handling
* Maintained fork of Aiobale

---

## Based On

This project is based on:

**Aiobale**
https://github.com/Enalite/aiobale

Credit to the original author for the initial implementation.

---

## Why BaleClient?

While using Aiobale in real projects, I encountered several issues such as:

* parsing bugs
* inconsistent API responses
* missing validations
* edge cases not handled

**BaleClient** fixes these problems and introduces improvements to make the library more stable for production usage.

---

## Fixes

The following issues in the original library have been fixed:

* [x] Fixed **dialog response parsing**
* [x] Fixed **message caption parsing**
* [x] Fixed **history response validation errors**
* [x] Fixed **incorrect type validations** in response models
* [x] Fixed **document MIME type parsing** when the API returns a dictionary instead of a string
* [x] Fixed **thumbnail parsing** when the API returns `6-1` instead of `6`
* [x] Fixed **thumbnail image parsing** when the API returns a structured object instead of raw `bytes` or `str`
* [x] Allowed `GroupPeer.access_hash` to be **optional** to support peers returned without an access hash

> This list will continue to grow as more protocol inconsistencies are discovered and resolved.

---

## Improvements

Additional enhancements and quality-of-life improvements:

* [x] Improved **error handling for corrupted or modified session files**
* [x] Improved **robustness when parsing Bale API responses with inconsistent structures**
* [x] Added safer handling for **missing or optional message fields**
* [x] Added normalization for **inconsistent thumbnail payload structures**
* [x] Improved resilience against **schema variations in document and media responses**

---

## Changelog

### v0.1.0

* Initial release
* Fork of Aiobale with several fixes
* Improved session error handling

---

## Documentation

Documentation will be expanded in future releases.

For now, refer to:

* The source code
* Example usage in the repository

---

## Notes

* BaleClient is **not an official Bale API library**
* The Bale API is internal and may change without notice

---

## License

This project follows the same license as the original project unless otherwise specified.
