Бот для Discord API на Python (discord.py) с командами

Сегодня разберём создание бота для популярной соцсети Discord. Эта платформа предназначена для общения посредством голосовых чатов и сообщений и чем-то схожа с телеграмом.

Недавно я столкнулся с задачей написания подобного бота. Поскольку на просторах интернета, нет внятных гайдов, решил сделать свой. Про официальную документацию можно не говорить, там чёрт ногу сломит. В YouTube охватывают лишь самое начало. Я постараюсь более детально погрузиться в discord.py и работу с Discord API.

Структура проекта и установка библиотек

Что потребуется:

Компьютер или ноутбук
Редактор кода (Notepad++ тоже подойдет).
Python версии 3.9 и выше.
Соединение с интернетом

Установка для Windows:

pip install discord.py

Установка для MacOS:

pip3 install discord.py

Структура проекта

+---discord
|   +---cogs
|   |   +---everyone.py
|   |   +---logs.py
|   |   \---moder.py
|   +---config.py
|   \---main.py

Структура максимально простая, все модули для обработки команд будут храниться в директории cogs. Остальное можно структурировать как угодно.

Создание бота и получение токена

Заходим на этот сайт https://discord.com/developers/docs/intro и нажимаем на "applications". После проходим авторизацию (видео инструкция тут).

Создаем новое приложение:

Дальше переходим во вкладку Bot и создаем бота. Тут вы сможет создать и скопировать токен:

После всех манипуляций выбираем уровень доступа для бота - administrator.

Как добавить бота на сервер

Переходим во вкладку OAuth2 General, ставим такие настройки и сохраняем:

Потом переходим в URL General, выбираем те же самые настройки и копируем ссылку ниже:

Переходим по ссылке и выбираем на какой сервер хотим добавить бота. Добавлять можно только на тот сервер, который вы администрируете (у вас есть права администратора на нем). Дальше следуем иструкциям Discord.

Разработка бота

Main.py

Импорты:

import asyncio
import os
import discord
from discord.ext import commands
import config

Подробнее остановимся на commands и config.

В commands будет инициализироваться и храниться бот. В дальнейшем через этот объект класса будем обращаться к методам.

Анонсы всех видео, статей и полезностей - в нашем Telegram-канале🔥
Присоединяйтесь, обсуждайте и автоматизируйте!

Config – там будут храниться все глобальные переменные - токены, ID каналов, ID ролей и т д.

discord_intents = discord.Intents.all()
discord_intents.members = True

discord_intents – мы наделяем бота полными правами доступа (когда будем добавлять его, то он запросит разрешение для управления)

bot – тут собирается бот. Аргументы: command_prefix - на какой спец символ будет откликаться бот; intents - права доступа.

discord_intents = discord.Intents.all()
discord_intents.members = True

bot = commands.Bot(command_prefix=config.prefix, intents=discord_intents)
bot.remove_command("help")

@bot.event

@commands.has_any_role(*config.admin_id_role)
async def on_ready():
    await bot.change_presence(status=discord.Status.idle, activity=discord.Game(config.prefix+"info"))
    await bot.wait_until_ready()

@bot.command()
@commands.has_any_role(*config.admin_id_role)
async def load(ctx, extension):
    bot.load_extension(f"cogs.{extension}")
    print(f"load module: cogs.{extension}")

@bot.command()
@commands.has_any_role(*config.admin_id_role)
async def unload(ctx, extension):
    bot.unload_extension(f"cogs.{extension}")
    print(f"unload module: cogs.{extension}")

@bot.command()
@commands.has_any_role(*config.admin_id_role)
async def reload(ctx, extension):
    bot.unload_extension(f"cogs.{extension}")
    bot.load_extension(f"cogs.{extension}")
    print(f"reload module: cogs.{extension}")

async def load_extensions():
    for filename in os.listdir("./cogs"):
        if filename.endswith(".py"):
            await bot.load_extension(f"cogs.{filename[:-3]}")


async def main():
    print('zit goot')
    await load_extensions()
    await bot.start(config.token)

if __name__ == "__main__":
    # bot.run(config.token)
    asyncio.run(main())

Пробежимся по функциям.

On_ready – срабатывает при загрузке бота. bot.change_presence - тут мы устанавливаем активность (Discord может показывать во что вы сейчас играете).

Дальше подгружаются все винтики. Почему пакеты в Discord называют винтики? Потому что в официальной документации разработчики назвали именно так;)

Load и unload - позволяют отключить и подключить винтики. Загрузка происходит с помощью обращения к методам объекта бота.

Reload - по сути вызывает по очереди unload и load.

Цикл for перебирает все файлы и загружает их в первый раз.

Ну и в конце мы запускаем бота, передавая в него токен.

Config.py

token = '12345'

prefix = '!'
recurring_guild_id = 1234

admin_id_role = '938435735701311538'

id_mute_role = '938437343751319613'
id_user_role = '938437452920672327'

Этот файл будет хранить в себе только служебные переменные - токены, ID ролей, ID серверов.

Директория cogs

Everyone.py

import discord
import time
import config
from discord.ext import commands


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

   @commands.Cog.listener()
   async def on_ready(self):
      print('everyone is ready')

   @commands.command()
   async def info(self, ctx):
      embed = discord.Embed(title=f">>     Команды     <<",  color=0x9370DB)
      embed.set_author(name=f"{ctx.author}", icon_url=f"{ctx.author.avatar_url}")

      embed.add_field(name=f"***{config.prefix}mute*** --- отключить возможность говорить и писать человеку", value=f"Пример: {config.prefix}mute @1234", inline=False)
      embed.add_field(name=f"***{config.prefix}unmute*** --- вернуть все возможности человку", value=f"Пример: {config.prefix}unmute @1234", inline=False)
      embed.add_field(name=f"***{config.prefix}ban*** --- добавить человека в черный список и выгнать", value=f"Пример: {config.prefix}ban @1234", inline=False)
      embed.add_field(name=f"***{config.prefix}unban*** --- убрать человека из чероного списка", value=f"Пример: {config.prefix}unban @1234", inline=False)
      embed.add_field(name=f"***{config.prefix}kick*** --- выгрнать человека", value=f"Пример: {config.prefix}kick @1234", inline=False)
      embed.add_field(name=f"***{config.prefix}clear*** --- удалить последние сообщения", value=f"Пример: {config.prefix}clear 40", inline=False)

      embed.set_footer(text=f"BOT • {time.asctime()}")
      await ctx.channel.purge(limit=1)
      await ctx.send(embed=embed)


async def setup(bot):
   await bot.add_cog(Everyone(bot))

В этом файле будут храниться все команды доступные обычному пользователю. Импорты отдельно разбирать не буду, там и так все понятно.

Вероятно, вы спросите что это за класс. Everyone наследуется от commands.Cog. Винтики работают за счёт объектов - когда мы запускаем бота, то перебираем все объекты и собираем всё вместе.

Для отслеживания команд мы используем декоратор commands.command(). Для корректной работы при создании класса мы передаём в него нашего бота. Дальше описываем в методах логику.

Функция info будет высылать пользователю embed (сообщение) с указанием доступных команд. Внутрь функции передаем ctx (полное его название context) - это полученное сообщение.

Мы создаем объект, в который передаем: заголовок, свет линии с краю, подпись автора и ссылку на изображение. Дальше, обращаясь к методу add_field, добавляем строки с именем и значением - можно их назвать заголовок и текст.

Метод set_footer добавляет маленькую подпись в конце сообщения. В завершение мы обращаемся к await ctx.channel.purge(limit=1), что удаляет одно сообщение (можно указать любое количество в limit). Await позволяет нам дождаться окончания асинхронного метода.

После этого отправляем сообщение с помощью await ctx.send(embed=embed), передавая внутрь сформированное сообщение. Или можно просто отправить текст await ctx.send(text=”your message”).

Эта конструкция нужна библиотеке, что бы она могла увидеть и загрузить винтик:

async def setup(bot):
   await bot.add_cog(Everyone(bot))

Удобный конструктор embed, который сразу выдает python код, находится тут.

Moder.py

import discord
import time
from discord.ext import commands
import config


class Moder(commands.Cog):

    def __init__(self, bot):
        self.bot = bot

    @commands.Cog.listener()
    async def on_ready(self):
        print('moder is ready')

    @commands.command()
    @commands.has_any_role(config.admin_id_role)
    async def mute(self, ctx, user: discord.Member, reason=None):

        channel = self.bot.get_channel(config.log_mes_channel_id)
        guild = self.bot.get_guild(config.recurring_guild_id)
        role = guild.get_role(config.id_mute_role)

        embed = discord.Embed(title=f"Пользователя {user} заглушили", color=0xfac400)
        embed.set_author(name=f"{ctx.author}", icon_url=f"{ctx.author.avatar_url}")
        embed.add_field(name="Причина:", value=f"{reason}", inline=True)
        embed.set_footer(text=f"BOT • {time.asctime()}")

        await user.add_roles(role)

        await channel.send(embed=embed)
        await ctx.channel.purge(limit=1)
        await ctx.send(embed=embed, delete_after=30)


    @commands.command()
    @commands.has_any_role(config.admin_id_role)
    async def unmute(self, ctx, user: discord.Member):

        channel = self.bot.get_channel(config.log_mes_channel_id)
        guild = self.bot.get_guild(config.recurring_guild_id)
        role = guild.get_role(config.id_mute_role)

        embed = discord.Embed(title=f"Пользователя {user} разглушили", color=0xfac400)
        embed.set_author(name=f"{ctx.author}", icon_url=f"{ctx.author.avatar_url}")
        embed.set_footer(text=f"BOT • {time.asctime()}")

        await user.remove_roles(role)

        await channel.send(embed=embed)
        await ctx.channel.purge(limit=1)
        await ctx.send(embed=embed, delete_after=30)


    @commands.command()
    @commands.has_any_role(config.admin_id_role)
    async def ban(self, ctx, user: discord.Member, *, reason=None):

        channel = self.bot.get_channel(config.log_mes_channel_id)

        embed = discord.Embed(title=f"Пользователя {user} забанили", color=0xfac400)
        embed.set_author(name=f"{ctx.author}", icon_url=f"{ctx.author.avatar_url}")
        embed.add_field(name="Причина:", value=f"{reason}", inline=True)
        embed.set_footer(text=f"BOT • {time.asctime()}")

        await channel.send(embed=embed)
        await user.ban(reason=reason)
        await ctx.channel.purge(limit=1)
        await ctx.send(embed=embed, delete_after=30)


    @commands.command()
    @commands.has_any_role(config.admin_id_role)
    async def unban(self, ctx, *, member):

        banned_users = await ctx.guild.bans()
        channel = self.bot.get_channel(config.log_mes_channel_id)

        member_name, member_discriminator = member.split("#")
        for ban_entry in banned_users:
            user = ban_entry.user

            if (user.name, user.discriminator) == (member_name, member_discriminator):
                await ctx.guild.unban(user)
                embed = discord.Embed(title=f"Пользователя {user} разбанили", color=0xfac400)
                embed.set_author(name=f"{ctx.author}", icon_url=f"{ctx.author.avatar_url}")
                embed.set_footer(text=f"Silence. • {time.asctime()}")
                await channel.send(embed=embed)
                await ctx.channel.purge(limit=1)
                await ctx.send(embed=embed, delete_after=30)
                return


    @commands.command()
    @commands.has_any_role(config.admin_id_role)
    async def kick(self, ctx, user: discord.Member, *, reason=""):

        channel = self.bot.get_channel(config.log_mes_channel_id)

        embed = discord.Embed(title=f"Пользователя {user} выгнали из сервера", color=0xfac400)
        embed.set_author(name=f"{ctx.author}", icon_url=f"{ctx.author.avatar_url}")
        embed.add_field(name="Причина:", value=f"{reason}", inline=True)
        embed.set_footer(text=f"BOT • {time.asctime()}")

        await channel.send(embed=embed)
        await ctx.channel.purge(limit=1)
        await ctx.send(embed=embed, delete_after=30)
        await user.kick()



    @commands.command()
    @commands.has_any_role(config.admin_id_role)
    async def clear(self, ctx, amount=20):

        channel = self.bot.get_channel(config.log_mes_channel_id)
        if amount < 200:

            embed = discord.Embed(title=f"Очистил чат \"{ctx.channel}\" на {amount} сообщений(ия)", color=0xfac400)
            embed.set_author(name=f"{ctx.author}", icon_url=f"{ctx.author.avatar_url}")
            embed.set_footer(text=f"BOT • {time.asctime()}")

            await ctx.channel.purge(limit=int(amount))
            await channel.send(embed=embed)
            await ctx.send(embed=discord.Embed(description=f":wheelchair: удалено {amount} сообщений(я)"), delete_after=30)
        else:
            await ctx.send(embed=discord.Embed(description=f":Вы не можете удалить больше 200 сообщений"), delete_after=30)


async def setup(bot):
    await bot.add_cog(Moder(bot))

Пройдёмся по функциям сверху вниз.

@commands.has_any_role(config.admin_id_role) - это новый декоратор, он проверяет есть ли у пользователя роль (нужен ID роли). Также можно указывать перечень ролей в массиве (для этого распаковывайте массив).

Mute принимает в себя само сообщение, пользователя (пример @user), и причину. Первым делом мы заготавливаем объект чата, в который будем присылать действия администратора. Потом сам сервер (в документации discord.py сервер называется гильдия). И в конце получаем роль, которую будем давать пользователю.

Когда всё готово, собираем сообщение-уведомление (не забывайте пользоваться конструктором embed тут). Дальше к объекту пользователя добавляем роль. И отправляем сообщение в логи и в чат, откуда пришла команда. Не забываем удалять отправленную команду.

Unmute зеркальна с функций mute, только для пользователя мы используем метод remove role.

Ban - выгоняет пользователя с сервера и добавляет его в черный список (в дальнейшем его не смогут пригласить на сервер пока он в ЧС).

Для работы в переменных нам потребуется только канал для системы логов. Следом проходим процедуру сборки красивого сообщения и отправляем его как в mute.

Unban - не просто зеркальная функция, потому что тут нам потребуется обращаться к списку ЧС. banned_users делает запрос к ЧС сервера. Дальше мы делаем полный перебор всех заблокированных и сравниваем с нашим пользователем. Как только находим его, убираем юзера из списка и выводим сообщение о разблокировке.

Kick - с этой функций дела обстоят намного проще, так как у пользователя есть метод для изгнания user.kick.

Clear - последняя возможность для администрирования. В нее поступает не только сообщение, но и количество сообщений, которое нужно удалить. Дальше идет защита от опечатки.

ctx.channel.purge(limit=int(amount)) отвечает за удаление сообщений, в limit передаем полученное значение.

Заключение

Библиотека discord.py не проста в понимании и требует много времени на разбор. Но лучших аналогов для Python не найти из-за обширности API.

Если захотите разобраться глубже, самостоятельно изучайте новые методы и классы. Производите глубокий анализ, что откуда исходит (какой вы получаете объект в ответе и как его можно получить еще).

Для дальнейшего развития советую попытаться добавить в бота интеграцию с базой данных. Например есть хорошая БД MongoDB - на ней можно простроить мощную многоуровневую систему администрирования сервера.