NSplusthon

Asynchronous Python library for the Soroush Plus API

Built on Telethon and fully adapted for the Soroush Plus protocol.

Documentation • PyPI • GitHub • Soroush Plus

کتابخانه 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 روی این مسیر حدود ۱۸ برابر SPlusthon است (from_buffer_copy به‌جای کپی بایت‌به‌بایت).

اسکریپت: benchmarks/aes_ige_bench.py

نصب

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

از PyPI:

pip install nsplusthon

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

pip install "nsplusthon[fast]"

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

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

شروع سریع

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()

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

from nsplusthon import SoroushClient
from nsplusthon.sessions import StringSession

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

nsplusthon doctor
nsplusthon login

نمونه

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()

ارسال پیام

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

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

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")

دانلود رسانه

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

Session ذخیره‌شده

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 منتشر شده است.