ساخت و استفاده از پلاگین‌های Rubka

۱. ساختار پیشنهادی پروژه

پوشه پروژه شما باید حداقل این شکل باشد:

rubka-awesome-plugin/          # نام دلخواه
├── pyproject.toml
└── rubka_awesome_plugin/          # نام پکیج باید با rubka_ شروع شود (بهتر دیده شود)
    ├── __init__.py                # می‌تواند خالی باشد
    └── plugin.py                  # مهم‌ترین فایل — اینجا منطق پلاگین نوشته می‌شود

۲. نوشتن فایل plugin.py

اینجا قلب پلاگین شماست. می‌توانید handlerهای پیام، فیلترها، state و هر چیز دیگری اضافه کنید.

# rubka_awesome_plugin/plugin.py
from rubka import Router, filters

router = Router(prefix="!")   # همه دستورات با ! شروع می‌شوند (اختیاری)

@router.message(filters.command("hello"))
async def cmd_hello(bot, update):
    """دستور ساده !hello"""
    user = update.get("from_user", {}).get("first_name", "دوست عزیز")
    await bot.send_message(
        chat_id=update["chat_id"],
        text=f"سلام {user} جان! پلاگین من داره کار می‌کنه 🚀",
        reply_to_message_id=update.get("message_id")
    )

@router.message(filters.regex(r"(?i)خوب|عالی|خوبه"))
async def react_positive(bot, update):
    await bot.send_message(
        chat_id=update["chat_id"],
        text="مرسی که خوب هستی 😊",
        reply_to_message_id=update.get("message_id")
    )

def register(bot):
    """این تابع توسط کتابخانه Rubka فراخوانی می‌شود"""
    bot.router.include_router(router)
    # اگر می‌خواهید پیام خوش‌آمدگویی یا لاگ بزنید:
    # print("پلاگین Awesome Plugin لود شد!")

۳. ساخت فایل pyproject.toml (اجباری برای انتشار)

این فایل به pip و PyPI می‌گوید پروژه شما چیست و چگونه ثبت شود.

[project]
name = "rubka-awesome-plugin"
version = "0.1.0"
description = "پلاگین سلام و واکنش مثبت برای بات‌های Rubka"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "rubka>=7.5.0",
]

[project.entry-points."rubka.plugins"]
"awesome-plugin" = "rubka_awesome_plugin.plugin:register"

۴. انتشار در PyPI

این دستورات را در ترمینال (داخل پوشه پروژه) اجرا کنید:

# نصب ابزارهای لازم (فقط یک بار)
pip install --upgrade build twine

# ساخت فایل‌های توزیع
python -m build

# آپلود به PyPI (اولین بار باید توکن بگیرید)
twine upload dist/*

۱. نصب پلاگین با pip

# نصب پلاگین دلخواه
pip install rubka-awesome-plugin

# یا اگر هنوز در PyPI نیست و در گیت‌هاب است
pip install git+https://github.com/username/rubka-awesome-plugin.git

۲. لود کردن پلاگین در کد بات

دو روش اصلی وجود دارد:

from rubka import Robot

bot = Robot(token="u0YourBotTokenHere...")

# روش ۱ — توصیه‌شده — لود خودکار همه پلاگین‌های نصب‌شده
bot.auto_load_plugins()

# روش ۲ — لود دستی (اگر فقط یک یا دو پلاگین می‌خواهید)
# bot.load_plugin("rubka-awesome-plugin")

# حالا بات را اجرا کنید
bot.run()

۳. تست کنید!

اگر پلاگین بالا را نصب کرده باشید، حالا می‌توانید در چت این دستورات را امتحان کنید:

• !hello → جواب سلام می‌دهد
• هر پیامی که شامل «خوب» یا «عالی» باشد → واکنش مثبت می‌دهد