Add chapter three on telebot library and update navigation in mkdocs
This commit is contained in:
@@ -51,4 +51,5 @@
|
||||
{"programming-languages-chapter2-1.md": {"created": "2026-05-06T10:36:46.397576+03:30"}}
|
||||
{"programming-languages-chapter2-2.md": {"created": "2026-05-06T10:36:46.397576+03:30"}}
|
||||
{"programming-languages-chapter2.md": {"created": "2026-05-06T10:36:46.397576+03:30"}}
|
||||
{"programming-languages-chapter3.md": {"created": "2026-05-06T10:52:56.641622+03:30"}}
|
||||
{"programming-languages.md": {"created": "2026-04-28T13:17:04.811052+03:30"}}
|
||||
|
||||
@@ -0,0 +1,327 @@
|
||||
# فصل سه: شروع کار با کتابخانهٔ telebot
|
||||
|
||||
در فصل قبل فهمیدیم رباتهای تلگرام و بله چطور با API کار میکنند. در این فصل میخواهیم یک قدم عملیتر برداریم و با کتابخانهٔ `telebot` در پایتون یک ربات ساده بسازیم.
|
||||
|
||||
نام اصلی پکیجی که نصب میکنیم `pyTelegramBotAPI` است، اما در کد با نام `telebot` از آن استفاده میکنیم.
|
||||
|
||||
## telebot چیست؟
|
||||
|
||||
`telebot` یک کتابخانهٔ پایتونی است که کار با Bot API را سادهتر میکند. بدون کتابخانه باید خودمان با `requests` درخواستهای HTTP بسازیم، آدرسها را بنویسیم و پاسخهای JSON را پردازش کنیم. اما با `telebot` میتوانیم سادهتر بنویسیم:
|
||||
|
||||
```python
|
||||
@bot.message_handler(commands=["start"])
|
||||
def start(message):
|
||||
bot.reply_to(message, "سلام!")
|
||||
```
|
||||
|
||||
یعنی به جای اینکه همهٔ جزئیات HTTP را خودمان مدیریت کنیم، بیشتر روی منطق ربات تمرکز میکنیم.
|
||||
|
||||
## نصب کتابخانه
|
||||
|
||||
برای نصب، بهتر است از محیط مجازی پایتون استفاده کنیم:
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install pyTelegramBotAPI
|
||||
```
|
||||
|
||||
در ویندوز فعالسازی محیط مجازی معمولاً این شکل است:
|
||||
|
||||
```bash
|
||||
.venv\Scripts\activate
|
||||
```
|
||||
|
||||
!!! warning "اشتباه رایج"
|
||||
پکیج درست `pyTelegramBotAPI` است. ممکن است پکیجهایی با نامهای شبیه `telebot` هم وجود داشته باشند، اما برای این درس همین پکیج را نصب میکنیم و در کد `import telebot` مینویسیم.
|
||||
|
||||
## گرفتن توکن ربات
|
||||
|
||||
برای شروع به یک توکن نیاز داریم. توکن مثل کلید ورود ربات است.
|
||||
|
||||
مراحل کلی:
|
||||
|
||||
1. در پیامرسان مورد نظر یک ربات یا بازو بسازید.
|
||||
2. توکن ربات را دریافت کنید.
|
||||
3. توکن را در کد یا بهتر از آن در متغیر محیطی قرار دهید.
|
||||
4. برنامهٔ ربات را اجرا کنید.
|
||||
|
||||
برای پروژهٔ واقعی، بهتر است توکن را مستقیم داخل کد ننویسیم. اما برای تمرینهای سادهٔ کلاسی، ممکن است اول کار توکن را موقتاً داخل کد بگذاریم تا مفهوم روشن شود.
|
||||
|
||||
## ساخت اولین ربات تلگرام
|
||||
|
||||
یک فایل به نام `bot.py` بسازید:
|
||||
|
||||
```python
|
||||
import telebot
|
||||
|
||||
TOKEN = "توکن ربات را اینجا قرار دهید"
|
||||
|
||||
bot = telebot.TeleBot(TOKEN)
|
||||
|
||||
|
||||
@bot.message_handler(commands=["start"])
|
||||
def start(message):
|
||||
bot.reply_to(message, "سلام! ربات شروع به کار کرد.")
|
||||
|
||||
|
||||
bot.infinity_polling()
|
||||
```
|
||||
|
||||
حالا برنامه را اجرا کنید:
|
||||
|
||||
```bash
|
||||
python bot.py
|
||||
```
|
||||
|
||||
تا وقتی برنامه در ترمینال باز است، ربات میتواند پیامها را دریافت کند. اگر برنامه را ببندید، ربات دیگر پاسخ نمیدهد.
|
||||
|
||||
## اگر بخواهیم از بله استفاده کنیم
|
||||
|
||||
کتابخانهٔ `telebot` در اصل برای Bot API تلگرام نوشته شده است. چون ساختار Bot API بله شبیه تلگرام است، میتوانیم آدرس API را تغییر بدهیم تا درخواستها به سرور بله ارسال شوند.
|
||||
|
||||
برای بله باید این خط را اضافه کنیم:
|
||||
|
||||
```python
|
||||
apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"
|
||||
```
|
||||
|
||||
این خط باید قبل از ساختن شیء `TeleBot` نوشته شود.
|
||||
|
||||
نمونهٔ ساده برای بله:
|
||||
|
||||
```python
|
||||
import telebot
|
||||
from telebot import apihelper
|
||||
|
||||
TOKEN = "توکن ربات بله را اینجا قرار دهید"
|
||||
|
||||
apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"
|
||||
|
||||
bot = telebot.TeleBot(TOKEN)
|
||||
|
||||
|
||||
@bot.message_handler(commands=["start"])
|
||||
def start(message):
|
||||
bot.reply_to(message, "سلام! ربات بله آماده است.")
|
||||
|
||||
|
||||
bot.infinity_polling()
|
||||
```
|
||||
|
||||
اگر از تلگرام استفاده میکنید، این خط را لازم ندارید:
|
||||
|
||||
```python
|
||||
apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"
|
||||
```
|
||||
|
||||
ولی اگر از بله استفاده میکنید، باید آن را فعال کنید.
|
||||
|
||||
## برنامهٔ بهتر با متغیر محیطی
|
||||
|
||||
نوشتن توکن داخل کد امن نیست. روش بهتر این است که توکن را از متغیر محیطی بخوانیم.
|
||||
|
||||
```python
|
||||
import os
|
||||
import telebot
|
||||
|
||||
TOKEN = os.getenv("BOT_TOKEN")
|
||||
|
||||
if not TOKEN:
|
||||
raise RuntimeError("متغیر BOT_TOKEN تنظیم نشده است.")
|
||||
|
||||
bot = telebot.TeleBot(TOKEN)
|
||||
|
||||
|
||||
@bot.message_handler(commands=["start"])
|
||||
def start(message):
|
||||
bot.reply_to(message, "سلام! ربات آماده است.")
|
||||
|
||||
|
||||
bot.infinity_polling()
|
||||
```
|
||||
|
||||
قبل از اجرا:
|
||||
|
||||
```bash
|
||||
export BOT_TOKEN="توکن ربات"
|
||||
python bot.py
|
||||
```
|
||||
|
||||
برای بله، نسخهٔ متغیر محیطی این شکل میشود:
|
||||
|
||||
```python
|
||||
import os
|
||||
import telebot
|
||||
from telebot import apihelper
|
||||
|
||||
TOKEN = os.getenv("BOT_TOKEN")
|
||||
|
||||
if not TOKEN:
|
||||
raise RuntimeError("متغیر BOT_TOKEN تنظیم نشده است.")
|
||||
|
||||
apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"
|
||||
|
||||
bot = telebot.TeleBot(TOKEN)
|
||||
|
||||
|
||||
@bot.message_handler(commands=["start"])
|
||||
def start(message):
|
||||
bot.reply_to(message, "سلام! ربات بله آماده است.")
|
||||
|
||||
|
||||
bot.infinity_polling()
|
||||
```
|
||||
|
||||
## handler چیست؟
|
||||
|
||||
در `telebot` هر تابعی که قرار است به یک نوع پیام جواب بدهد، یک handler است. بالای تابع از دکوراتور `@bot.message_handler` استفاده میکنیم تا مشخص کنیم این تابع چه پیامهایی را بررسی کند.
|
||||
|
||||
مثلاً این handler فقط دستور `/start` را بررسی میکند:
|
||||
|
||||
```python
|
||||
@bot.message_handler(commands=["start"])
|
||||
def start(message):
|
||||
bot.reply_to(message, "سلام!")
|
||||
```
|
||||
|
||||
این handler فقط دستور `/help` را بررسی میکند:
|
||||
|
||||
```python
|
||||
@bot.message_handler(commands=["help"])
|
||||
def help_message(message):
|
||||
bot.reply_to(message, "دستورهای ربات: /start و /help")
|
||||
```
|
||||
|
||||
## پاسخ دادن به پیام معمولی
|
||||
|
||||
اگر بخواهیم ربات به همهٔ پیامهای متنی جواب بدهد، میتوانیم از `content_types` استفاده کنیم:
|
||||
|
||||
```python
|
||||
@bot.message_handler(content_types=["text"])
|
||||
def echo(message):
|
||||
bot.reply_to(message, "پیام شما دریافت شد: " + message.text)
|
||||
```
|
||||
|
||||
این ربات هر متنی را که کاربر بفرستد، با یک جملهٔ ساده پاسخ میدهد.
|
||||
|
||||
## تفاوت reply_to و send_message
|
||||
|
||||
دو روش رایج برای پاسخ دادن:
|
||||
|
||||
```python
|
||||
bot.reply_to(message, "پاسخ به همان پیام")
|
||||
```
|
||||
|
||||
و:
|
||||
|
||||
```python
|
||||
bot.send_message(message.chat.id, "ارسال پیام به همین گفتگو")
|
||||
```
|
||||
|
||||
تفاوت ساده:
|
||||
|
||||
- `reply_to` پاسخ را به همان پیام کاربر وصل میکند.
|
||||
- `send_message` فقط یک پیام جدید در همان گفتگو میفرستد.
|
||||
|
||||
برای شروع، `reply_to` سادهتر است. وقتی با `chat.id` آشنا شدید، `send_message` هم خیلی کاربردی میشود.
|
||||
|
||||
## یک ربات کاملتر برای شروع
|
||||
|
||||
این نمونه چند دستور ابتدایی دارد:
|
||||
|
||||
```python
|
||||
import os
|
||||
import telebot
|
||||
|
||||
TOKEN = os.getenv("BOT_TOKEN")
|
||||
|
||||
if not TOKEN:
|
||||
raise RuntimeError("متغیر BOT_TOKEN تنظیم نشده است.")
|
||||
|
||||
bot = telebot.TeleBot(TOKEN)
|
||||
|
||||
|
||||
@bot.message_handler(commands=["start"])
|
||||
def start(message):
|
||||
bot.reply_to(message, "سلام! به ربات آموزشی خوش آمدی.")
|
||||
|
||||
|
||||
@bot.message_handler(commands=["help"])
|
||||
def help_message(message):
|
||||
text = "دستورهای ربات:\n/start شروع\n/help راهنما"
|
||||
bot.reply_to(message, text)
|
||||
|
||||
|
||||
@bot.message_handler(content_types=["text"])
|
||||
def answer_text(message):
|
||||
if message.text == "سلام":
|
||||
bot.reply_to(message, "سلام! خوش آمدی.")
|
||||
else:
|
||||
bot.reply_to(message, "پیام شما را گرفتم.")
|
||||
|
||||
|
||||
bot.infinity_polling()
|
||||
```
|
||||
|
||||
برای تبدیل همین نمونه به نسخهٔ بله، فقط کافی است `apihelper` را اضافه کنیم و آدرس API را قبل از ساختن `bot` تغییر بدهیم:
|
||||
|
||||
```python
|
||||
import os
|
||||
import telebot
|
||||
from telebot import apihelper
|
||||
|
||||
TOKEN = os.getenv("BOT_TOKEN")
|
||||
|
||||
if not TOKEN:
|
||||
raise RuntimeError("متغیر BOT_TOKEN تنظیم نشده است.")
|
||||
|
||||
apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"
|
||||
|
||||
bot = telebot.TeleBot(TOKEN)
|
||||
```
|
||||
|
||||
بقیهٔ handlerها معمولاً مثل قبل میمانند.
|
||||
|
||||
## اقدامات ابتدایی برای هر ربات
|
||||
|
||||
برای شروع هر ربات، این کارها را انجام دهید:
|
||||
|
||||
1. هدف ربات را خیلی ساده مشخص کنید. مثلاً «پاسخ به سلام» یا «نمایش راهنما».
|
||||
2. توکن ربات را بگیرید و آن را امن نگه دارید.
|
||||
3. کتابخانهٔ `pyTelegramBotAPI` را نصب کنید.
|
||||
4. یک فایل مثل `bot.py` بسازید.
|
||||
5. شیء `TeleBot` را با توکن بسازید.
|
||||
6. حداقل یک handler برای `/start` بنویسید.
|
||||
7. یک handler برای `/help` اضافه کنید.
|
||||
8. اگر لازم است به پیامهای عادی هم پاسخ بدهید.
|
||||
9. برنامه را با `bot.infinity_polling()` اجرا کنید.
|
||||
10. ربات را در پیامرسان تست کنید.
|
||||
|
||||
## خطاهای رایج
|
||||
|
||||
- نصب پکیج اشتباه به جای `pyTelegramBotAPI`
|
||||
- فراموش کردن `import telebot`
|
||||
- اشتباه نوشتن توکن
|
||||
- گذاشتن توکن داخل مخزن عمومی
|
||||
- اضافه نکردن `apihelper.API_URL` برای بله
|
||||
- نوشتن `apihelper.API_URL` بعد از ساختن `bot`
|
||||
- بستن ترمینال و انتظار پاسخگویی ربات
|
||||
|
||||
## تمرینهای کوتاه
|
||||
|
||||
1. رباتی بسازید که با دستور `/start` پیام خوشآمد نمایش دهد.
|
||||
2. دستور `/help` را اضافه کنید و دو دستور ربات را در آن توضیح دهید.
|
||||
3. کاری کنید اگر کاربر کلمهٔ `سلام` را فرستاد، ربات جواب `سلام، خوبی؟` بدهد.
|
||||
4. نسخهٔ بلهٔ کد را با اضافه کردن `apihelper.API_URL` آماده کنید.
|
||||
5. توضیح دهید چرا خط `apihelper.API_URL` باید قبل از `telebot.TeleBot(TOKEN)` نوشته شود.
|
||||
|
||||
## جمعبندی
|
||||
|
||||
کتابخانهٔ `telebot` کار ساخت ربات را ساده میکند. با چند خط کد میتوانیم دستورهای ساده مثل `/start` و `/help` را مدیریت کنیم و به پیامهای متنی پاسخ بدهیم. برای تلگرام از تنظیمات پیشفرض کتابخانه استفاده میکنیم، اما برای بله باید آدرس API را با `apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"` تغییر بدهیم.
|
||||
|
||||
## منابع برای مطالعهٔ بیشتر
|
||||
|
||||
- [مستندات pyTelegramBotAPI](https://pytba.readthedocs.io/en/latest/)
|
||||
- [صفحهٔ pyTelegramBotAPI در PyPI](https://pypi.org/project/pyTelegramBotAPI/)
|
||||
- [Telegram Bot API](https://core.telegram.org/bots/api)
|
||||
@@ -69,6 +69,7 @@ nav:
|
||||
- "معرفی فصل": programming-languages-chapter2.md
|
||||
- "زیرفصل ۲-۱: مفاهیم پایهٔ رباتها و API": programming-languages-chapter2-1.md
|
||||
- "زیرفصل ۲-۲: دریافت و ارسال پیام در تلگرام و بله": programming-languages-chapter2-2.md
|
||||
- "📚 فصل سه": programming-languages-chapter3.md
|
||||
- "شیوه ارزشیابی": grading.md
|
||||
|
||||
theme:
|
||||
|
||||
Reference in New Issue
Block a user