Skip to content

README-FA.md

Latest commit

 

History

History
163 lines (111 loc) · 8.43 KB

README-FA.md

File metadata and controls

163 lines (111 loc) · 8.43 KB

ربات تلگرام کدهاب (V2.0)

English | فارسی

یک رابط با تلگرام و کتابخانه python-telegram-bot که می‌توانید با آن، برنامه خود را پیست کنید، پیدا کنید و به اشتراک بذارید.

موارد لازم

موارد لازم requirements.txt:

  1. python-telegram-bot
  2. python-dotenv
  3. peewee

استفاده

  1. نیازمندی‌ها را نصب کنید:
pip install -r requirements.txt
  1. یک فایل .env (در کنار main.py) بسازید که محتوی آن به شکل زیر باشد:
TOKEN="..."
WEBHOOK="..."
مقدار TOKEN را برابر با توکن ربات خود قرار دهید. می‌توانید توکن را از @botfather دریافت کنید. اگر می‌خواهید از وبهوک استفاده کنید، مقدار WEBHOOK را برابر با آدرس مورد نظر قرار دهید. وگرنه، خالی بذارید (WEBHOOK="")
  1. و بلاخره...
python3 main.py
ممکن است که بخواهید از مواردی مانند tmux برای اجرای ربات استفاده کنید؛ مثلا هنگام استفاده از سرور.

توجه: این ربات از sqlite3 برای ذخیره داده‌های پیست‌ها، چت‌ها و کاربران استفاده می‌کند. اگر می‌خواهید از مواردی مانند MySQL یا PostgreSQL استفاده کنید، باید در src/model/__init__.py. تغییراتی ایجاد کنید. مستندات peewee را ببینید.

Contributing

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

  1. src/handler

    این پوشه، Handlerهای لازم را داراست. هر Hanlder یک پوشه ویژه خود به شکل src/handler/<NAME> داراست. Handler مورد نظر در src/handler/<NAME>/__init__.py تعریف خواهد شد. در این فایل، شما باید تابعی به شکل creator(model) تعریف کنید. پارامتر model، در واقع ایمپورت شده src/model می‌باشد. این تابع، با دریافت این پارامتر، دقیقا یک شی Handler برمی‌گرداند. شما می‌توانید هر تعداد پوشه حاوی Handlerهای مختلف بسازید.

    برای نمونه، فرض می‌کنیم که یک Handler برای دریافت /start می‌خواهید بنویسید. در این صورت، باید یک پوشه و یک فایل __init__.py درون آن بسازید؛ مانند src/handler/my_start_handler/__init__.py بسازید، سپس محتوی آن، برای مثال، می‌تواند به شکل زیر باشد

    from telegram.ext import CommandHandler, CallbackContext
    from telegram import Update

    def your_function(update: Update, context: CallbackContext):
        update.message.reply_text("hello!")

    def creator(model):
        return CommandHandler("start", your_function)
با این حال، شاید شما بخواهید که از یک ‌attributeای درون src/model مانند HELLO_TEXT استفاده کنید. پیشنهاد می‌کنیم که یک تابع برای پاس دادن مدل استفاده کنید. این تابع از قبل درون src/handler/functions.py نوشته شده است. پس، می‌توانید به این شکل از آن استفاده کنید: 

    from telegram.ext import CommandHandler, CallbackContext
    from telegram import Update
    from ..function import pass_model_to

    def your_function(update: Update, context: CallbackContext, model):
        update.message.reply_text(model.HELLO_TEXT)

    def creator(model):
        return CommandHandler("start", pass_model_to(your_function, model))
اگر شما توابع/کلاس‌هایی دارید که می‌خواهید از آن‌ها در Handlerهای متنوعی استفاده کنید، می‌توانید درون src/handler/functions.py بگذارید؛ سپس import کنید.

وقتی کار نوشتن Handler تمام شد، باید creator آن را در src/handler/__init__.py import کنید و به تاپل CREATORS اضافه کنید. بعنوان مثال، اگر می‌خواهید که Handler مورد بحث، یعنی my_start_handler را اضافه کنید؛ باید این خط را به src/handler/__init__.py اضافه کنید: 

from my_start_handler import creator as my_start_handler_creator

همانطور که می‌بینید، وقتی که Handlerای به نام <NAME> را می‌خواهیم اضافه کنیم، بهتر است creator آن، به شکل <NAME>_creator استفاده شود (from <NAME> import creator as <NAME>_creator). سپس، آنرا به تاپل CREATORS اضافه می‌کنیم.

برای نمونه، سه Handler زیر را تصور کنید:

  • handler1 (src/handler/handler1)
  • handler2 (src/handler/handler2)
  • handler3 (src/handler/handler3)

حال، در این مثال، اگر بخواهیم همه را بکار ببریم، باید src/handler/__init__.py را به شکل زیر بنویسیم:

from handler1 import creator as handler1_creator
from handler2 import creator as handler2_creator
from handler3 import creator as handler3_creator
# from your_new_handler import creaotr as your_new_hanlder_creator

CREATORS = (
    handler1_creator,
    handler2_creator,
    handler3_creator,
    # your_new_hanlder_creator,
)

# don't change it, don't remove it, don't see it, and don't think about it at all!
def get_handlers(model):
    for creator in CREATORES:
        yield creator(model)
*توجه: اگر Handler خود را به این شکل اضافه نکنید، Handler شما به dispatcher اضافه نخواهد شد. اگر دیدید که Handler شما کار نمی‌کند (با فرض اطمینان از نحوه کارکرد Handler خود و واکنشِ بدون ایرادِ ربات به سایر Handlerها)، احتمالا بخاطر این است که آن را اضافه نکردید!

  1. src/model

این بخش، هر داده‌ای در رابطه با زبان‌ها (فارسی، انگلیسی، ...)، database و ... را در بر می‌گیرد. در حال حاضر، همین دو مورد گفته شده در آن قرار دارد. این بخش، import شده و به creatorهای handlerها داده می‌شود (پارامتر model در creator(model)، یادته دیگه؟!). برای مثال، اگر EXAMPLE = 123 را در src/model/__init__.py تعریف کنید؛ می‌توانید از طریق پارامتر model، به شکل model.EXAMPLE از آن استفاده کنید.