Metadata-Version: 2.4
Name: NSplusthon
Version: 1.3.4
Summary: Asynchronous Python library for the Soroush Plus API
Author: AmoGrotex
Maintainer: AmoGrotex
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/Amogrotex/NSplusthon
Project-URL: Documentation, https://Amogrotex.github.io/NSplusthon/
Project-URL: Repository, https://github.com/Amogrotex/NSplusthon
Project-URL: Issues, https://github.com/Amogrotex/NSplusthon/issues
Project-URL: PyPI, https://pypi.org/project/nsplusthon/
Keywords: soroush,splus,nsplusthon,mtproto,asyncio,chat,client,messaging
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyaes
Requires-Dist: rsa
Requires-Dist: aiohttp
Provides-Extra: cryptg
Requires-Dist: cryptg; extra == "cryptg"
Provides-Extra: socks
Requires-Dist: python-socks[asyncio]; extra == "socks"
Provides-Extra: fast
Requires-Dist: cryptg; extra == "fast"
Requires-Dist: python-socks[asyncio]; extra == "fast"
Requires-Dist: hachoir; extra == "fast"
Requires-Dist: Pillow; extra == "fast"
Requires-Dist: isal; extra == "fast"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="logo.png" width="200" alt="NSplusthon Logo">

<h1>NSplusthon</h1>

<p>
  <strong>Asynchronous Python library for the Soroush Plus API</strong>
</p>

<p>
  Built on <strong>Telethon</strong> and fully adapted for the
  <strong>Soroush Plus</strong> protocol.
</p>

<p>

<a href="https://pypi.org/project/nsplusthon/">
  <img src="https://img.shields.io/pypi/v/nsplusthon.svg?style=for-the-badge" alt="PyPI">
</a>

<a href="https://pypi.org/project/nsplusthon/">
  <img src="https://img.shields.io/pypi/pyversions/nsplusthon.svg?style=for-the-badge" alt="Python">
</a>

<a href="LICENSE">
  <img src="https://img.shields.io/github/license/Amogrotex/NSplusthon?style=for-the-badge" alt="License">
</a>

<a href="https://github.com/Amogrotex/NSplusthon/stargazers">
  <img src="https://img.shields.io/github/stars/Amogrotex/NSplusthon?style=for-the-badge" alt="Stars">
</a>

<a href="https://github.com/Amogrotex/NSplusthon/issues">
  <img src="https://img.shields.io/github/issues/Amogrotex/NSplusthon?style=for-the-badge" alt="Issues">
</a>

<a href="https://github.com/Amogrotex/NSplusthon/actions">
  <img src="https://img.shields.io/github/actions/workflow/status/Amogrotex/NSplusthon/tests.yml?style=for-the-badge" alt="Build">
</a>

</p>

<p>

<a href="https://Amogrotex.github.io/NSplusthon/"><strong>Documentation</strong></a>
•
<a href="https://pypi.org/project/nsplusthon/"><strong>PyPI</strong></a>
•
<a href="https://github.com/Amogrotex/NSplusthon"><strong>GitHub</strong></a>
•
<a href="https://web.splus.ir"><strong>Soroush Plus</strong></a>

</p>

</div>

---

کتابخانه NSplusthon یک کتابخانه مدرن و قدرتمند برای **Python 3.9+** است که بر پایه
**asyncio** توسعه یافته و امکان تعامل مستقیم با **API پیام‌رسان سروش پلاس**
را به‌عنوان **کاربر** یا **ربات** فراهم می‌کند.

این پروژه بر پایه **Telethon** توسعه یافته و برای معماری اختصاصی سروش پلاس
بازطراحی شده است. کتابخانه از **TL Schema (Layer 182)**،
**RSA Encryption**، **DC Routing** و **WebSocket Transport**
پشتیبانی می‌کند و تجربه‌ای سریع، پایدار و نزدیک به کلاینت رسمی ارائه می‌دهد.

> **Note:** لطفاً هنگام استفاده از این کتابخانه، قوانین و شرایط استفاده سروش پلاس را
> رعایت کنید. مسئولیت استفاده از این پروژه بر عهده کاربر است.

## ویژگی‌ها

- پشتیبانی کامل از حساب کاربری و ربات
- مبتنی بر asyncio با کارایی بالا
- امکان استفاده به‌صورت Sync و Async
- پشتیبانی کامل از TL Schema اختصاصی سروش
- مدیریت Session و StringSession
- پشتیبانی از WebSocket
- پشتیبانی از DC Routing
- رمزنگاری RSA و AES
- بدون نیاز به API ID و API Hash
- API مشابه Telethon برای مهاجرت آسان
- مسیر OpenSSL سریع‌تر از SPlusthon / spluspy (AES-IGE)
- پکیج Typed (`py.typed`) برای Pyright / Pylance / mypy
- `Bot` + `filters` و `safe_send` (FloodWait خودکار)
- `network="ir"` و دانلود موازی (`workers=`)
- CLI: `nsplusthon login` / `nsplusthon doctor`
- `send_png` / `send_photo` / `send_video` / `send_gif` — path **or http(s) link**
- آپلود/دانلود روی **media connection** (رفع `FILE_REQUEST_RECEIVED_ON_CONNECTION_SERVER`)

## عملکرد

بنچمارک AES-IGE روی مسیر **libssl** (بدون cryptg)، ۲۵۶ کیلوبایت،
Intel Xeon @ 2.60GHz، Python 3.13.14، بهترینِ ۹ اجرا.
خروجی با مرجع C بیت‌به‌بیت یکسان بود.

| کتابخانه   | زمان رمز | سرعت          |
| ---------- | -------- | ------------- |
| NSplusthon | 2.50 ms  | **100.1 MiB/s** |
| SPlusthon  | 44.86 ms | 5.6 MiB/s     |
| spluspy    | 42.47 ms | 5.9 MiB/s     |

NSplusthon روی این مسیر حدود **۱۸ برابر** SPlusthon است
(`from_buffer_copy` به‌جای کپی بایت‌به‌بایت).

اسکریپت: [`benchmarks/aes_ige_bench.py`](benchmarks/aes_ige_bench.py)

## نصب

نیاز به **Python 3.9 یا بالاتر**.

از PyPI:

```bash
pip install nsplusthon
```

سریع‌ترین نصب (cryptg + پروکسی + رسانه):

```bash
pip install "nsplusthon[fast]"
```

یا آخرین نسخه توسعه:

```bash
pip install git+https://github.com/Amogrotex/NSplusthon.git
```

## شروع سریع

```python
from nsplusthon import Bot, filters

bot = Bot("my.session", network="ir")

@bot.on_message(filters.private & filters.text)
async def ping(event):
    await event.reply("pong")

bot.run()
```

کلاینت کامل (مثل قبل):

```python
from nsplusthon import SoroushClient
from nsplusthon.sessions import StringSession

client = SoroushClient(StringSession(), network="ir")
client.start()
```

```bash
nsplusthon doctor
nsplusthon login
```

## نمونه

```python
from nsplusthon import SoroushClient, events
from nsplusthon.sessions import StringSession

client = SoroushClient(StringSession())

@client.on(events.NewMessage)
async def handler(event):
    await event.reply("سلام 👋")

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

ارسال پیام

```python
client.send_message(
    "username",
    "سلام از NSplusthon ❤️"
)
```

ارسال فایل / لینک تصویر و ویدیو

```python
await bot.send_photo(chat, "/path/image.jpg")
await bot.send_photo(chat, "https://example.com/pic.png")
await bot.send_video(chat, "https://example.com/clip.mp4")
await bot.send_gif(chat, "https://example.com/anim.gif")
```

دانلود رسانه

```python
message = client.get_messages("username", limit=1)[0]
message.download_media()
```

## Session ذخیره‌شده

```python
from nsplusthon import SoroushClient
from nsplusthon.sessions import StringSession

session = "1AwA..."

with SoroushClient(StringSession(session)) as client:
    print(client.get_me())
```

## وابستگی‌ها

- aiohttp
- pyaes
- rsa

اختیاری:

- cryptg (افزایش سرعت رمزنگاری)

## مستندات

مستندات کامل پروژه:

https://Amogrotex.github.io/NSplusthon/

## مجوز

این پروژه تحت مجوز **GNU GPL v3** منتشر شده است.

---

<div align="center">

**NSplusthon** is maintained by [AmoGrotex](https://github.com/Amogrotex)

Forked from **SPlusthon** by [Shayan Heidari](https://github.com/shayanheidari01) —
which is itself based on [Telethon](https://github.com/LonamiWebs/Telethon).

</div>
