aiobale-py 0.2.0__tar.gz

aiobale_py-0.2.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Alireza Jahani | Enalite LD
+Copyright (c) 2026 Mohammadamin Madani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiobale_py-0.2.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: aiobale-py
+Version: 0.2.0
+Summary: Modern, fast, fully asynchronous Python framework for Bale Messenger.
+Author-email: Amin Madani <aminmadani112@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Alireza Jahani | Enalite LD
+        Copyright (c) 2026 Mohammadamin Madani
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/aminmadaniofficial/aiobale
+Project-URL: Repository, https://github.com/aminmadaniofficial/aiobale
+Project-URL: Documentation, https://aminmadaniofficial.github.io/aiobale/
+Project-URL: PyPI, https://pypi.org/project/aiobale-py/
+Requires-Python: >=3.8
+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
+
+# Aiobale
+
+<div align="center">
+
+[![CI Test Suite](https://github.com/aminmadaniofficial/aiobale/actions/workflows/ci.yml/badge.svg)](https://github.com/aminmadaniofficial/aiobale/actions/workflows/ci.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/aiobale-py.svg?color=blue)](https://pypi.org/project/aiobale-py/)
+[![Documentation](https://img.shields.io/badge/Docs-GitHub%20Pages-2563eb?style=flat&logo=github)](https://aminmadaniofficial.github.io/aiobale/)
+[![Python](https://img.shields.io/badge/Python-3.8%20--%203.14-3776AB?style=flat&logo=python)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/aminmadaniofficial/aiobale/blob/main/LICENSE)
+
+**Modern, fast, fully asynchronous Python framework for Bale Messenger.**
+
+[📖 Interactive Documentation](https://aminmadaniofficial.github.io/aiobale/) • [📦 PyPI Package](https://pypi.org/project/aiobale-py/) • [🚀 Quickstart](#-quickstart) • [✨ Features](#-key-features)
+
+</div>
+
+---
+
+## 🌟 Overview
+
+**Aiobale** is a high-performance, asynchronous Python library 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, automation tools, and group management services 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.
+- **🧠 Finite State Machine (FSM):** Multi-step conversational form management with `State`, `StatesGroup`, and `FSMContext`.
+- **🛡️ Middlewares Pipeline:** Intercept and process events before/after handlers with `BaseMiddleware`.
+- **⌨️ Fluent Keyboard Builders:** Chainable creation of Inline and Reply keyboards with dynamic grid formatting.
+- **🔮 Magic Filter (`F`):** Powerful expression-based event filtering (e.g. `F.text.startswith("/start")`, `F.chat.type == ChatType.GROUP`).
+- **🔀 Modular Routing:** Organize complex bots across multiple files using `Router` and sub-routers.
+- **🛡️ Full RPC Coverage (79+ Methods):** Complete access to Messaging, Groups, Channels, Contacts, Presence, Reactions, and File APIs.
+- **📁 Fast Media Upload & Download:** Automated chunked file streaming with binary support.
+- **🔐 Flexible Authentication:** Interactive CLI phone login, persistent session files (`.bale`), direct JWT token support, and headless Docker readiness.
+- **🧩 100% Type Annotated:** Powered by Pydantic v2 for data validation and complete IDE autocompletion.
+- **🧪 Battle-Tested:** Automated CI pipeline verifying compatibility from Python 3.8 to 3.14.
+
+---
+
+## 📦 Installation
+
+```bash
+# Install officially from PyPI
+pip install aiobale-py
+
+# Or install the latest development version directly from GitHub
+pip install git+https://github.com/aminmadaniofficial/aiobale.git
+```
+
+> **Note:** The package is installed as `aiobale-py`, while you import it in your Python code directly as `import aiobale` or `from aiobale import Client, Dispatcher, F`.
+
+---
+
+## 🚀 Quickstart
+
+Create your first bot in less than 5 minutes:
+
+```python
+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 store the session in `my_bot.bale` for automatic reconnects.
+
+---
+
+## 🎯 Code Examples
+
+### 1. Finite State Machine (FSM) Form
+
+```python
+from aiobale import Client, Dispatcher, F
+from aiobale.fsm import State, StatesGroup, FSMContext
+from aiobale.types import Message
+
+class Registration(StatesGroup):
+    name = State()
+    age = State()
+
+dp = Dispatcher()
+client = Client(dp, session_file="fsm_bot")
+
+@dp.message(F.text == "/register")
+async def start_register(msg: Message, state: FSMContext):
+    await state.set_state(Registration.name)
+    await msg.reply("Please enter your name:")
+
+@dp.message(Registration.name)
+async def process_name(msg: Message, state: FSMContext):
+    await state.update_data(name=msg.text)
+    await state.set_state(Registration.age)
+    await msg.reply("Great! Now enter your age:")
+
+@dp.message(Registration.age)
+async def process_age(msg: Message, state: FSMContext):
+    data = await state.get_data()
+    name = data.get("name")
+    age = msg.text
+    await state.clear()
+    await msg.reply(f"Registration complete! Name: {name}, Age: {age}")
+
+if __name__ == "__main__":
+    client.run()
+```
+
+### 2. Group Moderation & Anti-Link Bot
+
+```python
+import re
+from aiobale import Client, Dispatcher, F
+from aiobale.types import Message
+from aiobale.enums import ChatType
+
+dp = Dispatcher()
+client = Client(dp, session_file="mod_bot")
+
+LINK_REGEX = re.compile(r"(https?://|ble\.ir/|t\.me/|eitaa\.com/)")
+
+@dp.message(F.chat.type == ChatType.GROUP)
+async def delete_links(msg: Message):
+    if msg.text and LINK_REGEX.search(msg.text):
+        await msg.delete()
+
+@dp.message(F.text == "/ban", F.chat.type == ChatType.GROUP)
+async def ban_user(msg: Message, client: Client):
+    if msg.replied_to:
+        await client.kick_user(msg.chat.id, msg.replied_to.sender_id)
+        await msg.answer("User kicked from group.")
+
+if __name__ == "__main__":
+    client.run()
+```
+
+---
+
+## 📚 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 79+ methods:
+
+👉 **[Read the Full Documentation](https://aminmadaniofficial.github.io/aiobale/)**
+
+---
+
+## 🏛️ Project Origin & Acknowledgements
+
+This project is built upon the foundational work of the original `aiobale` library created by **Alireza Jahani** ([Enalite LD](https://github.com/Enalite)). 
+
+It has been modernized, heavily refactored, debugged, and is now actively maintained with automated CI/CD and comprehensive docs by **[Amin Madani](https://github.com/aminmadaniofficial)**.
+
+---
+
+## 📄 License
+
+Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more details.

aiobale_py-0.2.0/README.md

@@ -0,0 +1,175 @@
+# Aiobale
+
+<div align="center">
+
+[![CI Test Suite](https://github.com/aminmadaniofficial/aiobale/actions/workflows/ci.yml/badge.svg)](https://github.com/aminmadaniofficial/aiobale/actions/workflows/ci.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/aiobale-py.svg?color=blue)](https://pypi.org/project/aiobale-py/)
+[![Documentation](https://img.shields.io/badge/Docs-GitHub%20Pages-2563eb?style=flat&logo=github)](https://aminmadaniofficial.github.io/aiobale/)
+[![Python](https://img.shields.io/badge/Python-3.8%20--%203.14-3776AB?style=flat&logo=python)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/aminmadaniofficial/aiobale/blob/main/LICENSE)
+
+**Modern, fast, fully asynchronous Python framework for Bale Messenger.**
+
+[📖 Interactive Documentation](https://aminmadaniofficial.github.io/aiobale/) • [📦 PyPI Package](https://pypi.org/project/aiobale-py/) • [🚀 Quickstart](#-quickstart) • [✨ Features](#-key-features)
+
+</div>
+
+---
+
+## 🌟 Overview
+
+**Aiobale** is a high-performance, asynchronous Python library 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, automation tools, and group management services 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.
+- **🧠 Finite State Machine (FSM):** Multi-step conversational form management with `State`, `StatesGroup`, and `FSMContext`.
+- **🛡️ Middlewares Pipeline:** Intercept and process events before/after handlers with `BaseMiddleware`.
+- **⌨️ Fluent Keyboard Builders:** Chainable creation of Inline and Reply keyboards with dynamic grid formatting.
+- **🔮 Magic Filter (`F`):** Powerful expression-based event filtering (e.g. `F.text.startswith("/start")`, `F.chat.type == ChatType.GROUP`).
+- **🔀 Modular Routing:** Organize complex bots across multiple files using `Router` and sub-routers.
+- **🛡️ Full RPC Coverage (79+ Methods):** Complete access to Messaging, Groups, Channels, Contacts, Presence, Reactions, and File APIs.
+- **📁 Fast Media Upload & Download:** Automated chunked file streaming with binary support.
+- **🔐 Flexible Authentication:** Interactive CLI phone login, persistent session files (`.bale`), direct JWT token support, and headless Docker readiness.
+- **🧩 100% Type Annotated:** Powered by Pydantic v2 for data validation and complete IDE autocompletion.
+- **🧪 Battle-Tested:** Automated CI pipeline verifying compatibility from Python 3.8 to 3.14.
+
+---
+
+## 📦 Installation
+
+```bash
+# Install officially from PyPI
+pip install aiobale-py
+
+# Or install the latest development version directly from GitHub
+pip install git+https://github.com/aminmadaniofficial/aiobale.git
+```
+
+> **Note:** The package is installed as `aiobale-py`, while you import it in your Python code directly as `import aiobale` or `from aiobale import Client, Dispatcher, F`.
+
+---
+
+## 🚀 Quickstart
+
+Create your first bot in less than 5 minutes:
+
+```python
+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 store the session in `my_bot.bale` for automatic reconnects.
+
+---
+
+## 🎯 Code Examples
+
+### 1. Finite State Machine (FSM) Form
+
+```python
+from aiobale import Client, Dispatcher, F
+from aiobale.fsm import State, StatesGroup, FSMContext
+from aiobale.types import Message
+
+class Registration(StatesGroup):
+    name = State()
+    age = State()
+
+dp = Dispatcher()
+client = Client(dp, session_file="fsm_bot")
+
+@dp.message(F.text == "/register")
+async def start_register(msg: Message, state: FSMContext):
+    await state.set_state(Registration.name)
+    await msg.reply("Please enter your name:")
+
+@dp.message(Registration.name)
+async def process_name(msg: Message, state: FSMContext):
+    await state.update_data(name=msg.text)
+    await state.set_state(Registration.age)
+    await msg.reply("Great! Now enter your age:")
+
+@dp.message(Registration.age)
+async def process_age(msg: Message, state: FSMContext):
+    data = await state.get_data()
+    name = data.get("name")
+    age = msg.text
+    await state.clear()
+    await msg.reply(f"Registration complete! Name: {name}, Age: {age}")
+
+if __name__ == "__main__":
+    client.run()
+```
+
+### 2. Group Moderation & Anti-Link Bot
+
+```python
+import re
+from aiobale import Client, Dispatcher, F
+from aiobale.types import Message
+from aiobale.enums import ChatType
+
+dp = Dispatcher()
+client = Client(dp, session_file="mod_bot")
+
+LINK_REGEX = re.compile(r"(https?://|ble\.ir/|t\.me/|eitaa\.com/)")
+
+@dp.message(F.chat.type == ChatType.GROUP)
+async def delete_links(msg: Message):
+    if msg.text and LINK_REGEX.search(msg.text):
+        await msg.delete()
+
+@dp.message(F.text == "/ban", F.chat.type == ChatType.GROUP)
+async def ban_user(msg: Message, client: Client):
+    if msg.replied_to:
+        await client.kick_user(msg.chat.id, msg.replied_to.sender_id)
+        await msg.answer("User kicked from group.")
+
+if __name__ == "__main__":
+    client.run()
+```
+
+---
+
+## 📚 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 79+ methods:
+
+👉 **[Read the Full Documentation](https://aminmadaniofficial.github.io/aiobale/)**
+
+---
+
+## 🏛️ Project Origin & Acknowledgements
+
+This project is built upon the foundational work of the original `aiobale` library created by **Alireza Jahani** ([Enalite LD](https://github.com/Enalite)). 
+
+It has been modernized, heavily refactored, debugged, and is now actively maintained with automated CI/CD and comprehensive docs by **[Amin Madani](https://github.com/aminmadaniofficial)**.
+
+---
+
+## 📄 License
+
+Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more details.

aiobale_py-0.2.0/aiobale/__init__.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+import warnings
+
+warnings.filterwarnings(
+    "ignore",
+    message="pkg_resources is deprecated as an API.*",
+    category=UserWarning,
+    module="google.protobuf.*"
+)
+
+__version__ = "0.2.0"
+
+from .client.client import Client
+from .dispatcher.dispatcher import Dispatcher
+from .dispatcher.router import Router
+from .utils.magic_filter import MagicFilter
+from .fsm import (
+    State,
+    StatesGroup,
+    default_state,
+    any_state,
+    FSMContext,
+    StateFilter,
+    BaseStorage,
+    MemoryStorage,
+)
+from .middlewares import BaseMiddleware
+from .utils.keyboard import (
+    InlineKeyboardBuilder,
+    ReplyKeyboardBuilder,
+    InlineKeyboardButton,
+    ReplyKeyboardButton,
+)
+
+F = MagicFilter()
+
+__all__ = (
+    "__version__",
+    "Client",
+    "Dispatcher",
+    "Router",
+    "F",
+    "State",
+    "StatesGroup",
+    "default_state",
+    "any_state",
+    "FSMContext",
+    "StateFilter",
+    "BaseStorage",
+    "MemoryStorage",
+    "BaseMiddleware",
+    "InlineKeyboardBuilder",
+    "ReplyKeyboardBuilder",
+    "InlineKeyboardButton",
+    "ReplyKeyboardButton",
+)