Metadata-Version: 2.4
Name: soroushthon
Version: 0.2.94
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** ابزار پایتونی ناهمگام برای ساخت چنین برنامه‌هایی با **حساب کاربری سروش‌پلاس** است: از یک پاسخ ساده به پیام تا کار با گفتگوها، رسانه‌ها، نظرسنجی‌ها و رویدادها.

کد روزمره را با متدهای آشنا بنویس و وقتی به جزئیات بیشتری نیاز داری، به درخواست‌های خام کتابخانه دسترسی داشته باش. برای هر حساب هم می‌توانی نشست جداگانه نگه داری.

## در چند خط، اولین واکنش را بساز

این نمونه پیام `ping` را که **خودت با همان حساب** می‌فرستی می‌بیند و روی همان پیام پاسخ می‌دهد:

```python
from soroushthon import SoroushClient

client = SoroushClient.for_account("main")


@client.on_message(outgoing=True, pattern=r"(?i)\Aping\Z")
async def reply_to_ping(event):
    await client.send_message(
        await event.get_input_chat(),
        "pong",
        reply_to=event.id,
    )


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

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

## چه چیزهایی می‌توانی بسازی؟

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

متدهای کوتاهی مانند `send`، `messages`، `file`، `poll` و `react` در کنار نام‌های کامل آن‌ها قرار دارند. این نام‌ها برای ساده‌تر نوشتن کدند؛ هر درخواست خامِ موجود در بسته الزاماً روی سرور در همهٔ شرایط آزموده نشده است.

## نصب؛ یک دستور قابل کپی

به Python 3.9 یا جدیدتر نیاز داری. دستورهای زیر فقط از نویسه‌های انگلیسی استفاده می‌کنند:

**Pydroid 3 و Termux** — در ترمینال همان برنامه:

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

**VS Code روی Linux یا macOS** — در ترمینال پروژه:

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

**VS Code روی Windows** — در ترمینال پروژه:

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

در VS Code مفسر Python همان محیطی را انتخاب کن که دستور نصب را در آن اجرا کردی. روی Android، نصب `aiohttp` و وابستگی‌های آن به سازگاری بسته‌ها با نسخهٔ Python محیطت بستگی دارد؛ در محیطی که این وابستگی‌ها نصب باشند، خود Soroushthon به‌صورت wheel مستقل از معماری ارائه می‌شود.

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

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

در Windows، اگر با `py` نصب کردی، در دستور بررسی هم `python` را با `py` جایگزین کن.

## از اینجا ادامه بده

برای هر حساب یک نام انتخاب کن: `main` برای حساب اصلی یا نام‌هایی مثل `work` برای نشست جدا. برای برنامهٔ ناهمگام موجود هم می‌توانی از `await client.start()` و `await client.disconnect()` استفاده کنی. نصب وابستگی‌های اصلی `aiohttp`، `pyaes` و `rsa` را `pip` انجام می‌دهد؛ بعضی امکانات رسانه‌ای وابستگی اختیاری دارند.

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

برای گفتگو دربارهٔ پروژه و دیدن نمونه‌های بیشتر: [@soroushthon در سروش‌پلاس](https://splus.ir/soroushthon).
