معرفی کتابخانه discord.py در پایتون

discord.py یک کتابخانهٔ قدرتمند و محبوب برای توسعه بات‌های دیسکورد با زبان پایتون است. این کتابخانه با استفاده از مدل async/await پایتون، ارتباط همزمان با API دیسکورد را ممکن می‌سازد و امکانات متنوعی مثل مدیریت رویدادها، سیستم دستورات (commands)، ارسال پیام‌های غنی (embeds)، کار با صدا و مدیریت نقش‌ها را فراهم می‌کند.

چرا discord.py؟

• سادگی و خوانایی کد با استفاده از asyncio
• پشتیبانی از ساختارهای حرفه‌ای مثل Cog برای ماژولار کردن بات
• مستندات و کامیونیتی قوی
• قابلیت گسترش و تعامل با API جدید دیسکورد

نصب و راه‌اندازی

برای نصب معمولاً از pip استفاده می‌شود. توجه کنید که نسخه‌های مختلفی وجود دارند و از سال‌های اخیر تنظیمات intents برای دسترسی به اطلاعات بیشتر لازم است.

pip install discord.py
# یا برای آخرین نسخه‌ای که از صدا پشتیبانی می‌کند:
pip install -U discord.py[voice]

این دستور پکیج اصلی را نصب می‌کند. همچنین بهتر است توکن را در متغیرهای محیطی قرار دهید و نه در کد.

مثال ساده: یک بات ابتدایی

import os
import discord
from discord.ext import commands

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(command_prefix="!", intents=intents)

@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}")

@bot.command()
async def ping(ctx):
    await ctx.send("Pong!")

bot.run(os.getenv("DISCORD_TOKEN"))

این کد یک بات پایه می‌سازد که هنگام راه‌اندازی پیام در ترمینال چاپ می‌کند و با فرمان !ping پاسخ Pong! می‌دهد. تنظیم intents.message_content = True برای دسترسی به محتوای پیام‌ها ضروری است و می‌بایست در پنل توسعه‌دهندهٔ دیسکورد نیز فعال شود.

توضیح Intents و مجوزها

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

ساختار Commands و Cog برای سازمان‌دهی

برای پروژه‌های بزرگ‌تر از discord.ext.commands و ساختار Cog استفاده کنید تا هر ماژول در فایل جدا قرار گیرد.

from discord.ext import commands

class Greetings(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

    @commands.command()
    async def hello(self, ctx):
        await ctx.send(f"Hello, {ctx.author.mention}!")

def setup(bot):
    bot.add_cog(Greetings(bot))

در این مثال یک Cog به نام Greetings تعریف شده که شامل یک فرمان hello است. در فایل اصلی بات از bot.load_extension("module_name") برای بارگذاری Cog استفاده می‌کنیم. این روش باعث خوانایی و نگهداری آسان‌تر کد می‌شود.

استفاده از Embed و ارسال فایل

from discord import Embed

@bot.command()
async def info(ctx):
    embed = Embed(title="اطلاعات بات", description="نمونه‌ای از embed", color=0x00ff00)
    embed.add_field(name="نسخه", value="1.0")
    await ctx.send(embed=embed)

Embedها به شما امکان می‌دهند پیام‌های زیباتر و ساختاربندی شده‌تری ارسال کنید. در مثال بالا یک embed ساده ساخته و به پیام پیوست شده است.

کارهای زمان‌بندی‌شده با tasks

from discord.ext import tasks

@tasks.loop(minutes=60)
async def hourly_task():
    channel = bot.get_channel(123456789012345678)
    if channel:
        await channel.send("پیام ساعتی")

@hourly_task.before_loop
async def before():
    await bot.wait_until_ready()

hourly_task.start()

این کد یک وظیفهٔ دوره‌ای ایجاد می‌کند که هر ۶۰ دقیقه اجرا شده و در کانال مشخص پیامی ارسال می‌کند. تابع before_loop تضمین می‌کند که بات قبل از شروع آماده باشد.

مدیریت خطا و رعایت Rate Limit

دیسکورد محدودیت‌هایی روی تعداد درخواست‌ها اعمال می‌کند؛ discord.py به صورت خودکار به اکثر rate limitها پاسخ می‌دهد اما شما هم باید از ارسال درخواست‌های پشت‌سرهم جلوگیری کنید.

@bot.event
async def on_command_error(ctx, error):
    if isinstance(error, commands.MissingRequiredArgument):
        await ctx.send("آرگومان‌های لازم را وارد کنید.")
    elif isinstance(error, commands.CommandOnCooldown):
        await ctx.send(f"فرمان در حال cooldown است. لطفا {round(error.retry_after,1)} ثانیه صبر کنید.")
    else:
        await ctx.send("خطایی رخ داده است.")

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

نکات امنیتی و عملکرد

• توکن را در متغیر محیطی نگه دارید و هرگز در گیت/عمومی آپلود نکنید.
• از نسخه‌های اختصاصی intents استفاده کنید؛ فقط آنچه لازم است فعال شود.
• از کدهای بلاک‌کننده (مثل خواندن فایل بزرگ بدون async) خودداری کنید یا آن‌ها را با اجرای در executor جدا کنید.
• برای فراخوانی API خارجی از کتابخانه‌های async مثل aiohttp استفاده کنید.

نکات پیشرفته و بهینه‌سازی

برای بات‌هایی با کاربران زیاد از caching مناسب و پایگاه دادهٔ سریع مثل Redis استفاده کنید. همچنین می‌توانید از sharding برای تقسیم ترافیک بین چند پردازش استفاده کنید. در محیط تولید از سرویس‌های مدیریت فرایند مثل systemd یا Docker استفاده کنید تا بات هنگام خطا به‌طور خودکار ریست شود.

جمع‌بندی

discord.py یک ابزار کامل برای ساخت بات‌های دیسکورد با پایتون است که از امکانات پایه تا پیشرفته را پوشش می‌دهد. با درک intents، سازمان‌دهی کد با Cog، مدیریت خطاها و توجه به رعایت امنیت و نرخ‌ها، می‌توانید بات‌های پایدار و حرفه‌ای بسازید. همواره مستندات رسمی و تغییرات API را دنبال کنید تا بات شما با بروزرسانی‌های دیسکورد سازگار بماند.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال