Fast Rub ⚡

سریع‌ترین، هوشمندترین و کامل‌ترین فریم‌ورک ربات روبیکا برای پایتون

📑 فهرست مطالب

• ✨ ویژگی‌های کلیدی
• 📥 نصب
• 🚀 شروع سریع
  • دریافت پیام‌ها (Polling)
  • کلیک روی دکمه‌های Inline
• 🧠 WaitManager
• 📋 DataForm
• 💬 Conversation
• 🔍 فیلترها
• 🛡️ محافظت از متن (Injection Protection)
• ⌨️ ساختن کیبورد
• 🔄 Hot Reload
• ⏰ Scheduler
• 📡 Signals
• 🔌 Plugins
• 🗄️ ORM داخلی
• 💻 CLI
• 📁 ساختار پروژه
• ⚠️ نکته درباره pyrubi
• 📚 مستندات
• 🗺️ رودمپ
• ❤️ مشارکت
• 📄 لایسنس

✨ ویژگی‌های کلیدی

• ⚡ HTTP/2 + Async-First — سریع‌ترین فریم‌ورک روبیکا با httpx & h2
• 🧠 WaitManager — مدیریت هوشمند Rate Limit (فقط به Client بدهید — بقیه خودکار)
• 📋 DataForm — فرم‌های هوشمند با اعتبارسنجی، کیبورد و callbackهای شرطی
• 💬 Conversation — مکالمات چندمرحله‌ای با State Machine داخلی (کلاسیک + مدرن)
• 🔍 ۲۰۰+ فیلتر — فیلترهای آماده و ترکیبی (AND/OR/NOT) + Inline Filters
• 🔄 Hot Reload — توسعهٔ سریع بدون توقف ربات
• ⏰ Scheduler — زمان‌بندی کارها (interval + daily at)
• 📡 Signals — سیستم Event-driven برای ارتباط ماژول‌ها
• 🔌 Plugins — سیستم پلاگین با لود خودکار از پوشه
• 🗄️ ORM داخلی — دیتابیس SQLite با API ساده و SQL پارامتری
• 📸 Snapshots — Version Control برای تنظیمات ربات
• 🌐 Webhook Server — سرور داخلی (FastAPI/Flask)
• 💻 CLI — ابزار خط فرمان (fastrub new, fastrub run --reload)
• 🛡️ AntiSpam — سیستم ضد اسپم پیشرفته
• 🚀 Middleware, Cache, BackGround-Task هم ابزاری که فکر بکنید
• 📈 قدرت انتخاب انتخاب با شماست هوشمند یا دستی. تنظیم poll_interval, ssl_verify, keeper_messages, ...
• 🪶 فوق‌العاده سبک — تست شده روی ۲۵۶MB RAM DDR1 با Alpine Linux
• 🔒 امنیت — SQL پارامتری، sanitize خودکار، middleware امنیتی و همچنین Markdown/HTML Injection Protection
• ⚙️ سادگی — بدون نیاز به یادگیری یا درگیری با قسمت هایی از فریمورک که نیاز به استفاده از آن ندارید
• 👥 یوزربات — پشتیبانی از یوزربات با فورکی از کتابخانه معروف پایروبی

📥 نصب

pip install fastrub

در صورت قطع شدن میرور اصلی PyPI:

pip install -i https://mirror-pypi.runflare.com/simple fastrub

pip install -i https://mirror.abrha.net/repository/pypi/simple fastrub

pip install -i https://package-mirror.liara.ir/repository/pypi/simple fastrub

⬆ بازگشت به فهرست

🚀 شروع سریع

دریافت پیام‌ها (Polling)

import asyncio
from fast_rub import Client, filters
from fast_rub.types import Update

async def main():
    bot = Client("my_bot")

    @bot.on_message(filters.text("سلام"))
    async def say_hello(msg: Update):
        await msg.reply("**سلام** از طرف فست روب ⚡")

    await bot.run()

asyncio.run(main())

کلیک روی دکمه‌های Inline

import asyncio
from fast_rub import Client
from fast_rub.types import UpdateButton

async def main():
    bot = Client("my_bot")

    @bot.on_button()
    async def button_click(msg: UpdateButton):
        await msg.send_text(f"دکمهٔ {msg.new_message.aux_data.button_id} فشرده شد")

    await bot.run()

asyncio.run(main())

⬆ بازگشت به فهرست

🧠 WaitManager

مدیریت هوشمند ترافیک — قوی‌ترین سیستم مدیریت Rate Limit در بین تمام فریم‌ورک‌های روبیکا. کافی است به Client بدهید — بقیه خودکار انجام می‌شود.

from fast_rub import Client, WaitManager

bot = Client(
    "my_bot",
    wait_manager=WaitManager(
        low_traffic=60,
        medium_traffic=100,
        low_wait=0.0,
        medium_wait=1.0,
        high_wait=3.0,
        time_window=60.0,
        auto_track=True,  # همه چیز خودکار
    )
)

@bot.on_message()
async def handler(msg: Message):
    await msg.reply("سلام!")  # WaitManager خودکار تأخیر را مدیریت می‌کند

await bot.run()

کانال‌های قابل ردیابی:

⬆ بازگشت به فهرست

📋 DataForm

فرم‌های هوشمند — فقط بگویید «چی می‌خواهید» — اعتبارسنجی، کیبورد، و حرکت بین فیلدها خودکار است.

from fast_rub import Client, Conversation
from fast_rub.core.forms import Text, Number, DataForm

class UserInfo(DataForm):
    name: Text = Text("👤 نام خود را وارد کنید", min_len=3, max_len=30)
    age: Number = Number("🎂 چند سالته؟", min=18, max=60, keypad=True)

register = Conversation(name="register")

@register.entry_form(UserInfo, commands=["/register"])
async def done(msg, data):
    await msg.reply(f"ثبت شد:\n👤 {data['name']}\n🎂 {data['age']}")

bot.add_conversation(register)

callbackهای شرطی (پیشرفته):

class AdvancedForm(DataForm):
    name: Text = Text("نام؟", min_len=3, repeat_if=lambda v: "admin" in v.lower())  # دوباره بپرس
    age: Number = Number("سن؟", min=18, max=60)
    job: Text = Text("شغل؟", skip_if=lambda data: data.get("age", 0) < 18)  # زیر ۱۸ سال نپرس
    city: Text = Text("شهر؟", cancel_if=lambda v: v == "هیچی")  # فرم را کنسل کن

⬆ بازگشت به فهرست

💬 Conversation

مکالمات چندمرحله‌ای — روش کلاسیک (Entry + State)

register = Conversation(name="register")

@register.entry(commands=["/register"])
async def ask_name(msg, data):
    await msg.reply("اسمت چیه؟")
    return "waiting_name"

@register.state("waiting_name")
async def get_name(msg, data):
    data["name"] = msg.new_message.text
    await msg.reply(f"سلام {msg.new_message.text}!")
    return Conversation.END

bot.add_conversation(register)

⬆ بازگشت به فهرست

🔍 فیلترها

۲۰۰+ فیلتر آماده

from fast_rub import filters

# فیلتر ساده
@bot.on_message(filters.text("/start"))

# ترکیب (AND)
@bot.on_message(filters.text("/admin") & filters.is_user)

# ترکیب (OR)
@bot.on_message(filters.text("/help") | filters.text("راهنما"))

# NOT
@bot.on_message(~filters.is_group)  # فقط PV

# Async — چک دیتابیس
@bot.on_message(filters.db_exists("users", lambda u: {"chat_id": u.chat_id}, db=my_db))

# Inline Filters (دکمه‌های شیشه‌ای)
@bot.on_button(filters.button_id("home") & filters.sender_ids(["admin_id"]))

⬆ بازگشت به فهرست

🛡️ محافظت از متن (Injection Protection)

با context می‌تونی متغیر توی متن بذاری. مارکدوانِ خودت فعال می‌مونه، ولی هرچی از context میاد خنثی می‌شه. یعنی کاربر نمی‌تونه با فرستادن **bold** یا لینک، فرمت پیامت رو عوض کنه.

await msg.reply("سلام **{{ name }}**", context={"name": msg.new_message.text})

بدون این، یه کاربر می‌تونه با **bold** یا [لینک](url) ظاهر پیامت رو خراب کنه.

⬆ بازگشت به فهرست

⌨️ ساختن کیبورد

from fast_rub.button import KeyPad

keypad = KeyPad()
keypad.append(keypad.simple("btn_1", "دکمه یک"))
keypad.append(keypad.simple("btn_2", "دکمه دو"), keypad.simple("btn_3", "دکمه سه"))

# کیبورد معمولی
await msg.reply("انتخاب کنید:", keypad=keypad.build())

# کیبورد شیشه‌ای
await msg.reply("انتخاب کنید:", inline_keypad=keypad.build())

⬆ بازگشت به فهرست

🔄 Hot Reload

هر بار فایلی را ذخیره کنید، ربات خودکار ری‌استارت می‌شود.

await bot.run(reload=True)

# یا از CLI:
# $ fastrub run --reload

⬆ بازگشت به فهرست

⏰ Scheduler

from fast_rub import Scheduler

scheduler = Scheduler()

@scheduler.every(minutes=30)
async def cleanup():
    print("🧹 پاک‌سازی خودکار")

@scheduler.every(at="08:00")
async def report():
    print("📊 گزارش صبحگاهی")

⬆ بازگشت به فهرست

📡 Signals

from fast_rub import SignalManager

signals = SignalManager()

@signals.on("user_registered")
async def welcome(user_id, chat_id):
    print(f"👋 کاربر {user_id} ثبت‌نام کرد!")

await signals.emit("user_registered", user_id="123", chat_id="456")

⬆ بازگشت به فهرست

🔌 Plugins

فایل plugins/admin.py:

async def setup(client):
    @client.on_message(filters.commands(["admin"]))
    async def panel(msg):
        await msg.reply("🔧 پنل ادمین")

لود خودکار:

await bot.load_plugins("plugins")

⬆ بازگشت به فهرست

🗄️ ORM داخلی

from fast_rub.db import DataBase

db = DataBase("my_bot.db")
await db.start({"users": {"chat_id": "TEXT", "name": "TEXT"}})

await db.write("users", {"chat_id": "123", "name": "علی"})
user = await db.find("users", "*", {"chat_id": "123"})

⬆ بازگشت به فهرست

💻 CLI

fastrub new my_bot      # پروژه جدید
fastrub run             # اجرا
fastrub run --reload    # اجرا با Hot Reload
fastrub version         # نسخه
fastrub docs            # مستندات

⬆ بازگشت به فهرست

📁 ساختار پروژه

fast_rub
├── button # KeyPad
│   ├── __init__.py
│   └── key_pad.py # KeyPad | InlineKeyPad
├── cli.py # CLI - fastrub cmd
├── core # core fastrub
│   ├── async_sync.py # Converter async to sync funcs
│   ├── background.py # BackGround tasks
│   ├── client.py # Client core fastrub
│   ├── config.py # Config client
│   ├── conversation.py # Conversation classic and DataForm
│   ├── forms # Forms for DataForm conversation
│   │   ├── config.py # Config the DataForm
│   │   ├── data_form.py # Config the DataForm
│   │   ├── fields.py # Fields - Number, Text, Choice
│   │   ├── __init__.py
│   │   └── manager.py # Manager DataForm in conversation.py
│   ├── helpers.py # Helpers for client
│   ├── hotreload.py # Hot reload client
│   ├── __init__.py
│   ├── middleware.py # Middleware client
│   ├── plugins.py # Plugins client
│   ├── scheduler.py # Scheduler for scheduling tasks
│   ├── signals.py # Signals (like Django Framework)
│   └── webhook_server.py # Web Server client for webhook local
├── db # DataBases
│   ├── database.py # DataBase ORM fastrub
│   ├── __init__.py
│   ├── message_keeper.py # DB Message Keeper for find message by message id
│   └── session.py # DB Sessions fastrub({name}.faru)
├── __init__.py
├── network # Network fastrub
│   ├── __init__.py
│   └── network.py # Network fastrub - Httpx HTTP/2
├── pyrightconfig.json # Config for Pyright Extension to ignore errors for code that runs synchronously but is async
├── pyrubi # UserBot - Pyrubi(Forked)
│   ├── client # core client
│   │   ├── client.py # core client - API to fast_rub/methods
│   │   └── __init__.py
│   ├── crypto # Cryper
│   │   ├── crypto.py # De/En cryper Conect UserBot rubika
│   │   └── __init__.py
│   ├── enums.py # Enums client
│   ├── exceptions.py # Exceptions
│   ├── filters.py # Filters Messages
│   ├── __init__.py
│   ├── methods # API Methods
│   │   ├── __init__.py
│   │   └── methods.py # Concter to rubika API
│   ├── network # Network UserBot
│   │   ├── helper.py # Helper network
│   │   ├── __init__.py
│   │   ├── network.py # Network API
│   │   └── socket.py # Web Socket rubika
│   ├── sessions # Session
│   │   ├── __init__.py
│   │   └── sessions.py # Session manager
│   ├── types # Types
│   │   ├── __init__.py
│   │   └── socket # Types Web Socket
│   │       ├── __init__.py
│   │       └── message.py # Message Class
│   └── utils # Utils UserBot
│       ├── configs.py # Config client
│       ├── __init__.py
│       ├── reacrions.py # ReActions utils
│       └── utils.py # Utils UserBot
├── type # Conect to types folder
│   └── __init__.py
├── types # Types fastrub
│   ├── errors.py # Exception fastrub
│   ├── exceptions.py # Alias errors.py
│   ├── forms.py # Alias fast_rub/core/forms
│   ├── get_type.py # Utils for Update Class
│   ├── __init__.py
│   ├── metadata.py # Utils for Update Class - MetaData Message
│   ├── models # Models client
│   │   ├── base_model # Base Models for Bot & Chat Classs
│   │   ├── bot.py # Bot Model
│   │   ├── chat.py # Chat Model
│   │   └── __init__.py
│   ├── props.py
│   ├── prop_update.py
│   ├── update_button.py # Inline Message/Update Type fastrub
│   ├── update.py # Message/Update Type fastrub
│   └── webhook.py # WebHook config
└── utils # Utils fastrub
    ├── antispam.py # Anti Spam client
    ├── cache.py # Cache client
    ├── colors.py # Utils for color print client(display_welcome)
    ├── encryption.py # Crypter token bot
    ├── filters.py # Filters for Messages
    ├── __init__.py
    ├── inline_filters.py # InlineFilters for Inline Messages
    ├── logger.py # Logger client
    ├── metadata.py # Creator text for format Markdown/HTML
    ├── snapshot.py # SnapShot JSON client
    ├── template.py # Anti-XSS in message text
    ├── text_parser.py # Text Parser MetaData for text message - Markdown | HTML
    ├── utils.py # More utils
    ├── version.py # Version fastrub
    └── wait_manager.py # Manager Waiting for sending request(send_message, ban, ...)

⬆ بازگشت به فهرست

⚠️ نکته درباره pyrubi

فست روب از یوزر بات پشتیبانی میکند بخش/پوشه pyrubi فورکی از AliGanji1/pyrubi است که برای قسمت یوزر بات استفاده شده است که دارای لایسنس MIT بوده.

⬆ بازگشت به فهرست

📚 مستندات

• مستندات رسمی | مستندات رسمی(گیتهاب)
• گیت‌هاب
• PyPI

مستندات خام جیسون مناسب AI

• متود ها
• مدل ها
• قابلیت های دیگر

⬆ بازگشت به فهرست

🗺️ رودمپ تکمیل نشده

هر قابلیتی اضافه شود/مشکلی دیباگ شود از این رودمپ حذف خواهد شد.

⬆ بازگشت به فهرست

❤️ مشارکت

از Pull Request ها، Issue ها و پیشنهادات استقبال می‌شود.

برای مشارکت:

1. پروژه را Fork کنید.
2. تغییرات خود را اعمال کنید.
3. Commit بگیرید.
4. Pull Request ارسال کنید.

⬆ بازگشت به فهرست

📄 لایسنس

این پروژه تحت لایسنس MIT منتشر شده است.

⬆ بازگشت به فهرست

ساخته‌شده با ❤️ توسط سید محمد حسین موسوی رجا — OandONE