Metadata-Version: 2.4
Name: navix-rubika
Version: 1.2.1
Summary: A modern, fast, and modular framework for creating Rubika bots
Home-page: https://github.com/TheDevErfan/navix-rubika
Author: TheDevErfan
Author-email: TheDevErfan <erfanlotfolahkhajoe8@gmail.com>
License: MIT
Project-URL: Repository, https://github.com/TheDevErfan/navix-rubika
Project-URL: Bug Tracker, https://github.com/TheDevErfan/navix-rubika/issues
Project-URL: Documentation, https://github.com/TheDevErfan/navix-rubika#readme
Keywords: rubika,bot,async,framework
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Chat
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4.0.0,>=3.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Navix Framework 🚀

> **A Modern, Fast, and Modular Framework for Building Rubika Bots**

[![PyPI Version](https://img.shields.io/pypi/v/navix-rubika?style=flat-square&color=blue)](https://pypi.org/project/navix-rubika/)
[![Python Version](https://img.shields.io/pypi/pyversions/navix-rubika?style=flat-square)](https://pypi.org/project/navix-rubika/)
[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/TheDevErfan/navix-rubika/ci.yml?style=flat-square)](https://github.com/TheDevErfan/navix-rubika/actions)

---

## ✨ مقدمه

**Navix** یک فریمورک مدرن، ناهمگام (Async) و ماژولار برای توسعه ربات‌های پیام‌رسان روبیکا است. این فریمورک با طراحی حرفه‌ای و معماری پایدار، ایجاد ربات‌های پیشرفته را آسان می‌کند.

### ویژگی‌های اصلی:
- ✅ **Async/Await**: پشتیبانی کامل از برنامه‌نویسی ناهمگام
- ✅ **روتر قدرتمند**: پردازش پیام‌ها با فیلترهای قابل ترکیب
- ✅ **Middleware**: پردازش خط‌به‌خط درخواست‌ها
- ✅ **FSM**: مدیریت حالت کاربران (State Machine)
- ✅ **صفحه‌کلید**: سازنده‌های ساختاریافته برای keyboard و inline keyboard
- ✅ **مدیریت خطا**: سلسله‌مراتب استثنا‌های شفاف
- ✅ **Retry و Rate Limiting**: کنترل خودکار اتصال و محدودیت سرعت

---

## 📦 نصب

### از PyPI:
```bash
pip install navix-rubika
```

### از منبع:
```bash
git clone https://github.com/TheDevErfan/navix-rubika.git
cd navix-rubika
pip install -e .
```

---

## 🚀 شروع سریع

### ربات ساده:
```python
import asyncio
from navix import APIClient, Router, Dispatcher
from navix.filters import Command

# ایجاد کلاینت
client = APIClient(token="YOUR_BOT_TOKEN")

# ایجاد روتر
router = Router()

# ثبت هندلر
@router.message(Command("start"))
async def start_handler(message):
    await message.reply("سلام! خوش آمدید.")

@router.message()
async def echo_handler(message):
    if message.text:
        await message.reply(f"شما گفتید: {message.text}")

# ایجاد دیسپچر
dispatcher = Dispatcher(client, router)

# شروع ربات
async def main():
    print("ربات شروع شد...")
    await dispatcher.run()

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 🎯 مثال‌های بیشتر

### استفاده از فیلترها:
```python
from navix.filters import Text, Regexp, Private, Group, Contains

# فیلتر متن دقیق
@router.message(Text("سلام"))
async def greet(message):
    await message.reply("و علیکم السلام!")

# فیلتر regex
@router.message(Regexp(r"^/start@\w+$"))
async def handle_mention(message):
    await message.reply("منشن شدم!")

# فیلتر ترکیبی (AND)
@router.message(Private() & Command("settings"))
async def settings(message):
    await message.reply("تنظیمات بات")

# فیلتر ترکیبی (OR)
@router.message(Text("سلام") | Text("درود"))
async def greet_any(message):
    await message.reply("سلام!")

# فیلتر منفی (NOT)
@router.message(~Private())
async def group_only(message):
    await message.reply("این دستور فقط در گروه کار می‌کند")
```

### صفحه‌کلید:
```python
from navix.keyboards import Keyboard, Button, InlineKeyboard, InlineButton

# صفحه‌کلید معمولی
keyboard = Keyboard()
keyboard.add_row([Button("دکمه 1"), Button("دکمه 2")])
keyboard.add_row([Button("دکمه 3")])

await client.send_message(
    chat_id="123456",
    text="یک گزینه انتخاب کنید:",
    keyboard=keyboard.to_dict()
)

# صفحه‌کلید inline
inline_kb = InlineKeyboard()
inline_kb.add_row([
    InlineButton("لینک", url="https://example.com"),
    InlineButton("Callback", callback_data="action_1")
])
```

### FSM (مدیریت حالت):
```python
from navix.fsm import FSM, MemoryStorage
from navix.filters import Command

fsm = FSM(storage=MemoryStorage())

@router.message(Command("profile"))
async def start_profile(message):
    await fsm.set_state(message.author.id, "waiting_for_name")
    await message.reply("نام خود را وارد کنید:")

@router.message()
async def process_name(message):
    state = await fsm.get_state(message.author.id)
    
    if state == "waiting_for_name":
        await fsm.set_data(message.author.id, {"name": message.text})
        await fsm.set_state(message.author.id, "waiting_for_age")
        await message.reply("سن خود را وارد کنید:")
    
    elif state == "waiting_for_age":
        data = await fsm.get_data(message.author.id)
        data["age"] = message.text
        await fsm.update_data(message.author.id, data)
        await fsm.clear_state(message.author.id)
        await message.reply(f"پروفایل ذخیره شد!\nنام: {data['name']}\nسن: {data['age']}")
```

### Middleware:
```python
from navix.middleware import MiddlewareManager

async def logging_middleware(message, next_middleware):
    print(f"پیام دریافت شد: {message.text}")
    await next_middleware(message)
    print(f"پیام پردازش شد")

async def auth_middleware(message, next_middleware):
    if message.author.id not in ALLOWED_USERS:
        await message.reply("دسترسی رد شد")
        return
    await next_middleware(message)

dispatcher.use_middleware(logging_middleware)
dispatcher.use_middleware(auth_middleware)
```

---

## 📚 API Reference

### APIClient
```python
client = APIClient(token="YOUR_TOKEN")

# متدهای اصلی
await client.get_me()  # اطلاعات بات
await client.get_updates(offset=0)  # دریافت آپدیت‌ها
await client.send_message(chat_id="123", text="سلام")
await client.edit_message_text(chat_id="123", message_id="456", text="متن جدید")
await client.delete_message(chat_id="123", message_id="456")
await client.send_poll(chat_id="123", question="سوال؟", options=["گزینه 1", "گزینه 2"])
```

### Message
```python
# خصوصیات
message.message_id  # شناسه پیام
message.text  # متن پیام
message.chat_id  # شناسه چت
message.author  # User object
message.chat  # Chat object

# متدها
await message.reply("پاسخ")  # پاسخ به پیام
await message.edit("متن جدید")  # ویرایش پیام
await message.delete()  # حذف پیام
```

### Router
```python
router = Router()

# ثبت هندلر
@router.message(filter1, filter2, priority=10)
async def handler(message):
    pass

# دستور دستی
await router.dispatch(message)
```

### Filters
```python
# فیلترهای موجود
Command("start")  # /start
Text("سلام")  # متن دقیق
Regexp(r"pattern")  # regex
StartsWith("/")  # شروع با
EndsWith("!")  # پایان با
Contains("کلمه")  # شامل
Private()  # چت خصوصی
Group()  # گروه
User(user_ids=["123"])  # کاربر خاص
Chat(chat_ids=["456"])  # چت خاص

# ترکیب فیلترها
Command("start") & Private()  # AND
Text("سلام") | Text("درود")  # OR
~Private()  # NOT
```

---

## 🧪 تست کردن

```bash
# نصب تست‌ها
pip install navix-rubika[dev]

# اجرای تست‌ها
pytest tests/

# تست با coverage
pytest --cov=navix tests/
```

---

## 🤝 مشارکت

ما خوشحال می‌شویم از مشارکت‌های شما! لطفاً:

1. Fork کنید
2. یک branch جدید ایجاد کنید (`git checkout -b feature/amazing`)
3. تغییرات را commit کنید (`git commit -m 'Add amazing feature'`)
4. Push کنید (`git push origin feature/amazing`)
5. یک Pull Request باز کنید

---

## 📝 لایسنس

این پروژه تحت لایسنس MIT منتشر شده است. برای جزئیات بیشتر [LICENSE](LICENSE) را ببینید.

---

## 📧 تماس

- **GitHub**: [@TheDevErfan](https://github.com/TheDevErfan)
- **Email**: erfanlotfolahkhajoe8@gmail.com

---

## 🙏 تشکر

تشکر از تمام کسانی که در این پروژه مشارکت کردند!
