NSplusthon

Async Python library for the Soroush Plus (سروش پلاس / SPlus) API
Telethon-style client for user accounts and bots. Fork of SPlusthon.

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

Documentation · English docs · PyPI · GitHub · Soroush Plus

What is NSplusthon?

NSplusthon is an asyncio Python 3.9+ library that talks to Soroush Plus (سروش پلاس, also called SPlus) over MTProto — the same idea as Telethon for Telegram.

Use it to write userbots and bots: send messages and files, download media, handle events, and route commands. No API ID or API hash is required.

It is a maintained fork of SPlusthon with a faster AES-IGE path, a command router, rate limiting, and encrypted sessions. The import is nsplusthon; the client class is still SoroushClient.

pip install nsplusthon

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

Do not name your script nsplusthon.py — it will shadow the package.

Why NSplusthon instead of SPlusthon / spluspy?

Full write-up: Compare · Migrate from SPlusthon

Features

• User accounts and bots
• High-performance asyncio client
• Command router: /help, middleware, per-user state, rate limits
• Sliding-window RateLimiter (avoid FloodWait / bans)
• Passphrase-encrypted sessions (AES-IGE + PBKDF2)
• Lazy import (PEP 562): import nsplusthon in ~15 ms
• Sync and async APIs
• Soroush TL schema (layer 182)
• StringSession / MemorySession / SQLiteSession
• WebSocket transport and DC routing
• RSA + AES
• No API ID / API hash
• Telethon-like API so Telegram bots are easy to port
• Typed package for Pyright / Pylance / mypy

• پشتیبانی کامل از حساب کاربری و ربات
• 🎛️ Command Router با /help خودکار، middleware و rate-limit
• 🔐 Session رمزنگاری‌شده با passphrase
• 🪜 API مشابه Telethon برای مهاجرت آسان
• 🗝️ بدون نیاز به API ID و API Hash

Install

Requires Python 3.9+.

pip install nsplusthon

Faster crypto, SOCKS proxies, and media helpers:

pip install "nsplusthon[fast]"

Latest git snapshot:

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

Core dependencies: aiohttp, pyaes, rsa.

Quick start

from nsplusthon import SoroushClient
from nsplusthon.sessions import StringSession

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

Send a message, a file, or download media:

client.send_message("username", "سلام از NSplusthon")
client.send_file("username", "/path/image.jpg")

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

Sync API

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

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

Saved / encrypted session

from nsplusthon import SoroushClient
from nsplusthon.sessions import StringSession

session = "1AwA..."  # string from the first login

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

enc = StringSession.encrypt_session(session, "passphrase")
later = StringSession.from_encrypted(enc, "passphrase")

Command router

from nsplusthon import SoroushClient
from nsplusthon.sessions import StringSession
from nsplusthon.router import Router

router = Router().use_rate_limit(max_calls=40, period=60)

@router.command("start", description="Says hello")
async def cmd_start(event, args, kwargs):
    name = kwargs.get("name", "دوست")
    await event.reply(f"سلام {name}!")

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

Documentation

Persian (default): amogrotex.github.io/NSplusthon

• Quick start
• English overview
• Compare libraries
• Migrate from SPlusthon
• Command router
• Examples
• FAQ

Performance

AES-IGE via libssl (no cryptg), 256 KiB, Intel Xeon @ 2.60 GHz, Python 3.13.14, best of 9. Bit-identical to the C reference.

Micro-benchmarks (benchmarks/microbench.py) on Python 3.13:

Scripts: benchmarks/aes_ige_bench.py · benchmarks/microbench.py

Contributing

See CONTRIBUTING.md. Please open an issue first, work on a branch, and run python -m compileall nsplusthon before the PR.

License

GNU GPL v3.

This is a third-party library and is not affiliated with Soroush Plus. Follow the Soroush Plus terms. You are responsible for how you use it.