NSplusthon

Asynchronous Python library for the Soroush Plus API

کتابخانه‌ای مدرن و سریع بر پایه asyncio برای تعامل مستقیم با API پیام‌رسان سروش پلاس — به‌عنوان کاربر یا ربات.

📖 Documentation • 📦 PyPI • 🐙 GitHub • 💬 Soroush Plus

✨ ویژگی‌ها

• ✅ پشتیبانی کامل از حساب کاربری و ربات
• ⚡ مبتنی بر asyncio با کارایی بالا
• 🔄 استفاده همزمان به‌صورت Sync و Async
• 🧩 پشتیبانی کامل از TL Schema اختصاصی سروش (Layer 182)
• 💾 مدیریت انعطاف‌پذیر Session: StringSession / MemorySession / SQLiteSession
• 🌐 ترنسپورت WebSocket و DC Routing
• 🔒 رمزنگاری RSA و AES
• 🗝️ بدون نیاز به API ID و API Hash
• 🪜 API مشابه Telethon برای مهاجرت آسان
• 📝 پکیج Typed (py.typed) — تایپ‌چک کامل با Pyright / Pylance / mypy
• 🚀 مسیر OpenSSL بهینه برای AES-IGE (چند برابر سریع‌تر از کتابخانه‌های مشابه)

📊 عملکرد

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

NSplusthon روی این مسیر حدود ۱۸ برابر سریع‌تر است (from_buffer_copy به‌جای کپی بایت‌به‌بایت در سطح Python).

اسکریپت بنچمارک: benchmarks/aes_ige_bench.py

🚀 نصب

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

از PyPI:

pip install nsplusthon

نصب کامل با بهینه‌سازی‌های سرعت (cryptg + پروکسی + پردازش رسانه):

pip install "nsplusthon[fast]"

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

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

وابستگی‌های اختیاری (Extras)

وابستگی‌های اصلی: aiohttp، pyaes، rsa

⚡ شروع سریع

from nsplusthon import SoroushClient
from nsplusthon.sessions import StringSession

client = SoroushClient(StringSession())
client.start()

⚠️ نکته: فایل اسکریپت خود را nsplusthon.py نامگذاری نکنید — پایتون هنگام import با خود کتابخانه تداخل پیدا می‌کند.

💬 یک ربات ساده

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

ارسال فایل

client.send_file("username", "/path/image.jpg")

دانلود رسانه

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

🔄 حالت همگام (Sync)

اگر با async/await راحت نیستید، از API همگام استفاده کنید:

from nsplusthon.sync import SoroushClient
from nsplusthon.sessions import StringSession

with SoroushClient(StringSession()) as client:
    print(client.get_me())
    client.send_message("username", "درود!")

🔐 Session ذخیره‌شده

Session را یک‌بار ذخیره کنید و در اجراهای بعدی از همان استفاده کنید:

from nsplusthon import SoroushClient
from nsplusthon.sessions import StringSession

session = "1AwA..."  # رشته‌ای که پس از ورود اولیه ذخیره می‌کنید

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

📚 مستندات

مستندات کامل پروژه (فارسی):

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

• شروع سریع
• مفاهیم پایه
• مثال‌ها
• سوالات متداول

🤝 مشارکت

Pull requestها خوشحال‌کننده‌اند! لطفاً:

1. یک Issue برای مشکل یا ویژگی جدید باز کنید
2. روی شاخه‌ای جدا کار کنید
3. قبل از ارسال، مطمئن شوید کد byte-compile می‌شود: python -m compileall nsplusthon
4. توضیح تغییرات را در PR بنویسید

⚖️ مجوز

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

⚠️ توجه: این کتابخانه شخص ثالث است و وابستگی به سروش پلاس ندارد. هنگام استفاده، قوانین و شرایط استفاده سروش پلاس را رعایت کنید. مسئولیت نحوه استفاده از این پروژه بر عهده کاربر است.