Metadata-Version: 2.4
Name: nicotin
Version: 0.1.5
Summary: An async Rubika library with a Pyrogram-style API.
License: MIT License
        
        Copyright (c) 2026 NICOTIN contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: rubika,rubika-bot,rubika-api,bot,async,telegram-style,pyrogram-style
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: AsyncIO
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Dynamic: license-file

# 🚀 NICOTIN

**NICOTIN** is an asynchronous Python library for building **Rubika bots** using the **Rubika Bot API**.

Inspired by the developer experience of libraries such as **Pyrogram**, NICOTIN provides a clean and familiar API for Python developers who want to build Rubika bots with minimal learning overhead.

> ⚡ Simple, Async, and developer-friendly Python library for Rubika bots.

---

# 🇬🇧 English

## ✨ Features

* ⚡ Fully asynchronous architecture
* 🤖 Bot Token authentication
* 🔌 Rubika Bot API integration
* 🎯 Powerful filter system
* 🔗 Filter composition with `&`, `|`, and `~`
* 🧩 Handler-based event system
* 💬 Message management
* 📸 Media receiving and downloading
* 🔘 Callback Query support
* ✏️ Message editing and deletion
* 🔄 Message forwarding
* 💾 Chat information and history
* 🌐 Webhook support
* 🛡️ Dedicated error handling
* 📋 Connection and runtime logging
* 🧱 Modular and extensible architecture

---

## 📦 Installation

Install NICOTIN directly from PyPI:

```bash
pip install nicotin
```

Or install the latest development version from source:

```bash
git clone https://github.com/imohammad70707/nicotin.git
cd nicotin
pip install -e .
```

---

## 🔑 Bot Token

NICOTIN uses **Bot Token authentication**.

Create a bot through `@rubika_bot` on Rubika and use the generated token when initializing the client.

> 🔐 **Never expose your Bot Token in public repositories or source code.**

---

## ⚡ Quick Start

```python
from nicotin import Client, filters

app = Client(bot_token="YOUR_BOT_TOKEN")


@app.on_message(filters.command("start"))
async def start(client: Client, message):
    await message.reply("Hello from NICOTIN! 👋")


@app.on_message(filters.text & ~filters.command(["start", "help"]))
async def echo(client: Client, message):
    await message.reply(message.text)


if __name__ == "__main__":
    app.run()
```

Run your bot:

```bash
python bot.py
```

---

## 🎯 Filters

NICOTIN provides a flexible filter system inspired by modern Python bot frameworks.

```python
filters.text
filters.photo
filters.command("start")
```

Filters can be combined using logical operators:

```python
filters.text & filters.photo
```

```python
filters.photo | filters.video
```

```python
~filters.command(["start", "help"])
```

Example:

```python
filters.text & ~filters.command(["start", "help"])
```

---

## 🧩 Handlers

Register bot events using simple decorators:

```python
@app.on_message(...)
async def handler(client, message):
    ...
```

Callback queries:

```python
@app.on_callback_query()
async def callback(client, callback_query):
    ...
```

---

## 📚 API Overview

| API                          | Description               |
| ---------------------------- | ------------------------- |
| `Client(bot_token=...)`      | Create a bot client       |
| `app.run()`                  | Start the bot             |
| `Client.get_me()`            | Get bot information       |
| `Client.send_message()`      | Send a message            |
| `Client.send_photo()`        | Send a photo              |
| `Client.send_video()`        | Send a video              |
| `Client.send_document()`     | Send a document           |
| `Client.edit_message_text()` | Edit a message            |
| `Client.delete_messages()`   | Delete messages           |
| `Client.forward_messages()`  | Forward messages          |
| `Client.get_chat()`          | Get chat information      |
| `Client.get_chat_history()`  | Get chat history          |
| `Client.set_webhook()`       | Configure webhook         |
| `message.reply()`            | Reply to a message        |
| `message.edit_text()`        | Edit a message            |
| `message.delete()`           | Delete a message          |
| `filters.text`               | Text message filter       |
| `filters.photo`              | Photo filter              |
| `filters.command()`          | Command filter            |
| `@app.on_message()`          | Register message handler  |
| `@app.on_callback_query()`   | Register callback handler |

---

## 🛡️ Error Handling

NICOTIN provides a dedicated exception system based on `NicotinError`.

| Exception          | Description                  |
| ------------------ | ---------------------------- |
| `AuthError`        | Invalid or missing Bot Token |
| `RPCError`         | Non-OK response from Rubika  |
| `FloodWait`        | Rate limit reached           |
| `ConnectionError_` | Network connection failure   |
| `RequestTimeout`   | Request timeout              |

Example:

```python
from nicotin.errors import AuthError

try:
    ...
except AuthError:
    print("Invalid bot token.")
```

---

## 🧰 Requirements

* Python **3.10+**
* `httpx`

Dependencies are installed automatically when NICOTIN is installed through PyPI.

---

## 📄 License

NICOTIN is released under the **MIT License**.

See the [`LICENSE`](LICENSE) file for details.

---

## 👨‍💻 Developer

**MR API**

Built with Python to make Rubika bot development simpler, cleaner, and more accessible.

---

## ⭐ Support

If NICOTIN is useful to you, consider giving the project a ⭐ on GitHub.

**Happy Coding 🚀**

---

# 🇮🇷 فارسی

## 🚀 معرفی

**NICOTIN** یک کتابخانه‌ی Python مبتنی بر `asyncio` برای ساخت **ربات‌های روبیکا** با استفاده از **Rubika Bot API** است.

این کتابخانه با الهام از تجربه‌ی توسعه‌دهندگان کتابخانه‌هایی مانند **Pyrogram** طراحی شده تا برنامه‌نویسان Python بتوانند با ساختاری ساده و آشنا، ربات‌های روبیکای خود را توسعه دهند.

> ⚡ ساده، Async و توسعه‌دهنده‌پسند برای ساخت ربات‌های روبیکا

---

## ✨ ویژگی‌ها

* ⚡ معماری کاملاً Async
* 🤖 احراز هویت با Bot Token
* 🔌 اتصال به Rubika Bot API
* 🎯 سیستم قدرتمند Filters
* 🔗 ترکیب فیلترها با `&`، `|` و `~`
* 🧩 سیستم Handler
* 💬 مدیریت پیام‌ها
* 📸 دریافت و دانلود رسانه
* 🔘 پشتیبانی از Callback Query
* ✏️ ویرایش و حذف پیام‌ها
* 🔄 فوروارد پیام‌ها
* 💾 دریافت اطلاعات و تاریخچه چت
* 🌐 پشتیبانی از Webhook
* 🛡️ سیستم مدیریت خطای اختصاصی
* 📋 لاگ‌گذاری وضعیت اتصال و اجرا
* 🧱 ساختار ماژولار و قابل توسعه

---

## 📦 نصب

نصب مستقیم از PyPI:

```bash
pip install nicotin
```

یا نصب نسخه توسعه از سورس:

```bash
git clone https://github.com/imohammad70707/nicotin.git
cd nicotin
pip install -e .
```

---

## 🔑 Bot Token

NICOTIN از **Bot Token** برای احراز هویت ربات استفاده می‌کند.

برای ساخت ربات می‌توانید از `@rubika_bot` در روبیکا استفاده کرده و Token دریافت‌شده را هنگام ساخت Client وارد کنید.

> 🔐 **هرگز Bot Token خود را در Repository عمومی یا کدهای قابل انتشار قرار ندهید.**

---

## ⚡ شروع سریع

```python
from nicotin import Client, filters

app = Client(bot_token="YOUR_BOT_TOKEN")


@app.on_message(filters.command("start"))
async def start(client: Client, message):
    await message.reply("سلام از NICOTIN! 👋")


@app.on_message(filters.text & ~filters.command(["start", "help"]))
async def echo(client: Client, message):
    await message.reply(message.text)


if __name__ == "__main__":
    app.run()
```

اجرای ربات:

```bash
python bot.py
```

---

## 🎯 Filters

NICOTIN دارای یک سیستم فیلتر انعطاف‌پذیر است:

```python
filters.text
filters.photo
filters.command("start")
```

امکان ترکیب فیلترها نیز وجود دارد:

```python
filters.text & filters.photo
```

```python
filters.photo | filters.video
```

```python
~filters.command(["start", "help"])
```

مثال:

```python
filters.text & ~filters.command(["start", "help"])
```

---

## 🧩 Handlers

ثبت رویدادهای ربات با Decorator انجام می‌شود:

```python
@app.on_message(...)
async def handler(client, message):
    ...
```

برای Callback Query:

```python
@app.on_callback_query()
async def callback(client, callback_query):
    ...
```

---

## 📚 نمای کلی API

| API                          | کاربرد                        |
| ---------------------------- | ----------------------------- |
| `Client(bot_token=...)`      | ساخت Client ربات              |
| `app.run()`                  | اجرای ربات                    |
| `Client.get_me()`            | دریافت اطلاعات بات            |
| `Client.send_message()`      | ارسال پیام                    |
| `Client.send_photo()`        | ارسال عکس                     |
| `Client.send_video()`        | ارسال ویدیو                   |
| `Client.send_document()`     | ارسال فایل                    |
| `Client.edit_message_text()` | ویرایش پیام                   |
| `Client.delete_messages()`   | حذف پیام                      |
| `Client.forward_messages()`  | فوروارد پیام                  |
| `Client.get_chat()`          | دریافت اطلاعات چت             |
| `Client.get_chat_history()`  | دریافت تاریخچه چت             |
| `Client.set_webhook()`       | تنظیم Webhook                 |
| `message.reply()`            | پاسخ به پیام                  |
| `message.edit_text()`        | ویرایش پیام                   |
| `message.delete()`           | حذف پیام                      |
| `filters.text`               | فیلتر پیام متنی               |
| `filters.photo`              | فیلتر عکس                     |
| `filters.command()`          | فیلتر دستورات                 |
| `@app.on_message()`          | ثبت Handler پیام              |
| `@app.on_callback_query()`   | ثبت Handler مربوط به Callback |

---

## 🛡️ مدیریت خطا

NICOTIN دارای سیستم خطای اختصاصی بر پایه‌ی `NicotinError` است.

| خطا                | توضیح                        |
| ------------------ | ---------------------------- |
| `AuthError`        | Token نامعتبر یا خالی        |
| `RPCError`         | پاسخ غیر OK از سرور روبیکا   |
| `FloodWait`        | رسیدن به محدودیت درخواست     |
| `ConnectionError_` | خطا در اتصال شبکه            |
| `RequestTimeout`   | طولانی شدن بیش از حد درخواست |

مثال:

```python
from nicotin.errors import AuthError

try:
    ...
except AuthError:
    print("Bot token نامعتبر است.")
```

---

## 🧰 نیازمندی‌ها

* Python **3.10 یا بالاتر**
* `httpx`

وابستگی‌های موردنیاز هنگام نصب NICOTIN از PyPI به‌صورت خودکار نصب می‌شوند.

---

## 📄 مجوز

NICOTIN تحت **MIT License** منتشر شده است.

برای مشاهده جزئیات، فایل [`LICENSE`](LICENSE) را مطالعه کنید.

---

## 👨‍💻 توسعه‌دهنده

**MR API**

ساخته‌شده با Python برای ساده‌تر، تمیزتر و قابل‌دسترس‌تر کردن توسعه‌ی ربات‌های روبیکا.

---

## ⭐ حمایت از پروژه

اگر NICOTIN برای شما مفید است، می‌توانید با ⭐ دادن به پروژه در GitHub از توسعه‌ی آن حمایت کنید.

**Happy Coding 🚀**
