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:

pip install baleclient

Upgrade to the latest version:

pip install -U baleclient

Install from source:

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

Requirements

• Python 3.11+

Quick Example

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:

• Fixed dialog response parsing
• Fixed message caption parsing
• Fixed history response validation errors
• Fixed incorrect type validations in response models
• Fixed document MIME type parsing when the API returns a dictionary instead of a string
• Fixed thumbnail parsing when the API returns 6-1 instead of 6
• Fixed thumbnail image parsing when the API returns a structured object instead of raw bytes or str
• 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:

• Improved error handling for corrupted or modified session files
• Improved robustness when parsing Bale API responses with inconsistent structures
• Added safer handling for missing or optional message fields
• Added normalization for inconsistent thumbnail payload structures
• 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.