aiosroosh 1.0.0__tar.gz

aiosroosh-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blaygamesoffcial-hash
+
+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.

aiosroosh-1.0.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: aiosroosh
+Version: 1.0.0
+Summary: کتابخانه‌ی ناهمگام (async) پایتون برای API بات سروش‌پلاس (splus.ir)
+Author: 
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.8
+Dynamic: license-file
+Dynamic: requires-python

aiosroosh-1.0.0/README.md

@@ -0,0 +1,250 @@
+# aiosroosh
+
+کتابخانه‌ی **ناهمگام (async)** پایتون برای API بات سروش‌پلاس (سروش‌پلاس)، که
+از نظر ساختار شبیه به‌کلی Telegram Bot API و در آدرس
+`https://api.splus.ir/bot<token>/METHOD_NAME` در دسترس است.
+
+> این پروژه نسخه‌ی بازنویسی‌شده و async از کتابخانه‌ی sync قبلی
+> (`pyrosroosh`) است؛ ساختار عمومی (`Robot`، `Button`، `filters`،
+> `HandlerPriority`، `ErrorHandlerBuilder`، سلسله‌مراتب خطاها) کاملاً
+> بازطراحی شده تا استفاده از asyncio و ثبت هندلر با فیلترهای قابل‌ترکیب
+> راحت‌تر باشد. ساختار پکیج مشابه کتابخانه‌های `rubka` و `aiobale` است:
+> کلاینت با نام `Robot`، مدل‌های داده (`Message`/`Callback`) در
+> `aiosroosh.types`، و همه‌چیز هم از `aiosroosh.asynco` و هم از ریشه‌ی
+> پکیج (`aiosroosh`) قابل ایمپورت است.
+
+منبع مستندات: مستندات رسمی سروش‌پلاس (`soroushplus.com/p/documents`)؛
+نسخه‌ی کامل استخراج‌شده‌ی متن در `docs/soroush_bot_api.md` این پکیج
+موجود است.
+
+## نصب
+
+```bash
+pip install -e .
+```
+
+وابستگی اصلی: `aiohttp>=3.8`.
+
+## شروع سریع
+
+```python
+from aiosroosh import Robot, filters
+# یا: from aiosroosh.asynco import Robot, filters
+
+bot = Robot(token="YOUR_TOKEN_HERE")
+
+
+@bot.on_message(filters.command("start"))
+async def start(bot, message):
+    await message.reply("سلام! خوش آمدید!")
+
+
+bot.run()
+```
+
+## ساختار ایمپورت‌ها
+
+مشابه `rubka`، کلاس‌های اصلی از ریشه‌ی پکیج در دسترس‌اند:
+
+```python
+from aiosroosh import Robot, Message, Callback, Button, filters
+```
+
+و مشابه `aiobale`، به‌صورت جداگانه هم قابل ایمپورت‌اند — کلاینت از
+`aiosroosh.asynco` و مدل‌های داده از `aiosroosh.types`:
+
+```python
+from aiosroosh.asynco import Robot
+from aiosroosh.types import Message, Callback
+```
+
+`Client` به‌عنوان نام مستعار قدیمی `Robot` (برای سازگاری با کد قبلی) و
+`CallbackQuery` به‌عنوان نام مستعار قدیمی `Callback` هم‌چنان در دسترس‌اند.
+
+## گرفتن توکن
+
+یک بات در `splus.ir/fatherbot` بسازید، دقیقاً مثل BotFather در تلگرام.
+
+## استفاده‌ی پیشرفته‌تر (async/await مستقیم)
+
+به‌جای `bot.run()` می‌توانید خودتان چرخه‌ی رویداد را مدیریت کنید:
+
+```python
+import asyncio
+from aiosroosh import Robot
+
+async def main():
+    async with Robot("YOUR_TOKEN_HERE") as bot:
+        me = await bot.get_me()
+        print(me)
+        await bot.poll()  # حلقه‌ی long-polling
+
+asyncio.run(main())
+```
+
+## فیلترها (`aiosroosh.filters`)
+
+فیلترها قابل ترکیب با `&`، `|` و `~` هستند:
+
+```python
+from aiosroosh import filters
+
+@bot.on_message(filters.text & ~filters.reply)
+async def handler(bot, message):
+    ...
+
+@bot.on_message(filters.command(["start", "help"]))
+async def start(bot, message):
+    ...
+
+@bot.on_message(filters.photo | filters.video)
+async def on_media(bot, message):
+    ...
+```
+
+فیلترهای آماده: `text`, `photo`, `video`, `audio`, `voice`, `document`,
+`sticker`, `animation`, `video_note`, `contact`, `location`, `dice`,
+`reply`, `media` (ترکیب انواع رسانه)، `private`, `group`, `channel`،
+و توابع `command(...)`, `regex(...)`, `chat(...)`, `user(...)`.
+برای فیلتر سفارشی از `filters.create(func)` استفاده کنید.
+
+## اولویت هندلرها (`HandlerPriority`) و مدیریت خطا (`ErrorHandlerBuilder`)
+
+```python
+from aiosroosh import HandlerPriority
+from aiosroosh.errors import FloodWait, ChatNotFound
+
+@bot.on_message(filters.text, priority=HandlerPriority.HIGH)
+async def logger(bot, message):
+    print("پیام جدید:", message.text)
+
+@bot.errors.catch(FloodWait)
+async def on_flood(error, update):
+    import asyncio
+    await asyncio.sleep(error.seconds)
+
+@bot.errors.catch(ChatNotFound)
+def on_chat_not_found(error, update):
+    print("چت پیدا نشد:", error)
+```
+
+اگر هیچ هندلر خطایی خطا را نگیرد، همان‌طور که انتظار می‌رود دوباره
+`raise` می‌شود.
+
+## دکمه‌ها (`aiosroosh.Button`)
+
+```python
+from aiosroosh import Button
+
+# ساخت سریع
+btn1 = Button.inline("مرد", callback_data="male")
+btn2 = Button.inline("زن", callback_data="female")
+markup = Button.inline_markup([[btn1, btn2]])
+
+# سازنده‌ی زنجیره‌ای
+markup = (
+    Button.builder(inline=True)
+    .add("مرد", callback_data="male")
+    .add("زن", callback_data="female")
+    .build()
+)
+
+# صفحه‌کلید معمولی
+markup = Button.builder().add("گزینه ۱").add("گزینه ۲").build()
+
+# حذف صفحه‌کلید
+markup = Button.remove_keyboard()
+```
+
+## پیام‌رسانی (`Robot`)
+
+تمام متدهای زیر `async` هستند و باید با `await` فراخوانی شوند:
+
+`get_me`, `log_out`, `close_bot`, `send_message`, `forward_message`,
+`copy_message`, `send_photo`, `send_audio`, `send_document`,
+`send_video`, `send_animation`, `send_voice`, `send_video_note`,
+`send_sticker`, `send_media_group`, `send_location`, `send_contact`,
+`send_dice`, `get_file`, `download_file`, `edit_message_text`,
+`edit_message_caption`, `edit_message_media`, `edit_message_reply_markup`,
+`delete_message`, `answer_callback_query`, `set_my_commands`,
+`delete_my_commands`, `get_my_commands`, `get_updates`, `set_webhook`,
+`delete_webhook`, `get_webhook_info`.
+
+برای رسانه‌ها، یا یک رشته‌ی `file_id`، یک آدرس `https://`، یا یک فایل
+باینری باز (`open(path, "rb")`) بدهید — دقیقاً مثل مستندات رسمی.
+
+`Message`: `reply`, `reply_photo`, `reply_audio`, `reply_document`,
+`reply_video`, `reply_animation`, `reply_voice`, `reply_video_note`,
+`reply_location`, `reply_contact`, `reply_dice`, `reply_sticker`,
+`edit_text`, `edit_caption`, `edit_reply_markup`, `delete`, `forward`,
+`pin`, `unpin`.
+
+`Callback` (نام مستعار قدیمی: `CallbackQuery`): `answer`.
+
+هر دو کلاس `Message` و `Callback` هم از `aiosroosh` و هم از
+`aiosroosh.types` قابل ایمپورت‌اند.
+
+### توجه به تفاوت نام‌گذاری با pyrosroosh
+
+در نسخه‌ی sync قبلی، متد `close()` روی `Robot` معادل متد Bot API با نام
+`close` بود. در اینجا چون `Robot` خودش یک نشست HTTP (`aiohttp.ClientSession`)
+دارد که باید بسته شود، نام‌گذاری این‌طور تفکیک شده:
+
+- `bot.close()` → نشست HTTP خود کلاینت (و polling) را می‌بندد.
+- `bot.close_bot()` → متد Bot API با نام `close` را فراخوانی می‌کند
+  (اطلاع به سرور برای جابه‌جایی بین سرورها).
+
+## متدهایی که «به‌زودی»اند ولی اینجا پیاده‌سازی شده‌اند
+
+مطابق مستندات رسمی، متدهای زیر با برچسب «به‌زودی» علامت‌گذاری شده‌اند و
+سروش‌پلاس هنوز آن‌ها را در سرور فعال نکرده:
+
+- `send_chat_action` (`sendChatAction`)
+- `get_user_profile_photos` (`getUserProfilePhotos`)
+- `pin_chat_message` (`pinChatMessage`)
+- `unpin_chat_message` (`unpinChatMessage`)
+- `get_chat` (`getChat`)
+- `get_sticker_set` (`getStickerSet`)
+
+برخلاف `pyrosroosh` که این متدها را اصلاً پیاده نکرده بود، در `aiosroosh`
+همه‌ی این متدها **کامل و دقیقاً طبق مستندات پیاده‌سازی شده‌اند** — یعنی
+درخواست واقعی به همان endpoint مستند ارسال می‌شود. تنها تفاوت این است که
+تا وقتی سروش‌پلاس این قابلیت‌ها را فعال نکرده، پاسخ ناموفق سرور به‌جای
+یک `RPCError` مبهم، در قالب `UnsupportedByBackendError` (همراه با نام
+متد و پیام خام سرور) بازگردانده می‌شود — یعنی قابل تشخیص و قابل مدیریت
+جداگانه با `bot.errors.catch(UnsupportedByBackendError)`. به محض
+فعال شدن هر متد در سمت سرور، بدون هیچ تغییری در کد شما، فراخوانی‌ها با
+موفقیت انجام خواهند شد.
+
+نوع reply-markup به نام `ForceReply` نیز طبق مستندات «به‌زودی» است؛
+`Button.force_reply(...)` ساختار آن را می‌سازد، اما ممکن است تا فعال
+شدن این قابلیت در کلاینت‌های سروش‌پلاس اثری نداشته باشد.
+
+## سلسله‌مراتب خطاها (`aiosroosh.errors`)
+
+```
+PysrooshError
+├── ValidationError            پارامتر نامعتبر (پیش از ارسال درخواست)
+├── AuthError                  توکن نامعتبر
+├── SessionError                خطای شبکه/نشست HTTP
+│   └── SessionExpiredError    استفاده از کلاینتی که close() شده
+└── SoroushPlusAPIError        پاسخ ok=false از سرور
+    ├── UnsupportedByBackendError  متد «به‌زودی» (بالاتر توضیح داده شد)
+    └── RPCError
+        ├── BadRequest
+        │   ├── ChatNotFound
+        │   ├── UserNotFound
+        │   └── MessageNotFound
+        ├── Unauthorized
+        └── FloodWait (دارای فیلد seconds)
+```
+
+## نکته درباره‌ی مینی‌اپ
+
+طبق مستندات، مینی‌اپ در سروش‌پلاس نیز «به‌زودی» است و در حال حاضر هیچ
+API عمومی‌ای برای آن منتشر نشده؛ بنابراین چیزی برای پیاده‌سازی در این
+نسخه وجود ندارد.
+
+## مجوز
+
+MIT

aiosroosh-1.0.0/aiosroosh/__init__.py

@@ -0,0 +1,78 @@
+"""
+aiosroosh — کتابخانه‌ی ناهمگام (async) پایتون برای API بات سروش‌پلاس (splus.ir).
+
+مشابه ``rubka``، همه‌ی کلاس‌های اصلی از ریشه‌ی پکیج هم در دسترس‌اند::
+
+    from aiosroosh import Robot, Message, Callback, Button, filters
+
+    bot = Robot("YOUR_TOKEN_HERE")
+
+    @bot.on_message(filters.command("start"))
+    async def start(bot, message):
+        await message.reply("سلام!")
+
+    bot.run()
+
+و مشابه ``aiobale``، همه‌چیز از ``aiosroosh.asynco`` (کلاینت) و
+``aiosroosh.types`` (مدل‌های داده مثل ``Message``/``Callback``) نیز
+قابل ایمپورت است::
+
+    from aiosroosh.asynco import Robot
+    from aiosroosh.types import Message, Callback
+"""
+
+from .__version__ import __version__
+from .asynco import Robot, Client
+from .types import Message, Callback, CallbackQuery, User, Chat
+from .buttons import Button
+from .events import HandlerPriority, ErrorHandlerBuilder
+from . import filters
+from . import types
+from . import asynco
+from .errors import (
+    PysrooshError,
+    SoroushPlusAPIError,
+    RPCError,
+    FloodWait,
+    Unauthorized,
+    BadRequest,
+    ChatNotFound,
+    UserNotFound,
+    MessageNotFound,
+    SessionExpiredError,
+    SessionError,
+    AuthError,
+    ValidationError,
+    UnsupportedByBackendError,
+)
+
+__all__ = [
+    "__version__",
+    "Robot",
+    "Client",
+    "Message",
+    "Callback",
+    "CallbackQuery",
+    "User",
+    "Chat",
+    "Button",
+    "filters",
+    "types",
+    "asynco",
+    "HandlerPriority",
+    "ErrorHandlerBuilder",
+    "PysrooshError",
+    "SoroushPlusAPIError",
+    "RPCError",
+    "FloodWait",
+    "Unauthorized",
+    "BadRequest",
+    "ChatNotFound",
+    "UserNotFound",
+    "MessageNotFound",
+    "SessionExpiredError",
+    "SessionError",
+    "AuthError",
+    "ValidationError",
+    "UnsupportedByBackendError",
+]

aiosroosh-1.0.0/aiosroosh/__version__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

aiosroosh-1.0.0/aiosroosh/asynco/__init__.py

@@ -0,0 +1,60 @@
+"""
+لایه‌ی ناهمگام (async) اصلی aiosroosh (مشابه ``rubka`` / ``aiobale``).
+
+همه‌چیزی که برای نوشتن یک بات لازم دارید از همین‌جا هم قابل ایمپورت است::
+
+    from aiosroosh.asynco import Robot, Message, Callback, Button, filters
+"""
+
+from .robot import Robot
+from ..types import Message, Callback, CallbackQuery, User, Chat
+from ..buttons import Button
+from ..events import HandlerPriority, ErrorHandlerBuilder
+from .. import filters
+from ..errors import (
+    PysrooshError,
+    SoroushPlusAPIError,
+    RPCError,
+    FloodWait,
+    Unauthorized,
+    BadRequest,
+    ChatNotFound,
+    UserNotFound,
+    MessageNotFound,
+    SessionExpiredError,
+    SessionError,
+    AuthError,
+    ValidationError,
+    UnsupportedByBackendError,
+)
+
+# نام قدیمی برای سازگاری با نسخه‌های پیشین (Client -> Robot).
+Client = Robot
+
+__all__ = [
+    "Robot",
+    "Client",
+    "Message",
+    "Callback",
+    "CallbackQuery",
+    "User",
+    "Chat",
+    "Button",
+    "filters",
+    "HandlerPriority",
+    "ErrorHandlerBuilder",
+    "PysrooshError",
+    "SoroushPlusAPIError",
+    "RPCError",
+    "FloodWait",
+    "Unauthorized",
+    "BadRequest",
+    "ChatNotFound",
+    "UserNotFound",
+    "MessageNotFound",
+    "SessionExpiredError",
+    "SessionError",
+    "AuthError",
+    "ValidationError",
+    "UnsupportedByBackendError",
+]