Metadata-Version: 2.4
Name: soroushthon
Version: 0.2.95
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
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

### از یک پیام ساده تا یک برنامهٔ کامل برای سروش‌پلاس

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

> ✨ **سریع شروع کن؛ هر زمان لازم شد، عمیق‌تر برو.** متدهای ساده برای کارهای روزمره در دسترس‌اند و برای نیازهای پیشرفته‌تر می‌توانی از درخواست‌های خام موجود در بسته استفاده کنی.

## 🌟 چرا سروش‌تون؟

| امکان | آنچه می‌توانی انجام دهی |
| --- | --- |
| 💬 پیام و رویداد | دریافت پیام تازه، پاسخ، ویرایش، حذف، جست‌وجو و ثبت هندلر |
| 📎 فایل و رسانه | ارسال و دریافت عکس، ویدئو، صوت و سند |
| 👥 گفتگوها | دیدن گفتگوها و اطلاعاتشان، کار با اعضا و نقش‌ها |
| 🎯 تعامل | کار با نظرسنجی، رأی و واکنش به پیام |
| 🔐 چند حساب | نشست جداگانه برای هر حساب با `SoroushClient.for_account(...)` |
| 🧩 توسعهٔ پیشرفته | دسترسی به درخواست‌های خام و امکانات پروتکل موجود در کتابخانه |

## 🚀 نصب در چند ثانیه

**Termux، Pydroid 3، Linux و macOS:**

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

**Windows، از جمله ترمینال VS Code:**

```powershell
py -m pip install --upgrade soroushthon
```

به **Python 3.9 یا جدیدتر** نیاز داری. در VS Code همان مفسری را انتخاب کن که بسته را در آن نصب کرده‌ای. روی Android، نصب وابستگی `aiohttp` به سازگاری بسته‌های آن با نسخهٔ Python محیطت بستگی دارد.

## 🧪 اولین برنامه: پیام `ping` را ویرایش کن

کد زیر با **حساب خودت** وصل می‌شود. در گفتگویی که با آن حساب امکان ارسال پیام داری، `ping` بفرست؛ همان پیام به نتیجهٔ تست تغییر می‌کند:

```python
from soroushthon import SoroushClient

client = SoroushClient.for_account("main")


@client.on_message(outgoing=True, pattern=r"(?i)\Aping\Z")
async def ping(event):
    await event.edit("Test passed | Soroushthon 0.2.95")


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

اولین اجرا اطلاعات ورود را درخواست می‌کند. نشست حساب روی دستگاه ذخیره می‌شود؛ فایل‌های `.session` را با دیگران به اشتراک نگذار.

## ✨ تازه‌های نسخهٔ 0.2.95

- **کد کوتاه‌تر، رفتار آشنا:** ۹۸ نام کوتاه برای متدها در دسترس است؛ از جمله `send`، `messages`، `file`، `poll` و `react`. نام‌های کامل قبلی همچنان کار می‌کنند و نام کوتاه، همان آرگومان‌ها و رفتار متد اصلی را دارد.
- **رسیدگی منظم‌تر به رویدادها:** بسته‌های زنده در دسته‌های محدود پردازش می‌شوند و اطلاعات معوق نشست هنگام قطع اتصال ذخیره می‌شود.
- **دیدن وضعیت برنامه:** `update_pipeline_stats()` شمار بسته‌های منتظر و هندلرهای فعال را بدون درخواست شبکه گزارش می‌کند.
- **بازیابی انتخابی گروه‌های دیررس:** گزینهٔ `adaptive_update_polling=True` برای درخواست رویدادهای گروه‌هایی طراحی شده است که تأخیر در پیام‌هایشان تشخیص داده می‌شود؛ همهٔ گروه‌ها را دوره‌ای پیمایش نمی‌کند. این گزینه **به‌صورت پیش‌فرض خاموش** است و اثر آن باید روی حساب واقعی اندازه‌گیری شود.

برای دیدن نسخهٔ نصب‌شده:

```sh
python -c "import soroushthon; print(soroushthon.__version__)"
```

## 🤝 همراه پروژه

برای پرسش، بازخورد و نمونه‌های بیشتر: [کانال سروش‌تون در سروش‌پلاس](https://splus.ir/soroushthon).

Soroushthon پروژه‌ای **غیررسمی** است. برخی امکانات پیشرفته به پاسخ سرور و نوع گفتگو وابسته‌اند و همهٔ درخواست‌های خام در تمام شرایط آزمون زنده نشده‌اند. سورس با مجوز **GPL-3.0-only** ارائه می‌شود؛ جزئیات منشأ کدها در `NOTICE.md` و `TELETHON_LICENSE` داخل بستهٔ سورس آمده است.
