Metadata-Version: 2.4
Name: soroushthon
Version: 0.2.97
Summary: ⚡ سروش‌تون؛ کتابخانهٔ ناهمگام پایتون برای پیام‌ها، رویدادها و مدیریت حساب سروش‌پلاس
License-Expression: GPL-3.0-only
Project-URL: Community, https://splus.ir/soroushthon
Keywords: soroush plus,asyncio,messaging,user client
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: TELETHON_LICENSE
License-File: NOTICE.md
Requires-Dist: aiohttp>=3.8
Requires-Dist: pyaes>=1.6
Requires-Dist: rsa>=4
Requires-Dist: packaging>=23
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Provides-Extra: media
Requires-Dist: hachoir>=3.3; extra == "media"
Provides-Extra: audio
Requires-Dist: livekit; extra == "audio"
Dynamic: license-file

# سروش‌تون | Soroushthon ⚡

### از یک «سلام» ساده تا رباتی که واقعاً کار می‌کند.

**سروش‌تون** یک کتابخانهٔ ناهمگام پایتون برای ساخت ابزار و ربات روی حساب کاربری سروش‌پلاس است. پیام‌ها را دریافت کن، به رویدادها پاسخ بده، رسانه بفرست و گفتگوهای پررفت‌وآمد را با کدی خوانا مدیریت کن.

```bash
python -m pip install --upgrade soroushthon
```

> نیازمند Python 3.9 یا جدیدتر.

## از اولین پیام شروع کن

```python
from soroushthon import SoroushClient

client = SoroushClient.for_account("main")

@client.on_private_message(pattern=r"(?i)^سلام$")
async def hello(event):
    await event.reply("سلام! 👋")

client.start()
client.run_until_disconnected()
```

`main` نام نشست این حساب است؛ برای هر حساب دیگر، یک نام مستقل انتخاب کن.

## چه چیزهایی در اختیار داری؟

| مسیر | ابزارها |
| --- | --- |
| دریافت رویداد | هندلرهای جدا برای پیوی، گروه، پیام لینک‌دار گروه و ریپلای به پیام‌های خودت؛ فیلترهای ترکیب‌پذیر متن، دستور، رسانه و لینک. |
| پیام و گفتگو | ارسال، پاسخ، ویرایش، حذف و فوروارد؛ پیمایش تاریخچه، جست‌وجوی پیام، گفتگوهای آرشیوشده و پیش‌نویس‌ها. |
| رسانه | عکس، ویدئو، ویس، فایل و آلبوم؛ دانلود و پیمایش رسانه‌ها و پیام‌های سنجاق‌شده. |
| گروه و کانال | اطلاعات گفتگو، وضعیت ارسال همین حساب، مجوزهای ارسال، بن و سکوت، لینک‌های دعوت و ترک گفتگو. |
| ساختار ربات | نشست‌های مستقل برای چند حساب، نام‌های کوتاه متدها، `bind_chat()` و مدیریت وضعیت گفتگو با FSM. |

### رویدادها را دقیق بگیر

```python
from soroushthon import filters

@client.on_private_message(filters.command("start"))
async def start(event):
    await event.reply("خوش اومدی!")

@client.on_group_message(filters.text(r"(?i)\bسلام\b"))
async def group_hello(event):
    print(event.raw_text)

@client.on_link_message
async def group_link(event):
    print("لینک در گروه:", event.raw_text)
```

`on_link_message` برای پیام‌های دریافتی گروه است. برای تشخیص لینک در متن یا پیام دلخواهت، `extract_links(value)` و `has_link(value)` را هم داری.

### وقتی یک گروه را زیاد استفاده می‌کنی

```python
chat = await client.bind_chat("@your_group")
await chat.send("سلام به همه 👋")
info = await chat.info()
```

## تازه در 0.2.97 ✨

- **فرمان‌های خواناتر:** `on_command`، چند نام و پیشوند، و آرگومان‌های نقل‌قول‌دار در `event.command`.
- **رسانه‌های جدا:** ۱۱ فیلتر رسانه، `on_media` و ویژگی `media_type`.
- **متن قابل پردازش:** `filters.regex` و گروه‌های استخراج‌شده در `event.matches`.
- **انتخاب دقیق‌تر:** `from_users`، `chats`، `chat_type`، `all_of` و `any_of`، بدون واکشی شبکه برای هر پیام.
- **انتظار برای پاسخ:** `wait_for_message` با پاک‌سازی هندلر در پایان، timeout و لغو.
- **پاسخ رسانه‌ای کوتاه‌تر:** `reply_photo`، `reply_video`، `reply_audio`، `reply_voice`، `reply_file` و `reply_document`.
- **پیمایش کم‌حافظه:** `iter_groups` و `iter_channels`، بدون ساختن یک فهرست بزرگ از همهٔ گفتگوها.

نمونه‌های کاربردی این امکانات در `NEW_FEATURES_FA.md` همراه بستهٔ انتشار قرار دارند.

## بهبودهای سرعت و پایداری ⚡

- **حذف مکث مصنوعی پیش‌فرض:** درخواست‌های معمول دیگر فاصلهٔ اجباری ۵۰ میلی‌ثانیه ندارند؛ `request_spacing` به‌صورت پیش‌فرض صفر است.
- **ریپلای مطمئن‌تر:** خطای دسترسی به پیام اصلی یا حذف آن، مانع اجرای هندلرهای بعدی نمی‌شود. کش محدود نویسنده و ادغام واکشی‌های هم‌زمان، درخواست‌های تکراری را کم می‌کند.
- **تفکیک کانال و گروه:** `filters.channel` سوپرگروه را رد می‌کند و دکوراتور تازهٔ `on_channel_message` مسیر کانال را مشخص می‌کند.
- **کارهای پس‌زمینهٔ محدود:** عملیات مسدودکنندهٔ کتابخانه از مخزن مشترک حداکثر دو نخ استفاده می‌کنند؛ ذخیرهٔ نشستِ بدون تغییر هم کار اضافی ایجاد نمی‌کند.
- **مرجع تازهٔ API:** نمای روشن و تیره، جست‌وجو، جزئیات پارامترها، مثال‌ها و لینک مستقیم برای متدها.

## مسیر نسخه‌های اخیر 🔧

در به‌روزرسانی‌های اخیر، ورود با کد اول و پایداری اتصال بهتر شده؛ مسیر دریافت پیام‌های پیوی و گروه از هم جدا شده؛ ابزارهای لینک و ریپلای، پیمایش رسانه و پیام‌های سنجاق‌شده، وضعیت ارسال حساب در گروه، مدیریت پیوی، بن و سکوت و نام‌های کوتاه به تجربهٔ توسعه اضافه شده‌اند.

در پردازش رویدادها، صف‌ها، نشست‌ها و کش نیز بازبینی‌هایی برای **مصرف متعادل‌تر RAM و CPU در اجراهای طولانی** انجام شده است. در این نسخه مکث مصنوعی پیش‌فرض درخواست‌ها صفر است. محدودیت‌ها و FloodWait اعلام‌شده از طرف سرور همچنان رعایت می‌شوند.

از این نسخه، وقتی انتشار جدیدتری در PyPI در دسترس باشد، هنگام اتصال یک پیام انگلیسیِ کوتاه در ترمینال می‌بینی که دستور ارتقا را نشان می‌دهد؛ بررسی در پس‌زمینه انجام می‌شود و اجرای ربات را متوقف نمی‌کند.

## مستندات و جامعه 📚

مرجع جست‌وجوپذیر متدهای عمومی، امضاها و مثال‌ها به‌صورت HTML مستقل همراه بستهٔ انتشار است. برای خبرها و نمونه‌کدها به [کانال سروش‌تون](https://splus.ir/soroushthon) سر بزن.

**سروش‌تون — ایده‌ات را بنویس؛ ابزارش آماده است.**

این پروژه با مجوز **GPL-3.0-only** ارائه می‌شود.
