Metadata-Version: 2.4
Name: NSplusthon
Version: 1.8.1
Summary: Async Python client for Soroush Plus (سروش پلاس / SPlus)
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: Documentation (EN), https://amogrotex.github.io/NSplusthon/en/
Project-URL: Repository, https://github.com/Amogrotex/NSplusthon
Project-URL: Changelog, https://github.com/Amogrotex/NSplusthon/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Amogrotex/NSplusthon/issues
Project-URL: PyPI, https://pypi.org/project/nsplusthon/
Keywords: soroush,soroush-plus,soroushplus,splus,nsplusthon,spluspy,mtproto,asyncio,telethon,userbot,bot,chat,client,messaging,iran
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Natural Language :: Persian
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY.md
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

<p align="center">
  <img src="logo.png" width="160" alt="NSplusthon">
</p>

<h1 align="center">NSplusthon</h1>

<p align="center">
  An asynchronous Python MTProto client library for <a href="https://web.splus.ir">Soroush Plus</a>.
</p>

<p align="center">
  <a href="https://pypi.org/project/nsplusthon/"><img src="https://img.shields.io/pypi/v/nsplusthon.svg" alt="PyPI"></a>
  <a href="https://pypi.org/project/nsplusthon/"><img src="https://img.shields.io/pypi/pyversions/nsplusthon.svg" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-blue.svg" alt="License"></a>
</p>

Maintained fork of [SPlusthon](https://github.com/shayanheidari01/SPlusthon), itself derived from [Telethon](https://github.com/LonamiWebs/Telethon). See [NOTICE](NOTICE) and [THIRD_PARTY.md](THIRD_PARTY.md).

---

## Features

- **User Accounts & Bots**: Support for user login and official bot tokens.
- **FSM State Storage**: Finite State Machine with `MemoryStorage` and persistent `SQLiteStorage`.
- **Composable Filters**: Combine event filters using Python logic (`&`, `|`, `~`).
- **Group Moderation**: Built-in flood protection, link checking, profanity filtering, and optional night-lock.
- **Interactive Conversations**: Linear multi-step conversation handler (`async with client.conversation(chat)`).
- **Client Pool**: Manage multiple accounts with client pooling and message broadcasting.
- **Inline Keyboards & Paginator**: Clean keyboard builder and paginated inline menu layout.
- **Soroush Plus Detection**: Link parser and entity classifier for Soroush Plus URLs, URIs, and user IDs.

---

## Installation

```bash
pip install -U nsplusthon
```

Optional dependencies for **fast crypto** (cryptg) and proxy support:

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

PyPI may lag the git tag (Trusted Publishing — see [PUBLISHING.md](PUBLISHING.md)). Latest:

```bash
pip install -U "nsplusthon[fast] @ git+https://github.com/Amogrotex/NSplusthon.git"
```

---

## Quick Start

### Basic Bot Example

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

client = SoroushClient(StringSession())

@client.on(events.NewMessage(pattern=r"(?i)hello"))
async def hello_handler(event):
    await event.reply("Hello!")

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

### Bot Token Login

```python
client.start(bot_token="12345:abcdef")
```

No API ID or API hash is required.

---

## Usage Examples

### Finite State Machine (FSM)

```python
from nsplusthon.fsm import StatesGroup, State, MemoryStorage

class Registration(StatesGroup):
    name = State()
    city = State()

storage = MemoryStorage()
ctx = storage.get_context(user_id=event.sender_id, chat_id=event.chat_id)

await ctx.set_state(Registration.name)
await ctx.update_data(name="Ali")
```

### Group Guard Moderation

```python
from nsplusthon.moderation import GroupGuard

guard = GroupGuard(
    max_flood_messages=5,
    max_mentions=3,
    allowed_domains=["splus.ir"],
    exempt_user_ids={bot_id},
)
result = guard.inspect_message(chat_id=event.chat_id, user_id=event.sender_id, text=event.text)

if result["is_violation"]:
    await event.delete()
```

### Keyboard & Pagination

```python
from nsplusthon import Button
from nsplusthon.paginator import Paginator

paginator = Paginator(items=["Item 1", "Item 2", "Item 3"], page_size=2)
keyboard = paginator.build_keyboard(current_page=1, callback_prefix="page")
```

---

## License

[GPL-3.0](LICENSE). Copyright (C) 2026 AmoGrotex. Upstream Telethon is MIT — see [NOTICE](NOTICE).
