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. Inherits from: AccountMethods, AuthMethods, DownloadMethods, DialogMethods, ChatMethods, MessageMethods, UploadMethods, ButtonMethods, UpdateMethods, MessageParseMethods, UserMethods, ExtraMethods
نقطه ورود اصلی. از تمام متدهای بالا ارثبری میکند.
SQLiteSession, MemorySession, or custom Session.| Param | Type | Description |
|---|---|---|
| session | str | Session | Session name or instance / نام یا نمونه نشست |
| api_id | int | API ID (built-in default) |
| api_hash | str | API hash (built-in default) |
| connection | Connection | Transport (default: WebSocket) |
| flood_sleep_threshold | int | Auto-sleep on FloodWait (default: 60) |
| request_retries | int | Number of retries (default: 5) |
| auto_reconnect | bool | Auto-reconnect on disconnect (default: True) |
| sequential_updates | bool | Process updates sequentially (default: False) |
| receive_updates | bool | Receive updates from server (default: True) |
Represents a message. Inherits from ChatGetter, SenderGetter, TLObject.
نمایانگر پیام. از ChatGetter و SenderGetter ارثبری میکند.
| Property | Type | Description |
|---|---|---|
| id | int | Message ID |
| text | str | Formatted text (Markdown/HTML) |
| raw_text | str | Raw text without formatting |
| date | datetime | Timestamp |
| chat_id | int | Chat ID |
| sender_id | int | Sender ID |
| sender | User | None | Resolved sender |
| chat | Chat | Channel | User | Resolved chat |
| is_private | bool | Private chat? |
| is_group | bool | Group or megagroup? |
| is_channel | bool | Channel? |
| is_reply | bool | Is a reply? |
| forward | Forward | Forward info |
| media | MessageMedia | Media object |
| media_type | MessageMediaType | PHOTO, VIDEO, DOCUMENT, etc. |
| photo | Photo | Photo media |
| document | Document | Document media |
| audio | Document | Audio file |
| voice | Document | Voice note |
| video | Document | Video file |
| gif | Document | GIF animation |
| sticker | Document | Sticker |
| file | File | Helper for file attributes |
| views | int | View count |
| forwards | int | Forward count |
| replies | MessageReplies | Reply info |
| reactions | MessageReactions | Reaction info |
| edit_date | datetime | Last edit time |
| grouped_id | int | Album group ID |
| out | bool | Outgoing? |
| pinned | bool | Pinned? |
| ttl_period | int | Self-destruct TTL |
Composable with & (AND), | (OR), ~ (NOT).
قابل ترکیب با عملگرهای & و | و ~
| Filter | Matches | توضیحات |
|---|---|---|
| filters.private | Private chats | چتهای خصوصی |
| filters.group | Groups / supergroups | گروهها |
| filters.channel | Channels | کانالها |
| filters.me | Sent by you | ارسال شده توسط شما |
| filters.text | Text messages | پیامهای متنی |
| filters.link | Contains URL | حاوی لینک |
| filters.media | Any media | هر رسانهای |
| filters.photo | Photos | عکسها |
| filters.video | Videos | ویدیوها |
| filters.document | Documents | اسناد |
| filters.audio | Audio files | فایل صوتی |
| filters.voice | Voice notes | یادداشت صوتی |
| filters.sticker | Stickers | استیکرها |
| filters.animation | GIF animations | گیفها |
| filters.new_chat_members | New members joined | عضو جدید |
| filters.left_chat_member | Member left | عضو خارج شد |
event.pattern_match.NewMessage events.MessageEdited events.MessageDeleted events.ChatAction events (join/leave/pin/...).UserUpdate (online/offline/typing).on_message(filters.group & filters).on_message(filters.channel & filters).on_message(filters.me & filters).event.messages contains the list.types to filter by TL type.types میتوان فیلتر کرد.
Used with async with client.conversation(peer) as conv:
استفاده با async with
| 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) |
| Exception | Description / توضیحات |
|---|---|
| SplusPyError | Base for all errors |
| RPCError | API errors (code + message) |
| FloodWaitError | Flood wait. Has .seconds |
| FloodPremiumWaitError | Premium flood wait |
| SlowModeWaitError | Slow mode wait |
| UnauthorizedError | Auth required |
| ForbiddenError | Permission denied |
| BadRequestError | Bad request |
| ServerError | Internal server error |
| TimedOutError | Timeout |
| InvalidDCError | Wrong data center |
| AuthKeyDuplicatedError | Session used from two IPs |
| SessionExpiredError | Session expired |
| PhoneNumberInvalidError | Invalid phone |
| PhoneCodeInvalidError | Invalid code |
| PasswordHashInvalidError | Invalid password |
| MessageIdInvalidError | Invalid message ID |
| MessageNotModifiedError | Message content not changed |
| ChannelPrivateError | Channel is private |
| UserNotParticipantError | User not in chat |
| BotMethodInvalidError | Method not for bots |
| FloodWaitError | Alias for FloodWait |
| TakeoutInitDelayError | Takeout requires wait |
| FileReferenceExpiredError | File reference expired |
| LocationInvalidError | Invalid file location |
| MediaInvalidError | Invalid media |
| PhotoInvalidDimensionsError | Photo dimensions invalid |
| StickerEmojiInvalidError | Invalid sticker emoji |
Get a working Soroush Plus bot in just a few lines.
در چند خط کد، یک ربات سروش پلاس بسازید
from spluspy import SoroushClient, filters bot = SoroushClient("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_until_disconnected()
async with bot.conversation(chat_id) as conv: await conv.send_message("What's your name?") response = await conv.get_response() await conv.send_message(f"Nice to meet you, {response.text}!")
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 SoroushClientNo async needed / بدون async
pip install git+https://github.com/Itskillmaster/spluspy.gitLatest commits / آخرین تغییرات
We welcome contributions! Read our guidelines.
کمک به توسعهی پروژه — خوشآمدید!
pip install -e .[dev]pytestRecent updates and improvements.
تغییرات اخیر و بهبودها
on_message and all event decoratorsClient.leave_all(), Client.get_all_groups(), Client.delete_all_private()get_chat misuse by adding get_entity-based resolution helpersMessage.media_type propertyMessage.reply_photo, reply_video, reply_document, reply_voice, reply_sticker, reply_location, reply_poll, reply_diceMessage.forward property