rubiko 1.0.8

کتابخانه رسمی روبیکا - ساخت ربات‌های توکنی - سلف

🤖 روبیکو - کتابخانه پایتون برای پیام‌رسان روبیکا

روبيکو یک کتابخانه جامع و قدرتمند پایتون برای تعامل با پیام‌رسان روبیکا است. این کتابخانه از هر دو نوع ربات رسمی (با توکن) و سلف‌بات (با شماره تلفن) پشتیبانی میکند.

✨ ویژگی‌ها ✅ حالت دوگانه - پشتیبانی از ربات رسمی و سلف‌بات ✅ پوشش کامل API - پیاده‌سازی تمام متدهای API روبیکا ✅ پشتیبانی از Async/Await - عملیات غیرهمزمان ✅ مدیریت نشست - ذخیره‌سازی رمزنگاری شده با انقضای خودکار ✅ سیستم Middleware - پردازش آپدیت‌ها قبل/بعد از هندلرها ✅ دکوراتورهای هوشمند - admin_only، private_only، group_only، rate_limit ✅ محدودیت سرعت - محدودکننده سرعت داخلی برای هندلرها ✅ کیبوردهای شیشه‌ای - دکمه‌های تعاملی در پیام‌ها ✅ پشتیبانی از Webhook - برای محیط‌های تولیدی ✅ مدیریت فایل - آپلود، دانلود و مدیریت فایل‌ها ✅ مدیریت گروه - کنترل کامل ادمین (اخراج، بن، میوت، ترفیع) ✅ ترجمه خودکار - پشتیبانی از ترجمه گوگل به فارسی ✅ تایپ‌هینت - annotations کامل برای پشتیبانی بهتر IDE ✅ رمزنگاری - ذخیره‌سازی امن نشست با رمزنگاری Fernet

📦 نصب

از PyPI (توصیه شده): pip install rubiko

از سورس: git clone https://github.com/radinkarimi/rubiko cd rubiko pip install -e .

پیش‌نیازها: pip install requests aiohttp cryptography

🚀 شروع سریع

۱. ربات رسمی (با توکن):

from rubiko import Robot

bot = Robot("توکن_ربات_شما") me = bot.get_me() print(f"🤖 {me.first_name} (@{me.username})")

@bot.on("message") def echo(update): if update.text: bot.send_message(update.chat_id, f"📢 {update.text}")

bot.run()

۲. سلف‌بات (با شماره تلفن):

from rubiko import RubikaSelfBot

bot = RubikaSelfBot("[phone]") bot.send_code() code = input("📱 کد تأیید را وارد کنید: ") bot.verify_code(code)

@bot.on("message") def echo(update): if update.message and update.message.text: bot.send_message(update.chat_id, f"📢 {update.message.text}")

bot.run()

🤖 ربات رسمی (Robot)

مقداردهی اولیه:

from rubiko import Robot

bot = Robot( token="توکن_ربات_شما", timeout=30 )

دریافت اطلاعات ربات:

me = bot.get_me() print(f"نام: {me.first_name}") print(f"یوزرنیم: @{me.username}") print(f"آیدی: {me.id}")

ارسال پیام‌ها:

پیام متنی: bot.send_message(chat_id, "سلام! 👋") bot.send_message(chat_id, "سلام!", reply_to=123) bot.send_message(chat_id, "متن پررنگ", parse_mode=ParseMode.HTML) bot.send_message(chat_id, "متن پررنگ", parse_mode=ParseMode.MARKDOWN) bot.send_message(chat_id, "پیام بی‌صدا", disable_notification=True)

عکس: bot.send_photo(chat_id, "photo.jpg", "کپشن عکس") with open("photo.jpg", "rb") as f: bot.send_photo(chat_id, f.read(), "کپشن عکس")

ویدیو: bot.send_video( chat_id, "video.mp4", caption="ویدیو زیبا", duration=60, width=1280, height=720 )

فایل: bot.send_document(chat_id, "document.pdf", "فایل PDF")

استیکر: bot.send_sticker(chat_id, "sticker.webp")

موقعیت مکانی: bot.send_location(chat_id, 35.6892, 51.3890)

نظرسنجی: bot.send_poll( chat_id, "نظر شما چیست؟", ["گزینه ۱", "گزینه ۲", "گزینه ۳"], poll_type=PollType.REGULAR, is_anonymous=True, allows_multiple_answers=False )

کیبوردهای شیشه‌ای:

from rubiko import InlineKeyboardButton, InlineKeyboardMarkup

keyboard = InlineKeyboardMarkup() keyboard.add(InlineKeyboardButton("✅ تأیید", callback_data="confirm")) keyboard.add(InlineKeyboardButton("🌐 وبسایت", url="https://rubika.ir")) keyboard.row() keyboard.add(InlineKeyboardButton("🔍 جستجو", switch_inline_query="query"))

bot.send_message( chat_id, "لطفاً انتخاب کنید:", reply_markup=keyboard )

کیبورد معمولی:

from rubiko import ReplyKeyboardMarkup, ReplyKeyboardRemove

keyboard = ReplyKeyboardMarkup([ ["📱 پروفایل", "⚙️ تنظیمات"], ["📊 آمار", "❌ خروج"] ]) bot.send_message(chat_id, "منو:", reply_markup=keyboard) bot.send_message(chat_id, "کیبورد حذف شد", reply_markup=ReplyKeyboardRemove())

مدیریت پیام‌ها:

bot.edit_message_text(chat_id, message_id, "متن جدید") bot.edit_message_caption(chat_id, message_id, "کپشن جدید") bot.delete_message(chat_id, message_id) bot.pin_message(chat_id, message_id) bot.unpin_message(chat_id, message_id) bot.unpin_all_messages(chat_id) bot.forward_message(from_chat_id, message_id, to_chat_id) bot.copy_message(from_chat_id, message_id, to_chat_id, "کپشن جدید")

مدیریت گروه:

chat = bot.get_chat(chat_id) members = bot.get_chat_administrators(chat_id) count = bot.get_chat_members_count(chat_id) bot.kick_chat_member(chat_id, user_id) bot.unban_chat_member(chat_id, user_id) bot.restrict_chat_member(chat_id, user_id, can_send_messages=False, can_send_media=False) bot.promote_chat_member(chat_id, user_id, can_delete_messages=True, can_invite_users=True, can_pin_messages=True) bot.set_chat_title(chat_id, "عنوان جدید") bot.set_chat_description(chat_id, "توضیحات جدید") bot.set_chat_photo(chat_id, "photo.jpg") invite_link = bot.export_chat_invite_link(chat_id)

Webhook:

bot.set_webhook("https://your-domain.com/webhook") info = bot.get_webhook_info() bot.delete_webhook()

اکشن‌های چت:

bot.typing(chat_id) bot.upload_photo(chat_id) bot.upload_video(chat_id) bot.upload_audio(chat_id) bot.upload_document(chat_id)

ترجمه خودکار:

bot.enable_auto_translate_to_persian() bot.disable_auto_translate() translated = bot.translate_text("Hello", "fa")

پراکسی: bot._proxy("http://proxy.example.com:8080")

👤 سلف‌بات (RubikaSelfBot)

مقداردهی اولیه:

from rubiko import RubikaSelfBot

bot = RubikaSelfBot( phone_number="[phone]", session_path="sessions.db", timeout=30, max_retries=3, encrypt_session=True )

احراز هویت:

result = bot.send_code() if result.get("ok"): code = input("کد تأیید: ") bot.verify_code(code)

bot.logout() info = bot.get_session_info() print(f"آیدی کاربر: {info['user_id']}") print(f"وضعیت: {info['is_authenticated']}")

مدیریت پروفایل:

user_info = bot.get_my_info() user = bot.get_user_info(user_id) bot.set_username("new_username") bot.set_bio("بیوگرافی جدید") bot.set_profile_photo("photo.jpg") bot.set_online_status(True) status = bot.get_online_status(user_id)

ارسال پیام: همه متدها مشابه ربات رسمی

مدیریت نشست:

sessions = bot.get_all_sessions() bot.delete_session("[phone]") bot.delete_all_sessions()

📊 ساختار داده‌ها

User: user = User( id=123456789, first_name="علی", last_name="محمدی", username="alimohammadi", phone="[phone]", is_bot=False, is_online=True ) print(user.full_name) # "علی محمدی" print(user.mention) # "@alimohammadi"

Chat: chat = Chat( id=123456789, type=ChatType.PRIVATE, title="گروه تست", username="test_group" )

Message: message = Message( message_id=123, chat_id=456, from_user=user, text="سلام!", date=1234567890, message_type=MessageType.TEXT ) message.reply("پاسخ شما")

Update: update = Update( update_id=123, type=UpdateType.NEW_MESSAGE, chat_id=456, message=message, from_user=user )

🎯 دکوراتورها

@admin_only: from rubiko import admin_only

@bot.on("message") @admin_only(admin_ids=[123456789]) def admin_command(update): bot.send_message(update.chat_id, "دستور ادمین!")

@private_only: from rubiko import private_only

@bot.on("message") @private_only def private_chat(update): bot.send_message(update.chat_id, "چت خصوصی!")

@group_only: from rubiko import group_only

@bot.on("message") @group_only def group_chat(update): bot.send_message(update.chat_id, "گروه!")

@rate_limit: from rubiko import rate_limit

@bot.on("message") @rate_limit(calls_per_second=2, calls_per_minute=30) def limited_handler(update): bot.send_message(update.chat_id, "در حال پردازش...")

@retry_on_error: from rubiko import retry_on_error

@retry_on_error(max_retries=3, delay=1, backoff=2) def unstable_function(): pass

🔧 Middleware

استفاده از Middleware آماده:

from rubiko import LoggingMiddleware, FilterMiddleware, ChatType

bot.add_middleware(LoggingMiddleware()) bot.add_middleware(FilterMiddleware(chat_types=[ChatType.PRIVATE]))

ساخت Middleware سفارشی:

from rubiko import Middleware, Update

class MyMiddleware(Middleware): async def pre_process(self, update: Update) -> Update: print(f"📩 دریافت آپدیت: {update.update_id}") return update

async def post_process(self, update: Update, result):
    print(f"✅ پردازش شد: {update.update_id}")
    return result

bot.add_middleware(MyMiddleware())

💡 مثال‌های پیشرفته

ربات مدیریت گروه کامل:

from rubiko import Robot, admin_only import time

bot = Robot("TOKEN")

@bot.on("message") @admin_only(admin_ids=[123456789]) def admin_panel(update): if not update.text: return

chat_id = update.chat_id
text = update.text.lower()

if text == "/kick" and update.message.get("reply_to_message"):
    target = update.message["reply_to_message"]["from"]["id"]
    bot.kick_chat_member(chat_id, target)
    bot.send_message(chat_id, "✅ کاربر اخراج شد!")

elif text == "/ban" and update.message.get("reply_to_message"):
    target = update.message["reply_to_message"]["from"]["id"]
    bot.kick_chat_member(chat_id, target, until_date=int(time.time()) + 86400)
    bot.send_message(chat_id, "✅ کاربر به مدت ۲۴ ساعت بن شد!")

elif text == "/mute" and update.message.get("reply_to_message"):
    target = update.message["reply_to_message"]["from"]["id"]
    bot.restrict_chat_member(chat_id, target, can_send_messages=False)
    bot.send_message(chat_id, "✅ کاربر میوت شد!")

elif text == "/unmute" and update.message.get("reply_to_message"):
    target = update.message["reply_to_message"]["from"]["id"]
    bot.restrict_chat_member(chat_id, target, can_send_messages=True)
    bot.send_message(chat_id, "✅ کاربر آنمیوت شد!")

elif text == "/pin" and update.message.get("reply_to_message"):
    target_msg = update.message["reply_to_message"]["message_id"]
    bot.pin_message(chat_id, target_msg)
    bot.send_message(chat_id, "📌 پیام پین شد!")

elif text == "/stats":
    count = bot.get_chat_members_count(chat_id)
    admins = bot.get_chat_administrators(chat_id)
    bot.send_message(
        chat_id,
        f"📊 آمار گروه:\n"
        f"اعضا: {count}\n"
        f"ادمین‌ها: {len(admins)}"
    )

bot.run()

ربات با دکمه‌های تعاملی:

from rubiko import Robot, InlineKeyboardButton, InlineKeyboardMarkup

bot = Robot("TOKEN")

@bot.on("message") def interactive(update): if update.text == "/menu": keyboard = InlineKeyboardMarkup() keyboard.add(InlineKeyboardButton("📱 پروفایل", callback_data="profile")) keyboard.row() keyboard.add(InlineKeyboardButton("⚙️ تنظیمات", callback_data="settings")) keyboard.add(InlineKeyboardButton("📊 آمار", callback_data="stats")) keyboard.row() keyboard.add(InlineKeyboardButton("❌ بستن", callback_data="close"))

    bot.send_message(
        update.chat_id,
        "📋 منوی اصلی:",
        reply_markup=keyboard
    )

elif update.text == "/help":
    bot.send_message(
        update.chat_id,
        "🤖 دستورات موجود:\n"
        "/start - شروع ربات\n"
        "/menu - نمایش منو\n"
        "/help - راهنما\n"
        "/ping - بررسی وضعیت"
    )

elif update.text == "/ping":
    bot.send_message(update.chat_id, "🏓 پنگ!")

@bot.on("callback_query") def callback_handler(update): data = update.callback_query.data if data == "profile": bot.send_message(update.chat_id, "📱 پروفایل شما...") elif data == "settings": bot.send_message(update.chat_id, "⚙️ تنظیمات...") elif data == "stats": bot.send_message(update.chat_id, "📊 آمار...") elif data == "close": bot.delete_message(update.chat_id, update.message_id)

bot.run()

سلف‌بات با Async:

from rubiko import AsyncRubikaSelfBot import asyncio

async def main(): bot = AsyncRubikaSelfBot("[phone]") await bot.send_code() code = input("کد: ") await bot.verify_code(code)

@bot.on("message")
async def echo(update):
    if update.message and update.message.text:
        await bot.asend_message(
            update.chat_id,
            f"📢 {update.message.text}"
        )

await bot.run()

asyncio.run(main())

🔧 عیب‌یابی

خطاهای رایج:

خطای احراز هویت: راه حل: توکن یا شماره تلفن خود را بررسی کنید برای ربات‌ها: مطمئن شوید توکن صحیح است bot = Robot("توکن_صحیح")

برای سلف‌بات: مطمئن شوید شماره تلفن صحیح است bot = RubikaSelfBot("[phone]")

خطای اتصال: راه حل: اتصال اینترنت خود را بررسی کنید مطمئن شوید به اینترنت متصل هستید پروکسی را تنظیم کنید bot._proxy("http://proxy.example.com:8080")

خطای محدودیت سرعت: راه حل: از دکوراتور rate_limit استفاده کنید @rate_limit(calls_per_second=2) def handler(update): pass

خطای نشست منقضی شده: راه حل: نشست را حذف و دوباره احراز هویت کنید bot.delete_session("[phone]") bot.send_code() code = input("کد: ") bot.verify_code(code)

📝 مجوز

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

👨‍💻 سازنده

رادین کریمی

📢 کانال رسمی

@rubiko_official

🌍 لینک‌ها

PyPI: https://pypi.org/project/rubiko/ GitHub: https://github.com/rubiko-radinkarimi

---

ساخته شده با ❤️ توسط رادین کریمی