Quickstart¶
This page gives a brief introduction to the library. It assumes you have the library installed, if you don’t check the Installing portion.
A Minimal Bot¶
Let’s make a bot that responds to a specific message and walk you through it.
It looks something like this:
Let’s name this file example_bot.py . Make sure not to name it discord.py as that’ll conflict with the library.
There’s a lot going on here, so let’s walk you through it step by step.
The first line just imports the library, if this raises a ModuleNotFoundError or ImportError then head on over to Installing section to properly install.
Next, we create an instance of a Client . This client is our connection to Discord.
We then use the Client.event() decorator to register an event. This library has many events. Since this library is asynchronous, we do things in a “callback” style manner.
A callback is essentially a function that is called when something happens. In our case, the on_ready() event is called when the bot has finished logging in and setting things up and the on_message() event is called when the bot has received a message.
Since the on_message() event triggers for every message received, we have to make sure that we ignore messages from ourselves. We do this by checking if the Message.author is the same as the Client.user .
Afterwards, we check if the Message.content starts with ‘$hello’ . If it does, then we send a message in the channel it was used in with ‘Hello!’ . This is a basic way of handling commands, which can be later automated with the discord.ext.commands – Bot commands framework framework.
Finally, we run the bot with our login token. If you need help getting your token or creating a bot, look in the Creating a Bot Account section.
Now that we’ve made a bot, we have to run the bot. Luckily, this is simple since this is just a Python script, we can run it directly.
Создание Discord-бота на Python. Часть 1
Приветствую, хабровчане и другие пользователи интернета. Сегодня я начну цикл статей, посвящённых созданию Discord-бота с помощью библиотеки discord.py. Мы рассмотрим создание как и примитивного бота, как и "продвинутого" бота с модулями. В этой статье мы сделаем стандартную команду и ещё одну небольшую команду. Начнём!
Создание бота и получение токена
Для того, чтобы добавить бота на сервер нужно создать свое приложение и во вкладке General Information скопировать Client ID.
Здесь заменяем CLID на ранее скопированный Client ID.
Во вкладке Bot создаём бота и копируем токен.
Написание кода
Устанавливаем саму библиотеку.
Создаём файл config.py (так удобнее), и создаём там словарь.
Создаём main-файл, название может быть любое.
Импортируем библиотеки и наш файл конфига:
Создаём "тело" бота, название может быть любое:
Начинаем писать основной код.
В конце запускаем бота с помощью:
Должно получится так:
Бонусный туториал!
Сделаем вывод случайных картинок с лисами
Для этого импортируем еще пару библиотек:
Приступим к написанию команды.
Должно получится так:
Конец
На этом 1 часть закончена. Скоро будет опубликована 2 часть.
Name already in use
discord-py-guide / discord-py.md
- Go to file T
- Go to line L
- Copy path
- Copy permalink
- Open with Desktop
- View raw
- Copy raw contents Copy raw contents
Copy raw contents
Copy raw contents
Руководство по использованию библиотеки discord-py
Здесь вы можете почитать об основах, которые необходимо понимать, чтобы грамотно работать с библиотекой и не задавать вопросов, касающихся самых базовых вещей
Вероятнее всего у вас уже имеется созданный бот, поэтому инструкция по его созданию будет пропущена (но, возмжно появится позже).
Прежде чем начать.
Прежде чем приступать к работе с ботом, я сразу рекомендую зайти на страницу вашего бота и включить намерения ( intents , подробнее). Для этого зайдите в раздел приложений и выберите вашего бота. Затем, слева, на вкладке «Bot»
Включите параметры PRESENCE INTENT и SERVER MEMBERS INTENT
После этого выдайте намерения в коде при инициализации бота
Намерения нужны для работы с некоторыми событиями, объектами пользователей серверов ( участник / member ) и др. Они вам точно понадобятся, поэтому лучше включить их сразу, чтобы потом не спрашивать, почему вам не удается получить данные о пользователе сервера или чего-либо еще.
Начало работы с ботом и discord-py
Бот, которого вы создали на странице приложений, является аккаунтом дискорда, который по сути является таким же пользовательским аккаунтом, как и ваш, но с атрибутом bot и некоторыми ограничениями. Чтобы бот начал что-то делать, нужно создать его в коде и прописать логику.
Для начала рассмотрим виды ботов, которые предоставляет библиотека:
-
— фактически, самый базовый бот, на котором основаны другие. Умеет обрабатывать события по типу получения сообщений on_message() , установки реакции on_raw_reaction_add() и другие. — тот же discord.Client , только умеет находить в сообщениях и обрабатывать отдельные команды, которые начинаются с какого-либо префикса, например !test — про этого бота ничего сказать не могу, так как ни разу не использовал. Насколько мне известно, он нужен в тех случаях, когда вы планируете задать боту кучу разных комманд, событий и организовать все это в один отдельный класс.
В общем-то, выбор бота зависит напрямую от цели использования. Если вам нужен простой бот, который будет читать чат, фильтровать мат и т.п., считывать реакции, выдавать роли при входе нового пользователя и т.д., то вам хватит базового бота discord.Client .
Если помимо того, что я написал выше, вы хотите добавить еще и обработку команд по типу !ban <@User> , !play <Ссылка на видео с YouTube> , !погода и т.п., то использовать надо именно discord.ext.commands.Bot .
Теперь, когда вы определились с ботом можно наконец-то приступить к написанию кода.
Для начала подключим библиотеку.
На данном этапе я настоятельно рекомендую ознакомиться с руководством по использованию документации, так как на эту самую документацию я буду ссылаться очень часто и без ее использования вы вряд ли напишете что-то самостоятельно и будете постоянно спрашивать как реализовать ту или иную функцию.
В случае, если вы хотите использовать discord.ext.commands.Bot , я бы сразу отдельно подключил еще и этот пакет
Теперь создадим объект бота, который будет обрабатывать события и команды:
Из документации видим, что единственным обязательным аргументом при создании экземпляра класса является command_prefix .
Он принимает строку ( str ), по которой бот будет определять, то что сообщение является командой и обрабатывать его нужно именно как команду.
Помимо этого, выдадим боту намерения ( intents ), инструкция по настройке которых была в начале.
В качестве префикса команды укажем ! , намерения нужно выдавать именно те, которые вы будете использовать, но на первое время можно выдать все, то есть discord.Intents.all()
Если у вас discord.ext.commands.Bot :
Если у вас discord.Client , то префикс указывать не нужно (класс не принимает такого аргумента):
Основные обработчики событий
Теперь у нас есть объект bot , для которого нужно написать логику взаимодействия.
В качестве обработчиков событий используются асинхронные ( async ) функции ( def ), помеченные декоратором @bot.event , где bot — название объекта вашего бота. Функция должна иметь название, строго как в документации — иначе событие просто не будет обработано.
Если коротко, то все, что делает декоратор @bot.event — это помещает написанную вами функцию в другую функцию из библиотеки discord , которая, в свою очередь, передает вашей функции какие-либо параметры. Поэтому, если не пометить функцию декоратором, discord не обратит на нее внимание и она не будет вызвана.
async def on_ready()
Первым делом, нужно удостовериться, что бот успешно запустился и готов к работе. В списке событий находим событие on_ready() , которое вызывается один раз при запуске кода и обозначает то, что бот загрузился и готов к работе.
Здесь нужно отметить, что в этой функции не следует размещать фрагменты кода, которые должны будут выполняться в дальнейшем, так как функция будет вызвана только один раз. Поэтому в этой функции можно разместить какое-либо сообщение, о том, что бот запущен и, если есть работа с данными из файлов, то самое время их подгрузить. В общем, выполнить все единоразовые процедуры.
Выглядеть это будет вот так:
async def on_message(message)
Добавим обработчик сообщений, чтобы получать вызов функции каждый раз, когда bot получает сообщение в ЛС или на сервере.
В списке событий находим событие on_message(message) , которое принимает обязательный аргумент message . Этот аргумент имеет тип discord.Message из которого вы можете получить текст сообщения, а также объекты автора сообщения, сервер, канал, вложения, реакции, упоминания, ссылку на сообщение и много чего еще
Здесь вы можете прописать любую логику взаимодействия. Хоть даже удалять все только что переданные обработчиком сообщения (главное чтобы у бота были на то права). Самое главное — задать функции аргумент, который будет принимать объект сообщения. Вы можете назвать его как хотите, например даже так: async def on_message(собщение) , главное чтобы он был.
Если аргумент не указать, то при вызове события нового сообщения, discord-py отправит в функцию on_message() аргумент, содержащий объект сообщения, но получит ошибку о том, что указанная функция не принимает аргументов и ничего работать не будет. Это равноценно созданию функции, которая должна считать сумму 2 переданных в виде аргументов числа, но при этом она не принимает их.
По аналогии с примерами, приведенными выше, можно создать обработчик любого другого события, предствленного в discord-py . Главное, чтобы совпадало название и принимаемые аргументы.
Примеры других часто используемых событий:
on_raw_reaction_add(payload) , on_raw_reaction_remove(payload) — события добавления и удаления реакции с сообщения, соответствено. Из объекта payload вы можете получить сервер, сообщения и прочую инфу
on_member_join(member) , on_member_remove(member) — события подключения и выхода участника с сервера, в качестве аргумента принимает объект участника из которого можно получить всю информацию о пользователе.
Остальное вы можете найти в списке событий.
У вас уже есть объект бота и, вероятно, обработчики событий. Теперь бота нужно запустить.
При помощи токена, который нужно скопировать на странице бота, в разделе приложений вы можете авторизоваться в аккаунте бота.
Для этого у объекта bot нужно вызвать функцию run() :
Данная строка должна всегда находиться в самом низу кода. После ее выполнения бот будет запущен и весь код, который находится ниже этой строки будет выполнен только после завершения работы бота.
Бот будет выполнять работу до дех пор, пока вы не завершите выполнение кода. Это означает, что если вы закроете консольное окно программы, то бот перестанет работать и обрабатывать какие-либо события.
Чтобы бот работал без вашего участия, его можно поставить на хостинг — тогда он будет постоянно запущен на удаленном сервере, а не на вашем устройстве. Например, можно использовать бесплатный (уже не бесплатный) хостинг Heroku. В интернете есть куча разных туториалов по настройке. Возможно, когда-нибудь здесь появится ссылка на мой 🙂
В итоге должен получиться примерно такой код, посмотреть который можно здесь.
Данный бот выводит сообщение при успешном запуске, а также подробную информацию о каждом полученном сообщении.
Для этого примера достаточно было бы простого бота discord.Client , так как он обрабатывает только события. Но я наперед прописал в коде бота discord.ext.commands.Bot , так как дальше в этот код мы будем добавлять обработку команд.
Обработка отдельных команд
Данный раздел содержит информацию об устаревших в дискорде prefix-командах ( !command / >command / $command и т.п.). На данный момент актуально создавать именно slash-команды ( /command ), которые интегрируются в дискорд и позволяют более комфортно разделять аргументы и добавлять к ним описание.
Так или иначе, руководство по slash-командам подразумевает знание материала по работе с prefix-командами. Поэтому прежде чем переходить к slash-командам, я рекомендую ознакомиться с материалом ниже.
Напоминаю, что для работы с командами, в качестве бота нужно использовать объект discord.ext.commands.Bot , а не discord.Client ! Не забудьте также про префикс
Команды бота, как и обработчики событий, являются асинхронными функциями ( async def ).
Чтобы discord-py обнаружил команду в коде, функцию нужно пометить декоратором @bot.command() , где bot — название объекта вашего бота.
Скобки в декораторе @bot.command() обязательны, в отличии от @bot.event , так как декторатор discord.ext.commands.Command() принимает необязательные аргументы. Без скобок декоратор корректно работать не будет. *Подробнее про декораторы можно почитать выше
В отличии от обработчиков событий, функцию можно назвать как захочется — название функции станет названием команды.
Любая функция, являющаяся командой, должна принимать обязательный аргумент ctx (можно назвать как угодно). Аргумент является контекстом ( discord.ext.commands.Context ) выполнения команды, из которого можно получить сервер, автора, сообщение, канал и др. информацию. При вызове команды, Контекст в функцию передает библиотека discord-py .
Перед созданием первой команды
Для начала, если у вас в коде есть обработчик событий on_message() , его нужно немного доработать.
Из документации видим, что у объекта пользователя ( discord.User ) есть свойство bot , имеющее тип bool . Значит, если свойство имеет значение True — пользователь является ботом, иначе — не является)
Допишем условие, чтобы сообщения от любых ботов (включая нашего) игнорировались. Это часто делается для того, чтобы другие боты не могли спамить вызовами команд, обработка которых сначала проходит через on_message() , ведь любая команда в дискорде по сути является просто сообщением.
Для этого, кстати, в on_message() нужно добавить еще одну строку await bot.process_commands(message) , которую можно найти в списке методов объекта discord.ext.commands.Bot . Метод принимает в качестве аргумента сообщение с типом discord.Message и нужен для того, чтобы проверять, являестя ли сообщение командой. Многие, забыв добавить эту строку, потом не понимают, почему их бот игнорирует команды (подробный разбор проблемы)
Ключевое слово return завершает выполнение функции, то есть код, который идет дальше, так или иначе не будет выполнен.
Создание первой команды
Создадим команду с названием test , при вызове которой бот будет отвечать в чат «Успешный тест!»:
Результат:
Реализацию такой команды можно было бы сделать через обычного бота discord.Client прямо в on_message() , проверяя, наличие префикса и конкретного названия команды. Однако при большом количестве команд запихивать все в одну функцию не очень хорошо, да и не удобно разделять аргументы, про которые, кстати, можно почитать далее.
*Почитать подробнее, почему не стоит делать команды через on_message() можно здесь
Для создания нескольких названий одной команды можно передать в декоратор @bot.command() аргумент aliases , принимающий список ( list ) или кортеж ( tuple ) с названиями команды. При этом самого названия функции там быть не должно.
Работа с аргументами команды
Предположим, вам нужно при вызове функции принять от пользователя число , значение типа bool и участника сервера discord.Member
Чтобы принять эти параматры, нужно указать их в качестве аргументов функции, которая используется в качестве команды:
Поскольку Python — язык с динамической типизацией, по умолчанию все полученные значения принимают строковый тип str , так как фактически были получены из строки ( str ), содержащей текст сообщения.
Тогда
- number будет равно ’16’
- boolean будет равно ‘True’
- member будет равно ‘<@!239863351063144451>’
То есть из number нельзя будет вычесть число, boolean == True примет значение False , а member просто примет строку, содержащую форму упоминания пользователя.
Вместо того, чтобы вручную выполнять приведение типов ( number = int(number) , boolean = bool(boolean) и т.д.), можно сразу же явно указать тип аргумента функции:
И вот теперь уже все будет работать корректно. Помимо discord.Member можно указать любой другой тип библиотеки discord-py .
Из объекта member , например, можно получить id ( member.id ), ссылку на аватар ( member.avatar_url ) и другую информацию, которую можно найти в документации по объекту discord.Member .
Получить весь текст как один аргумент
В случае, когда вам в качестве аргумента нужен весь текст команды, можно использовать оператор * :
text будет иметь тип str и значение ‘это тестовый текст для проверки функции’
Если сделать так:
text будет иметь тип tuple и значение (‘это’, ‘тестовый’, ‘текст’, ‘для, ‘проверки’, ‘функции’)
Также можно сначала получить несколько отдельных слов, а уже потом оставшийся текст:
- first_word будет иметь тип str и значение ‘это’
- second_word будет иметь тип str и значение ‘тестовый’
- other_text будет иметь тип str и значение ‘текст для проверки функции’
Если смешать все команды из базового руководства в один код, то должно получиться что-то такое.
Данной информации должно хватить для понимания базовых вещей, таких как работа с документацией, создание prefix-команд, работа с обработчиками событий и т.д.
Creating a Discord Bot With Python
In this article, we’ll create a Discord bot using Python. The bot we’ll be creating today will have a simple purpose, telling jokes. We will give the bot a command and it will return a random joke. This should be simple enough, let’s get started!
Before Starting
I think it’ll be useful to understand what an API is before we actually get started. API stands for Application Programming Interface. Simply put, an API is what allows programs or services to communicate with other programs or services.
A great metaphor I came across (don’t remember the original source) was thinking of an API as a waiter at a restaurant.
So you, the customer, talk to a waiter to get your food. The waiter then talks to the chef who actually makes your food. The chef gives the food to the waiter. Finally, the waiter then gives the food to you.
Unpacking this metaphor, the user (customer) sends a request to an API (waiter). The API (waiter) then talks to the service you want to reach, usually a database (chef). That database (chef) then sends data (food) back to the API (waiter). And finally, the API (waiter) then gives you back data (food).
Great! Now that we know what an API is and have a general understanding of how it works, we can now move on to using one.
Acquiring the Jokes
To actually get the jokes, we’ll have to use the Official Joke API. This API is extremely easy to use, you just use this link and every time you call it, it will return a random joke in JSON format. Simple!
Creating a Discord Application
To create a Discord bot and invite it into your own Discord server, you can follow these steps here.
You can name it whatever you’d like but I’ll just name it “Jokes-Bot.”
Also, under the Settings tab to the left, go to “OAuth2” > “Scopes” and tick the bot option. Then in the same page, go to “Bot Permissions” and tick the Administrator box.
Now copy the link from the “Scopes” section and paste it onto your browser to add the bot to your Discord server.
Cool! Now just take a note of the Discord bot token in the “Bot” tab because we’ll be needing it later.
Downloading the Discord.py Library
We’ll be using the Discord.py library to create our Discord bot.
To install this library onto your machine you can follow these steps, or simply run the following command on the command line.
If you don’t already have Python and pip installed you can go here to install them.
Installing the Requests Module
Finally we need to download and install one more thing. To actually send requests and receive data from an API using Python we’ll need to download and install the python module Requests.
Simply type in the following command onto the command line to install this module.
Now it’s finally the time you’ve all been waiting for, the code.
Testing the Bot
To test that our bot actually works, copy and paste the following code into your favorite text editor.
To learn more about what this code does go here.
Now insert your Discord bot token into the last line where it says “your token here.” Save your python file as “discord_joke_bot.py” and then input the following command onto the terminal to run and test your bot.
If all went well you should see something like the following:
Now we can type the following command
into our Discord server and the bot should respond back with “Hello!”
Cool so the bot works.
Also, whenever we make changes to the bot, you’ll have to restart the python script by running it again.
Making API Requests With Python
Now let’s take a look at how to actually make API requests with Python and the Requests module.
The following code is what we’ll be using to make requests to the Joke API.
Let me explain what’s going on here.
On line 1 we import the Requests module.
Line 3 is the url we’ll be using and I just defined it in the global scope.
Now on line 6, I define a function named “check_valid_status_code” that will check if the status code from the API is successful or not.
If the status code is equal to 200, meaning it’s a successful call, it will return back the request in JSON format. If it’s unsuccessful, it will just return false.
Most of the time, whenever you make an API call, the API will return a status code. These status codes tell you whether an API call was successful or not. To learn more about status codes check out this article.
Now on line 13 I define another function named “get_joke.” This function, as implied by its name will get a joke.
First it makes a GET request to the url we pass it. Then it will call “check_valid_response_code” and store whatever it returns into a variable named “data.” Finally it returns the variable “data.”
Adding the $joke Command
We can finally move on to actually adding in our “$joke” command.
First let’s import “joke_api.py” into the “discord_joke_bot.py” file with the following line:
Now, in the file named “discord_joke_bot.py,” we can simply replace the if statement containing the “$hello” parameter on line 16 with the following if statement.
Let me explain what’s going on here.
So first on line 1, we check if the message we type into Discord starts with the “$joke” string.
Then on line 2 we call “get_joke” function from the “joke_api.py” file and save it into a variable named “joke.”
The variable “joke” stores a dictionary with the following keys: id, type, setup, and punchline.
The only dictionary keys we are interested in are “setup” and “punchline.”
Now on line 4 we check if the variable “joke” is “False.” If so we just return an error message.
Else, if it’s not false we return the joke setup with “joke[‘setup’]” adding a newline character, ‘\n’ and then adding the joke punchline with “joke[‘punchline’].”
Now if we test this in our Discord server with our bot we should receive a joke from our bot.