A modern, asynchronous Python library for interacting with Soroush Plus — both as a user account and a bot account.
کتابخانه پایتون مدرن و ناهمگام برای تعامل با سروش پلاس — هم کاربر و هم ربات
Packed with features for powerful Soroush Plus bots.
همه چیزی که برای رباتهای قدرتمند سروش پلاس نیاز دارید
Built with asyncio. Non-blocking I/O for high-performance concurrent operations.
Uses built-in Soroush Plus credentials. Install and start building immediately.
Handle messages, edits, callbacks, inline queries, and more with decorators.
Chain filters with & (AND), | (OR), ~ (NOT) for complex conditions.
Interactive keyboards with URL buttons, callback data, and more.
Multi-step bot dialogs with context managers for interactive flows.
Built-in FSM with multiple storage backends and decorator routing.
Dynamic plugin loading. Modular architecture that scales.
Pre/post processing of updates. Add logging and rate limiting.
Schedule messages and callbacks with interval or one-shot timing.
Memory, SQLite, Redis, PostgreSQL — choose what fits.
Token bucket algorithm with automatic flood wait handling.
Smart auto-responder with per-chat rate limiting.
Ban, mute, pin, purge — high-level admin API.
Real-time message cloning between chats.
Upload/download with progress tracking and chunked transfers.
Use without async/await via spluspy.sync.
Send, delete, forward multiple messages at once.
Every class, method, and parameter documented.
مستندات کامل تمام کلاسها، متدها و پارامترها — به دو زبان
Main entry point for all SplusPy operations. Manages authentication, events, middleware, and API calls. Supports bot mode (bot_token) and user mode (phone).
نقطه ورود اصلی تمام عملیات SplusPy — مدیریت احراز هویت، رویدادها، میانافزار و فراخوانیهای API
bot_token for bots or phone for user accounts.bot_token برای رباتها و phone برای حساب کاربری استفاده کنید.| Param | Type | Description |
|---|---|---|
| session | str | Session | Session name for persisting auth data / نام نشست |
| bot_token | str | None | Bot token for bot mode / توکن ربات |
| phone | str | None | Phone for user mode auth / شماره تلفن |
| api_id | int | None | Custom API ID (uses built-in if None) / شناسه API سفارشی |
| api_hash | str | None | Custom API hash / هش API سفارشی |
| flood_sleep_threshold | int | Auto-sleep on FloodWait (default: 60) / آستانه انتظار سیلاب |
| request_timeout | float | API request timeout in seconds / تایماوت درخواست |
| Param | Type | Description |
|---|---|---|
| chat_id | int | Target chat/user ID / شناسه چت مقصد |
| text | str | None | Message text / متن پیام |
| reply_to | int | None | Message ID to reply to / پاسخ به پیام |
| parse_mode | str | None | "html", "markdown", or None / حالت پارس |
Interactive conversational flow for request/response style messaging. Used with async with client.conversation(peer) as conv:.
جریان مکالمه تعاملی برای پیامرسانی سبک درخواست/پاسخ
Represents a received or sent message with all its properties and methods.
نمایانگر پیام دریافت شده یا ارسال شده با تمام ویژگیها و متدها
| Field | Type | Description |
|---|---|---|
| id | int | Unique message identifier / شناسه یکتای پیام |
| text | str | Message text or caption / متن پیام یا کپشن |
| date | datetime | None | Timestamp / زمان پیام |
| chat_id | int | Chat ID / شناسه چت |
| sender_id | int | None | Sender user ID / شناسه فرستنده |
| sender | User | None | Resolved User object / شیء کاربر |
| media | Media | None | Attached media / رسانه پیوست |
| media_type | MessageMediaType | Kind of media / نوع رسانه |
| reply_to | int | None | Replied-to message ID / شناسه پیام پاسخ داده شده |
| is_group | bool | From a group / از گروه |
| is_channel | bool | From a channel / از کانال |
| is_private | bool | From a private chat / از چت خصوصی |
| Field | Type | Description |
|---|---|---|
| id | int | Unique user identifier / شناسه یکتای کاربر |
| first_name | str | First name / نام |
| last_name | str | Last name / نام خانوادگی |
| username | str | None | Username without @ / نام کاربری |
| phone | str | None | Phone number / شماره تلفن |
| bio | str | None | Biography / بیوگرافی |
| is_bot | bool | Whether this is a bot / آیا ربات است |
| is_premium | bool | Premium subscription / اشتراک پریمیوم |
| status | UserStatus | Online status / وضعیت آنلاین |
| Field | Type | Description |
|---|---|---|
| id | int | Unique chat identifier / شناسه چت |
| title | str | Chat title / عنوان چت |
| type | ChatType | PRIVATE, GROUP, SUPERGROUP, CHANNEL / نوع چت |
| username | str | None | Public username / نام کاربری عمومی |
| description | str | None | Description / توضیحات |
| member_count | int | Number of members / تعداد اعضا |
Static factory methods for creating keyboard buttons.
Composable predicates with & (AND), | (OR), ~ (NOT).
| Filter | Matches | توضیحات |
|---|---|---|
| filters.private | Private chats | چتهای خصوصی |
| filters.group | Groups / supergroups | گروهها |
| filters.channel | Channels | کانالها |
| filters.text | Text messages | پیامهای متنی |
| filters.photo | Photos | عکسها |
| filters.video | Videos | ویدیوها |
| filters.audio | Audio | صوت |
| filters.voice | Voice notes | یادداشت صوتی |
| filters.document | Documents | اسناد |
| filters.sticker | Stickers | استیکرها |
| filters.animation | GIFs | گیفها |
| filters.contact | Contacts | مخاطبین |
| filters.location | Locations | موقعیتها |
| filters.poll | Polls | نظرسنجیها |
| filters.dice | Dice | تاس |
| filters.media | Any media | هر رسانهای |
| filters.reply | Replies | پاسخها |
| filters.forwarded | Forwarded | فوروارد شده |
| filters.me | Sent by you | ارسال شده توسط شما |
| filters.bot | Sent by bots | ارسال شده توسط رباتها |
| filters.outgoing | Outgoing | ارسالی |
| filters.incoming | Incoming | دریافتی |
| filters.service | Service messages | پیامهای سیستمی |
| Backend | Class | Description |
|---|---|---|
| Memory | MemoryStorage() | In-memory, non-persistent / حافظه، غیردائمی |
| SQLite | SQLiteStorage(path) | Persistent file-based / مبتنی بر فایل |
| Redis | RedisStorage(url) | Shared state (requires redis) / حالت مشترک |
| PostgreSQL | PostgresStorage(dsn) | Enterprise (requires asyncpg) / سازمانی |
Smart auto-responder for AFK mode with per-chat rate limiting.
پاسخگوی خودکار هوشمند حالت AFK با محدودیت نرخ به ازای هر چت
High-level chat administration API with batch operations.
Real-time message cloning between chats.
| Exception | Constructor | Description / توضیحات |
|---|---|---|
| SplusPyError | (message) | Base for all errors / پایه تمام خطاها |
| RPCError | (message, code=0) | API errors / خطاهای API |
| FloodWait | (seconds, message="") | Flood wait. Has .seconds / انتظار سیلاب |
| Unauthorized | (message) | Auth required / نیاز به احراز هویت |
| Forbidden | (message) | Permission denied / دسترسی غیرمجاز |
| BadRequest | (message) | Bad request / درخواست نادرست |
| ChatNotFound | (message) | Chat not found / چت یافت نشد |
| UserNotFound | (message) | User not found / کاربر یافت نشد |
| MessageNotFound | (message) | Message not found / پیام یافت نشد |
| SessionExpiredError | (message) | Session expired / نشست منقضی شده |
| AuthError | (message) | Auth failure / خطای احراز هویت |
| JoinChatError | (message, link="") | Join failure / خطای پیوستن |
| InvalidInviteLinkError | (link, reason) | Invalid link / لینک نامعتبر |
| InviteLinkExpiredError | (link, reason) | Expired link / لینک منقضی |
| ChatFullError | (chat_id, limit) | Chat is full / چت پر است |
| ChatDeactivatedError | (chat_id) | Chat deactivated / چت غیرفعال |
| MembershipRequiredError | (chat_id, reason) | Membership needed / نیاز به عضویت |
Get a working Soroush Plus bot in just a few lines.
در چند خط کد، یک ربات سروش پلاس بسازید
from spluspy import Client, filters bot = Client("my_session") @bot.on_message(filters.command("start")) async def start_handler(client, message): await message.reply("Hello!") @bot.on_message(filters.private & filters.text) async def echo(client, message): await message.reply(f"You said: {message.text}") bot.run()
from spluspy import Client, filters from spluspy.fsm import State, StateMachine from spluspy.storage import SQLiteStorage bot = Client("bot") sm = StateMachine(SQLiteStorage("fsm.db")) class Form: name = State() age = State() @sm.state(Form.name) async def handle_name(ctx, msg): await ctx.set(name=msg.text) return StateTransition(to=Form.age) @sm.state(Form.age) async def handle_age(ctx, msg): data = await ctx.get() await msg.reply(f"Done: {data}") await ctx.finish()
Install with the features you need.
SplusPy را با قابلیتهای مورد نیاز نصب کنید
pip install spluspyCore library / کتابخانه اصلی
pip install spluspy[speed]Performance optimized / بهینه عملکرد
pip install spluspy[redis]Shared state storage / ذخیرهسازی مشترک
pip install spluspy[postgres]Enterprise storage / ذخیرهسازی سازمانی
pip install spluspy[all]Everything included / همه چیز
from spluspy.sync import ClientNo async needed / بدون async