aiobale-py

Aiobale

---

🌟 Overview

Aiobale (aiobale-py) is a high-performance, asynchronous Python framework built on top of asyncio, WebSockets, and Protocol Buffers for the Bale Messenger platform. Designed with inspiration from modern bot frameworks like aiogram, it allows developers to build userbots, official bots, automated services, and group management systems with minimal resource usage and complete type safety.

---

✨ Key Features

• ⚡ Fully Asynchronous: Built natively on Python asyncio for non-blocking I/O and high concurrency.
• 💬 Interactive Conversations (Conversation): Multi-step question & answer wizard flows with async context managers (async with client.conversation(...) as conv:).
• 📜 History Iterator (iter_messages): Asynchronously iterate and paginate through chat message histories with automated deduplication and chunking.
• 🧠 Advanced FSM: Multi-step conversational form management with State, StatesGroup, MemoryStorage, and persistent SQLiteStorage.
• 🛡️ Middlewares & Rate Limiter: Intercept events and prevent spam using BaseMiddleware and the built-in MessageThrottler.
• ⌨️ Fluent Keyboards & Pagination: Chainable InlineKeyboardMarkup, ReplyKeyboardMarkup, and KeyboardPaginator for multi-page menus.
• 🔮 Rich Magic Filter (F) & Text Filters: Filter events effortlessly with F, Command, IsMedia, TextEquals, TextContains, and logical combinators (and_f, or_f, invert_f).
• 🔀 Modular Routing: Structure large-scale codebases across multiple files using Router and sub-routers.
• 🌐 Webhook HTTP Server: Built-in lightweight AiohttpWebhookServer with secret token security for serverless and production deployments.
• 📁 Smart Media & Downloads: Direct file path (str), Path, raw bytes, and io.BytesIO support in all sending methods, plus 1-line await message.download().
• 🛠️ Command-Line CLI: Scaffolding tool (aiobale startproject my_bot) and interactive phone session login (aiobale login).
• 🛡️ Complete RPC Coverage (80+ Methods): Full access to Messaging, Groups, Channels, Contacts, Presence, Reactions, and Wallet APIs.
• 🧩 100% Type-Safe: Powered by Pydantic v2 for robust data validation and complete IDE autocompletion.

---

📦 Installation

# Install officially from PyPI
pip install aiobale-py

# Or install using the ultra-fast uv package manager
uv pip install aiobale-py

# Or install the latest development build directly from GitHub
pip install git+https://github.com/aminmadaniofficial/aiobale.git

Important: The package name on PyPI is aiobale-py, while in your Python code you import it directly as aiobale:

from aiobale import Client, Dispatcher, F, Conversation

---

🚀 Quickstart

Create a functional bot in less than 5 minutes:

import asyncio
from aiobale import Client, Dispatcher, F
from aiobale.types import Message
from aiobale.filters import IsText

dp = Dispatcher()
client = Client(dp, session_file="my_bot")

@dp.message(F.text == "/start")
async def start_handler(message: Message):
    await message.reply("Hello! Welcome to Aiobale 🚀")

@dp.message(IsText())
async def echo_handler(message: Message):
    await message.reply(f"You said: {message.text}")

async def main():
    print("Connecting to Bale Messenger...")
    await client.start()

if __name__ == "__main__":
    asyncio.run(main())

When you run this script for the first time in your terminal, it will interactively prompt for your phone number and SMS verification code, then persist the session in my_bot.bale for automatic reconnects.

---

🎯 Code Showcases

1. Interactive Linear Conversation (Wizard)

from aiobale import Client, Dispatcher, F
from aiobale.types import Message

dp = Dispatcher()
client = Client(dp, session_file="wizard_bot")

@dp.message(F.text == "/register")
async def register_flow(msg: Message, client: Client):
    async with client.conversation(msg.chat.id) as conv:
        await conv.send_message("Please enter your full name:")
        name_msg = await conv.get_response(timeout=60)

        await conv.send_message(f"Nice to meet you, {name_msg.text}! How old are you?")
        age_msg = await conv.get_response(timeout=60)

        await conv.send_message(f"Registration successful! ✅\nName: {name_msg.text}\nAge: {age_msg.text}")

if __name__ == "__main__":
    client.run()

2. Message History Pagination (iter_messages)

from aiobale import Client

client = Client(session_file="my_account")

async def backup_chat_history(chat_id: int):
    print(f"Reading message history for chat {chat_id}...")
    async for message in client.iter_messages(chat_id=chat_id, limit=50):
        if message.text:
            print(f"[{message.date}] {message.sender_id}: {message.text}")
        elif message.document:
            print(f"[{message.date}] Media attachment: {message.document.name}")

if __name__ == "__main__":
    import asyncio
    asyncio.run(backup_chat_history(123456789))

3. Persistent FSM with SQLite Storage

from aiobale import Client, Dispatcher, F
from aiobale.fsm import State, StatesGroup, FSMContext, SQLiteStorage
from aiobale.types import Message

class OrderForm(StatesGroup):
    item = State()
    address = State()

storage = SQLiteStorage("bot_orders.db")
dp = Dispatcher(storage=storage)
client = Client(dp, session_file="shop_bot")

@dp.message(F.text == "/order")
async def start_order(msg: Message, state: FSMContext):
    await state.set_state(OrderForm.item)
    await msg.reply("What item would you like to purchase?")

@dp.message(OrderForm.item)
async def process_item(msg: Message, state: FSMContext):
    await state.update_data(item_name=msg.text)
    await state.set_state(OrderForm.address)
    await msg.reply("Please provide your delivery address:")

@dp.message(OrderForm.address)
async def process_address(msg: Message, state: FSMContext):
    data = await state.get_data()
    await state.clear()
    await msg.reply(f"Order confirmed! Item: {data.get('item_name')}, Address: {msg.text}")

if __name__ == "__main__":
    client.run()

---

📁 Ready-to-Run Examples

The examples/ directory contains 6 complete, production-grade scripts demonstrating every core capability:

---

📚 Comprehensive Documentation

The repository includes a modern, web-based interactive documentation website with zero emojis, custom Lucide icons, Dark/Light modes, live search (Ctrl+K), and reference guides for all 80+ methods:

👉 Read the Full Documentation

---

👥 Acknowledgements & Special Thanks

• Maintainer & Lead Developer: Modernized, heavily refactored, debugged, and actively maintained by Amin Madani.
• Core Foundation: Built upon the foundational work of the original aiobale library created by Alireza Jahani (Enalite LD).
• Special Thanks (Testing & QA): Huge thanks to Mohammad Reza Taghdiri (محمدرضا تقدیری) for active participation in testing, discovering critical edge-case bugs, and contributing to library stability.

---

📄 License

Distributed under the MIT License. See LICENSE for more details.