aiosplus 🚀

aiosplus is a modern, high-performance, asynchronous, type-safe, and modular Python framework for the Soroush Plus Bot API (مستندات پلتفرم بات سروش‌پلاس).

✨ Features | ویژگی‌های کلیدی

• ⚡ Asynchronous First: Built from the ground up on Python's asyncio and httpx for maximum concurrency and throughput.
• 🛡️ Pydantic V2 Powered: Complete, strictly-typed data models with automatic JSON validation and serialization for all API entities.
• 🎯 Aiogram 3 Style Architecture: Modular Dispatcher, Router blueprints, EventObserver, and hierarchical middleware pipelines.
• 🪄 Expressive Magic Filters (F): Clean and readable query filtering like F.text == "hello", F.from_user.id == 123, F.data.startswith("action_").
• 🧠 Finite State Machine (FSM): Built-in state management with StatesGroup, State, FSMContext, and MemoryStorage.
• ⌨️ Fluent Keyboard Builders: Chainable InlineKeyboardBuilder and ReplyKeyboardBuilder for dynamic button layouts.
• 📦 100% Soroush Plus Bot API Coverage: Full support for messages, photos, audio, documents, videos, voice notes, video notes, media albums, contacts, locations, stickers, bot commands, webhooks, and long polling.
• 🔤 Rich Formatting Utilities: Helpers for HTML and MarkdownV2 text formatting and character escaping.

📦 Installation | نصب

Install using pip:

pip install aiosplus

Or install with FastAPI webhook support:

pip install "aiosplus[fastapi]"

🚀 Quickstart | شروع سریع

Create your first bot in fewer than 20 lines of code:

import asyncio
from aiosplus import Bot, Dispatcher
from aiosplus.filters import Command
from aiosplus.types import Message

# Initialize Bot and Dispatcher
bot = Bot(token="YOUR_BOT_TOKEN_HERE")
dp = Dispatcher()


# Handle /start command
@dp.message(Command("start"))
async def start_handler(message: Message) -> None:
    user_name = message.from_user.first_name if message.from_user else "کاربر"
    await message.answer(f"سلام {user_name}! خوش آمدید به ربات سروش‌پلاس.")


# Echo text messages
@dp.message()
async def echo_handler(message: Message) -> None:
    if message.text:
        await message.answer(f"شما گفتید: {message.text}")


async def main() -> None:
    print("Bot is running...")
    await dp.start_polling(bot, drop_pending_updates=True)


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

🧩 Architecture Overview | ساختار معماری

aiosplus/
├── bot/               # Core Bot client handling API requests & file transfers
├── client/            # Async HTTP session & URL construction (HTTPX)
├── dispatcher/        # Dispatcher, Routers, Event Observers, & Pipelines
├── enums.py           # ParseMode, ChatType, MessageEntityType, ChatAction, etc.
├── exceptions.py      # Comprehensive API & network exception hierarchy
├── filters/           # Command, Text, MagicFilter (F), ChatType, State filters
├── fsm/               # Finite State Machine (StatesGroup, FSMContext, MemoryStorage)
├── middlewares/       # Outer & Inner middleware abstract bases
├── types/             # Pydantic v2 data models for all Soroush Plus objects
└── utils/             # Keyboard builders, text formatters, & webhook helpers

📚 Guides & Examples | راهنما و مثال‌ها

Explore ready-to-run examples in the examples/ directory:

1. Echo Bot: Basic message handling and command dispatching.
2. Keyboards Bot: Multi-row inline keyboards, callback query alerts, and reply menus.
3. FSM Survey Bot: Multi-step form data collection using StatesGroup and FSMContext.
4. Media & Files Bot: Uploading photos, sending albums (send_media_group), and downloading user files.
5. FastAPI Webhook: High-throughput production webhook server with FastAPI.

⌨️ Dynamic Keyboards Example

from aiosplus.utils import InlineKeyboardBuilder

builder = InlineKeyboardBuilder()
builder.button(text="وبسایت", url="https://splus.ir")
builder.button(text="تایید", callback_data="confirm")
builder.button(text="انصراف", callback_data="cancel")
builder.adjust(1, 2)  # Row 1: 1 button, Row 2: 2 buttons

await message.answer("گزینه مورد نظر را انتخاب کنید:", reply_markup=builder.as_markup())

🧠 Finite State Machine (FSM) Example

from aiosplus import State, StatesGroup
from aiosplus.fsm.context import FSMContext
from aiosplus.filters import StateFilter


class Form(StatesGroup):
    name = State()
    age = State()


@dp.message(Command("register"))
async def start_register(message: Message, state: FSMContext) -> None:
    await state.set_state(Form.name)
    await message.answer("لطفاً نام خود را وارد کنید:")


@dp.message(StateFilter(Form.name))
async def process_name(message: Message, state: FSMContext) -> None:
    await state.update_data(name=message.text)
    await state.set_state(Form.age)
    await message.answer("سن خود را وارد کنید:")

📡 API Methods Supported | متدهای پشتیبانی‌شده

🧪 Testing & Quality Assurance

Run the test suite with coverage:

pytest

Run type checking and code formatting:

mypy aiosplus tests
ruff check .
ruff format .

📄 License

This project is licensed under the terms of the MIT License.