Pyrobale چیست؟ آموزش ساخت ربات بله با پایتون از صفر تا پیشرفته

اگر با زبان برنامه‌نویسی پایتون آشنا باشید، احتمالاً می‌دانید که ساخت ربات‌های پیام‌رسان یکی از کاربردهای جذاب این زبان است. ربات‌ها می‌توانند بسیاری از فعالیت‌های روزمره را خودکار کنند؛ از پاسخ‌گویی به کاربران و مدیریت گروه‌ها گرفته تا ارائه خدمات، دریافت سفارش و اجرای سیستم‌های هوشمند.

در ایران، پیام‌رسان بله یکی از پلتفرم‌هایی است که امکان توسعه ربات برای آن وجود دارد. اما برای ساخت یک ربات حرفه‌ای، لازم نیست تمام درخواست‌های API را به‌صورت دستی مدیریت کنید.

اینجاست که Pyrobale وارد می‌شود!

Pyrobale یک کتابخانه پایتونی برای کار با Bale Bot API است که فرایند توسعه ربات‌های بله را ساده‌تر می‌کند. این کتابخانه با ارائه ساختاری پایتونی، امکاناتی مانند مدیریت پیام‌ها، ساخت دکمه‌های تعاملی، دریافت رویدادها و ارسال فایل را در اختیار توسعه‌دهندگان قرار می‌دهد.

در این آموزش، از نصب Pyrobale شروع می‌کنیم و قدم‌به‌قدم یک ربات کاربردی می‌سازیم.

فهرست مطالب

• Pyrobale چیست؟
• چرا از Pyrobale استفاده کنیم؟
• قابلیت‌های اصلی Pyrobale
• پیش‌نیازهای نصب
• نصب Pyrobale
• ساخت اولین ربات بله
• ساخت ربات Echo
• مدیریت دستورات کاربران
• ساخت کیبوردهای تعاملی
• مدیریت پیام‌ها و رویدادها
• نکات مهم برای اجرای ربات در محیط عملیاتی
• جمع‌بندی

۱. Pyrobale چیست؟

Pyrobale یک کتابخانه پایتونی (Python Library) است که به‌عنوان یک Wrapper برای API ربات‌های پیام‌رسان بله طراحی شده است.

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

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

Pyrobale بخش زیادی از این پیچیدگی را پشت یک رابط برنامه‌نویسی ساده‌تر پنهان می‌کند.

برای مثال، ارسال پیام به کاربر با استفاده از Pyrobale به شکل زیر انجام می‌شود:

await message.reply("سلام! به ربات ما خوش آمدید.")

به‌جای اینکه مستقیماً درخواست HTTP بسازید و پاسخ API را پردازش کنید، می‌توانید از متدهای آماده کتابخانه استفاده کنید.

این موضوع باعث می‌شود تمرکز بیشتری روی منطق اصلی برنامه داشته باشید.

۲. چرا از Pyrobale استفاده کنیم؟

یکی از مهم‌ترین مزیت‌های Pyrobale، کاهش پیچیدگی توسعه ربات‌های بله است.

برخی از قابلیت‌ها و ویژگی‌های این کتابخانه عبارت‌اند از:

یکی دیگر از ویژگی‌های جالب Pyrobale، امکان استفاده از ساختارهای Async و Sync است.

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

۳. پیش‌نیازهای نصب Pyrobale

قبل از شروع، بهتر است موارد زیر را آماده کنید:

• Python نسخه 3.9 یا بالاتر
• آشنایی مقدماتی با زبان Python
• آشنایی اولیه با توابع و ماژول‌ها
• دسترسی به پیام‌رسان بله
• توکن ربات

برای بررسی نسخه پایتون، دستور زیر را اجرا کنید:

python --version

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

python3 --version

اگر پایتون روی سیستم شما نصب نیست، ابتدا آن را نصب کنید.

ایجاد محیط مجازی

پیشنهاد می‌شود برای هر پروژه پایتونی از محیط مجازی (Virtual Environment) استفاده کنید.

ابتدا یک پوشه برای پروژه بسازید:

mkdir pyrobale-project
cd pyrobale-project

سپس محیط مجازی را ایجاد کنید:

python -m venv venv

در ویندوز:

venv\Scripts\activate

در لینوکس و macOS:

source venv/bin/activate

با فعال‌سازی محیط مجازی، وابستگی‌های پروژه از سایر پروژه‌های پایتونی جدا خواهند شد.

۴. نصب Pyrobale

پس از آماده‌سازی محیط، نصب کتابخانه بسیار ساده است.

دستور زیر را اجرا کنید:

pip install pyrobale

برای بررسی نصب موفقیت‌آمیز، می‌توانید از دستور زیر استفاده کنید:

pip show pyrobale

این دستور اطلاعات مربوط به نسخه نصب‌شده کتابخانه را نمایش می‌دهد.

برای نصب مجدد یا به‌روزرسانی نسخه موجود نیز می‌توانید از دستور زیر استفاده کنید:

pip install --upgrade pyrobale

نکته: پیش از استفاده در پروژه‌های عملیاتی، نسخه نصب‌شده و سازگاری آن با مستندات همان نسخه را بررسی کنید.

۵. ساخت اولین ربات بله با Pyrobale

حالا که کتابخانه نصب شده است، زمان ساخت اولین ربات رسیده است.

ابتدا باید یک ربات در بله ایجاد کنید و توکن دسترسی آن را دریافت کنید.

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

پس از دریافت توکن، یک فایل با نام main.py ایجاد کنید.

کد زیر یک نمونه ساده از اولین ربات Pyrobale است:

from pyrobale.client import Client
from pyrobale.objects import Message, UpdatesTypes

bot = Client("YOUR_BOT_TOKEN")


@bot.on_message()
async def message_handler(message: Message):
    await message.reply("سلام! ربات من با Pyrobale ساخته شده است.")


bot.run()

در این مثال چند بخش مهم وجود دارد.

بررسی کد

۱. وارد کردن Client

from pyrobale.client import Client

کلاس Client برای ایجاد ارتباط با API ربات بله استفاده می‌شود.

۲. وارد کردن Message

from pyrobale.objects import Message

کلاس Message اطلاعات مربوط به پیام دریافتی را در اختیار ما قرار می‌دهد.

۳. ساخت نمونه ربات

bot = Client("YOUR_BOT_TOKEN")

در این قسمت یک نمونه از Client ساخته می‌شود.

به‌جای YOUR_BOT_TOKEN باید توکن واقعی ربات قرار بگیرد.

۴. تعریف Message Handler

@bot.on_message()
async def message_handler(message: Message):
    await message.reply("سلام!")

دکوراتور on_message برای ثبت تابع مدیریت پیام استفاده می‌شود.

هر زمان پیام جدیدی دریافت شود، تابع موردنظر اجرا خواهد شد.

۵. اجرای ربات

bot.run()

این دستور فرایند اجرای ربات را آغاز می‌کند.

حالا می‌توانید فایل را اجرا کنید:

python main.py

اگر تنظیمات صحیح باشند، ربات آماده دریافت پیام خواهد بود.

۶. ساخت ربات Echo با Pyrobale

یکی از بهترین مثال‌ها برای یادگیری کار با پیام‌ها، ساخت ربات Echo است.

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

کد کامل:

from pyrobale.client import Client
from pyrobale.objects import Message

bot = Client("YOUR_BOT_TOKEN")


@bot.on_message()
async def echo_handler(message: Message):

    if message.text:
        await message.reply(message.text)


bot.run()

در این مثال:

• ابتدا پیام جدید دریافت می‌شود.
• محتوای متنی پیام بررسی می‌شود.
• اگر پیام دارای متن باشد، همان متن دوباره ارسال می‌شود.

برای مثال، اگر کاربر پیام زیر را ارسال کند:

Hello Pyrobale!

ربات نیز پاسخ می‌دهد:

Hello Pyrobale!

این مثال ساده می‌تواند پایه‌ای برای ساخت ربات‌های پیچیده‌تر باشد.

۷. مدیریت دستورات کاربران

در بسیاری از ربات‌ها، کاربران برای دسترسی به قابلیت‌های مختلف از دستوراتی مانند /start و /help استفاده می‌کنند.

با Pyrobale می‌توان به‌راحتی چنین دستوراتی را مدیریت کرد.

مثال:

from pyrobale.client import Client
from pyrobale.objects import Message

bot = Client("YOUR_BOT_TOKEN")


@bot.on_message()
async def command_handler(message: Message):

    if message.text == "/start":

        await message.reply(
            "سلام! به ربات ما خوش آمدید."
        )

    elif message.text == "/help":

        await message.reply(
            "برای استفاده از ربات، پیام خود را ارسال کنید."
        )

    elif message.text == "/about":

        await message.reply(
            "این ربات با استفاده از کتابخانه Pyrobale ساخته شده است."
        )

    else:

        await message.reply(
            "دستور واردشده معتبر نیست."
        )


bot.run()

در این مثال، ربات سه دستور اصلی دارد:

البته می‌توانید متناسب با نیاز پروژه، دستورات بیشتری به آن اضافه کنید.

۸. ساخت کیبوردهای تعاملی

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

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

Pyrobale امکان ساخت Inline Keyboard را در اختیار توسعه‌دهندگان قرار می‌دهد.

برای مثال:

from pyrobale.client import Client
from pyrobale.objects import (
    Message,
    InlineKeyboardMarkup,
    CopyTextButton
)

bot = Client("YOUR_BOT_TOKEN")


@bot.on_message()
async def keyboard_handler(message: Message):

    if message.text == "/start":

        buttons = InlineKeyboardMarkup()

        buttons.add_button(
            "وب‌سایت",
            url="https://pyrobale.ir"
        )

        buttons.add_button(
            "ارسال بازخورد",
            callback_data="feedback"
        )

        buttons.add_row()

        buttons.add_button(
            "کپی متن",
            copy_text_button=CopyTextButton("Hello Pyrobale!")
        )

        await message.reply(
            "یکی از گزینه‌های زیر را انتخاب کنید:",
            reply_markup=buttons
        )


bot.run()

در این مثال سه نوع دکمه ایجاد شده است:

دکمه URL

buttons.add_button(
    "وب‌سایت",
    url="https://pyrobale.ir"
)

این دکمه کاربر را به یک آدرس اینترنتی هدایت می‌کند.

دکمه Callback

buttons.add_button(
    "ارسال بازخورد",
    callback_data="feedback"
)

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

دکمه Copy Text

buttons.add_button(
    "کپی متن",
    copy_text_button=CopyTextButton("Hello Pyrobale!")
)

این دکمه امکان کپی کردن یک متن مشخص را فراهم می‌کند.

نکته مهم این است که ساخت دکمه Callback به‌تنهایی به معنی پردازش رویداد آن نیست. برای اجرای عملیات موردنظر باید مدیریت Callback Query را نیز پیاده‌سازی کنید.

۹. کار با رویدادها در Pyrobale

ربات‌ها تنها با دریافت پیام متنی کار نمی‌کنند.

در یک پروژه واقعی ممکن است لازم باشد رویدادهای مختلف را مدیریت کنید.

برای مثال:

• دریافت پیام جدید
• دریافت Callback Query
• مدیریت فایل‌ها
• پردازش تعاملات کاربران

Pyrobale از ساختار Event Handler برای مدیریت رویدادها پشتیبانی می‌کند.

برای مثال، می‌توانید از add_handler استفاده کنید:

from pyrobale.client import Client
from pyrobale.objects import Message, UpdatesTypes

bot = Client("YOUR_BOT_TOKEN")


async def handle_message(message: Message):

    if message.text == "/start":

        await message.reply(
            "ربات با موفقیت اجرا شد!"
        )


bot.add_handler(
    UpdatesTypes.MESSAGE,
    handle_message
)

bot.run()

در این روش، تابع مدیریت پیام به‌صورت مستقیم به رویداد MESSAGE متصل می‌شود.

این ساختار برای پروژه‌هایی که تعداد زیادی Handler دارند، می‌تواند مفید باشد.

۱۰. استفاده از توابع Sync و Async

یکی از ویژگی‌های جالب Pyrobale، پشتیبانی از هر دو نوع تابع همگام و ناهمگام است.

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

مثال:

@bot.on_message()
async def message_handler(message: Message):

    await message.reply("Hello!")

اما در Pyrobale می‌توان از تابع معمولی نیز استفاده کرد:

@bot.on_message()
def message_handler(message: Message):

    message.reply("Hello!")

کتابخانه از هر دو نوع Handler پشتیبانی می‌کند.

با این حال، برای پروژه‌هایی که عملیات ورودی و خروجی زیادی دارند، استفاده از ساختار Async معمولاً انتخاب مناسب‌تری است.

به‌خصوص زمانی که ربات باید هم‌زمان درخواست‌های متعددی را مدیریت کند.

۱۱. نکات مهم برای اجرای ربات در محیط عملیاتی

ساخت ربات تنها بخش اول پروژه است.

برای اینکه ربات بتواند به‌صورت پایدار فعالیت کند، باید به چند نکته مهم توجه داشته باشید.

۱. محافظت از توکن ربات

هرگز توکن ربات را در مخزن عمومی GitHub قرار ندهید.

بهتر است از متغیرهای محیطی استفاده کنید.

برای مثال:

import os

from pyrobale.client import Client

TOKEN = os.getenv("BOT_TOKEN")

if not TOKEN:
    raise RuntimeError("BOT_TOKEN is not configured")

bot = Client(TOKEN)

در محیط اجرا، متغیر BOT_TOKEN را با مقدار واقعی توکن تنظیم کنید.

۲. مدیریت خطاها

در پروژه‌های واقعی ممکن است ارتباط اینترنت قطع شود یا API پاسخ نامعتبر برگرداند.

بنابراین بهتر است عملیات حساس را با مدیریت خطا همراه کنید.

مثال:

@bot.on_message()
async def message_handler(message: Message):

    try:

        await message.reply(
            "درخواست شما با موفقیت دریافت شد."
        )

    except Exception as error:

        print(f"Error: {error}")

این مثال یک ساختار ابتدایی برای مدیریت خطاست. در پروژه عملیاتی بهتر است از سیستم Logging و مدیریت خطاهای اختصاصی کتابخانه نیز استفاده کنید.

۳. استفاده از Logging

برای بررسی عملکرد ربات، ثبت رویدادها اهمیت زیادی دارد.

می‌توانید از ماژول استاندارد Logging پایتون استفاده کنید:

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s"
)

logger = logging.getLogger(__name__)

logger.info("Bot started")
logger.warning("An unusual event occurred")
logger.error("An error occurred")

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

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

Pyrobale از Polling و Webhook پشتیبانی می‌کند.

در روش Polling، ربات به‌صورت دوره‌ای به سرور API مراجعه می‌کند تا به‌روزرسانی‌های جدید را دریافت کند.

در روش Webhook، سرور پیام‌رسان به آدرس مشخص‌شده در برنامه شما درخواست ارسال می‌کند.

هر روش مزایا و محدودیت‌های خودش را دارد:

انتخاب نهایی به معماری پروژه و امکانات API بستگی دارد.

۵. انتخاب زیرساخت مناسب

رباتی که تنها برای آزمایش ساخته شده، ممکن است روی سیستم شخصی اجرا شود.

اما اگر قرار است کاربران واقعی از آن استفاده کنند، به محیطی نیاز دارید که بتواند برنامه را به‌صورت مداوم اجرا کند.

در زمان انتخاب زیرساخت، موارد زیر را بررسی کنید:

• پشتیبانی از نسخه موردنیاز Python
• امکان نصب وابستگی‌های پروژه
• اجرای مداوم برنامه
• مدیریت متغیرهای محیطی
• دسترسی شبکه به API بله
• امکان مشاهده لاگ‌ها
• قابلیت راه‌اندازی مجدد برنامه پس از خطا

توجه: تله‌ران در معرفی عمومی خود به‌عنوان زیرساخت میزبانی و استقرار ربات‌های تلگرام معرفی شده است. از آنجا که Pyrobale برای بله طراحی شده، قبل از انتخاب تله‌ران برای میزبانی چنین رباتی باید پشتیبانی آن از ارتباط خروجی با API بله و امکان اجرای این نوع برنامه را بررسی کنید.

۱۲. آیا Pyrobale برای پروژه‌های بزرگ مناسب است؟

پاسخ این سؤال به نیازهای پروژه بستگی دارد.

برای ساخت ربات‌های ساده تا نسبتاً پیچیده، استفاده از یک Wrapper می‌تواند سرعت توسعه را افزایش دهد.

اما برای پروژه‌های بزرگ بهتر است معماری برنامه را به بخش‌های مختلف تقسیم کنید.

برای مثال:

my_bot/
│
├── main.py
│
├── handlers/
│   ├── messages.py
│   ├── commands.py
│   └── callbacks.py
│
├── services/
│   ├── database.py
│   └── user_service.py
│
├── config/
│   └── settings.py
│
└── requirements.txt

در این ساختار:

• main.py نقطه ورود برنامه است.
• پوشه handlers مسئول مدیریت رویدادها است.
• پوشه services شامل منطق اصلی برنامه است.
• پوشه config تنظیمات پروژه را نگهداری می‌کند.

این تفکیک باعث می‌شود توسعه و نگهداری پروژه در آینده ساده‌تر باشد.

همچنین بهتر است منطق کسب‌وکار برنامه را مستقیماً داخل Handlerها قرار ندهید.

۱۳. منابع و مستندات بیشتر

اگر قصد دارید توسعه ربات‌های بله را به‌صورت جدی دنبال کنید، پیشنهاد می‌کنم منابع زیر را بررسی کنید:

• مستندات رسمی Pyrobale
• مخزن GitHub پروژه
• صفحه Pyrobale در PyPI
• مستندات API ربات بله

این منابع برای آشنایی با متدها، کلاس‌ها، قابلیت‌های پیشرفته و تغییرات نسخه‌های مختلف مفید هستند.

جمع‌بندی

Pyrobale ابزاری کاربردی برای توسعه ربات‌های پیام‌رسان بله با زبان پایتون است.

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

در این مقاله یاد گرفتیم چگونه Pyrobale را نصب کنیم، اولین ربات خود را بسازیم، دستورات کاربران را مدیریت کنیم و دکمه‌های تعاملی ایجاد کنیم.

اگر قصد ورود به دنیای توسعه ربات‌های بله را دارید، Pyrobale می‌تواند نقطه شروع مناسبی برای آشنایی با این حوزه باشد.

پیشنهاد می‌کنیم ابتدا یک ربات ساده بسازید و سپس با اضافه کردن قابلیت‌هایی مانند اتصال به دیتابیس، مدیریت کاربران و پردازش درخواست‌ها، آن را به یک پروژه واقعی تبدیل کنید.