کتابخانه ریوپای

riopy

معرفی و نصب

شروع سریع

هسته کتابخانه

ساختار کتابخانه

کلاس Bot

مدل‌های داده

پیشرفته

مدیریت رویدادها

استفاده از Webhook

کیبوردها

مدیریت خطاها

متفرقه

نکات مهم

مجوز و توسعه‌دهنده

نسخه 3.2.0

مستندات کتابخانه riopy

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

نصب

برای نصب کتابخانه از pip استفاده کنید:

pip install riopy

پس از نصب، می‌توانید نسخه نصب شده را بررسی کنید:

import riopy

print(riopy.__version__) # 0.1.1 یا بالاتر

شروع سریع

یک بات ساده که به پیام /start پاسخ می‌دهد:

import riopy

bot = riopy.Bot("توکن_بات_شما")

@bot.on_message()

def handle_message(update):

if update.new_message.text == "/start":

bot.send_message(

chat_id=update.chat_id,

text="سلام! به بات من خوش آمدی 👋"

)

if __name__ == "__main__":

bot.polling()

ساختار کتابخانه

کتابخانه از بخش‌های کلیدی زیر تشکیل شده است:

riopy.Bot: کلاس اصلی برای تعامل با API

riopy.types: مدل‌های داده (Update, Message, Chat, ...)

riopy.exceptions: استثناهای سفارشی برای مدیریت خطا

riopy.polling: مدیریت دریافت پیام‌ها به روش Long Polling

کلاس Bot

ایجاد نمونه

from riopy import Bot

bot = Bot("token")

متدهای اصلی

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

me = bot.get_me()

print(me.bot_title) # نام بات

print(me.bot_id) # شناسه بات

ارسال پیام متنی

message_id = bot.send_message(

chat_id="شناسه_چت",

text="متن پیام",

disable_notification=False, # (اختیاری)

reply_to_message_id="شناسه_پیام", # (اختیاری) پاسخ به پیام خاص

chat_keypad=..., # (اختیاری) کیبورد پایین صفحه

inline_keypad=... # (اختیاری) کیبورد شیشه‌ای

)

ارسال نظرسنجی

message_id = bot.send_poll(

chat_id="شناسه_چت",

question="آیا این کتابخانه مفید است؟",

options=["بله", "خیر", "نظری ندارم"]

)

مدیریت اعضا (مسدود کردن و رفع مسدودیت)

# مسدود کردن کاربر در گروه/کانال

bot.ban_chat_member("chat_id", "user_id")

# رفع مسدودیت کاربر

bot.unban_chat_member("chat_id", "user_id")

مدل‌های داده (riopy.types)

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

Update

فیلد نوع توضیحات

type UpdateTypeEnum نوع آپدیت (NewMessage, UpdatedMessage, ...)

chat_id str شناسه چت

new_message Optional[Message] پیام جدید

updated_message Optional[Message] پیام ویرایش‌شده

Message

فیلد نوع توضیحات

message_id str شناسه پیام

text Optional[str] متن پیام

sender_id str شناسه فرستنده

time int زمان ارسال (timestamp)

مدیریت رویدادها (Polling)

کتابخانه به شما امکان می‌دهد با دکوراتور @bot.on_message() تابعی برای پردازش پیام‌های جدید تعریف کنید.

@bot.on_message()

def my_handler(update):

# پردازش پیام جدید

pass

bot.polling(interval=2.0) # بررسی هر ۲ ثانیه

استفاده از Webhook

اگر سرور با دامنه عمومی و SSL دارید، می‌توانید به جای Polling از Webhook استفاده کنید.

from flask import Flask, request

import riopy

app = Flask(__name__)

bot = riopy.Bot("token")

@app.route("/webhook", methods=["POST"])

def webhook():

data = request.json

update = riopy.types.Update.from_dict(data.get("update"))

# پردازش update مشابه قبل

return "OK"

استفاده از کیبوردها

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

ارسال کیبورد ساده (Chat Keypad)

keypad = {

"rows": [

{

"buttons": [

{"id": "btn1", "type": "Simple", "button_text": "دکمه ۱"},

{"id": "btn2", "type": "Simple", "button_text": "دکمه ۲"}

]

}

],

"resize_keyboard": True

}

bot.send_message(

chat_id=chat_id,

text="یک دکمه انتخاب کنید:",

chat_keypad=keypad,

chat_keypad_type=riopy.types.ChatKeypadTypeEnum.New

)

مدیریت خطاها

کتابخانه استثناهای زیر را تعریف کرده است:

riopy.exceptions.RiopyError: خطای پایه

riopy.exceptions.APIError: خطای برگشتی از API

riopy.exceptions.InvalidTokenError: توکن نامعتبر

from riopy.exceptions import APIError, InvalidTokenError

try:

me = bot.get_me()

except InvalidTokenError:

print("توکن اشتباه است!")

except APIError as e:

print(f"خطای API: {e}")

نکات مهم

توکن: از @BotFather در روبیکا دریافت کنید.

دسترسی: برای دیدن همه پیام‌های گروه/کانال، گزینه «دریافت همه پیام‌ها» را در @BotFather فعال کنید.

مدیریت: برای استفاده از متدهای مدیریتی مانند ban_chat_member، بات باید در گروه ادمین باشد.

مجوز و توسعه‌دهنده

این

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

توسعه‌دهنده: محمد لطیفی‌پور

ایمیل: mohammad.latifi@example.com

سال انتشار: ۱۴۰۴

© ۱۴۰۴ - تمامی حقوق برای کتابخانه riopy محفوظ است.