Checking Commands
In this lesson, you’ll learn how to use the Check
object. A Check
is a predicate that is evaluated before a Command
is executed to ensure that the Context
surrounding the Command
invocation is valid.
In an earlier example, you did something similar to verify that the user who sent a message that the bot handles was not the bot user itself. The commands
extension provides a cleaner and more usable mechanism for performing this kind of check, namely using Check
objects.
00:00
This is part 13, where you will learn about the Check
object. First things first, what is the Check
object? A Check
is a predicate that is evaluated before a Command
is executed, to ensure that the Context
surrounding the Command
invocation is valid.
00:16
That’s a bit of a mouthful, but believe it or not, you did that yourself earlier, or at least something similar, anyway. Just here, when you checked for the message.author
to be different to the client.user
.
00:29
The commands
extension provides a cleaner and more usable mechanism for performing this kind of check, namely using Check
objects. To demonstrate how this works, assume you want to support a command !create-channel <channel name>
that creates a new channel. However, you only want administrators to be allowed the ability to create new channels using this command. Firstly, you will need to create a new member role in the admin.
00:58 Go into the Discord guild and select the {Server Name} → Server Settings menu. Then, select Roles from the left-hand navigation list. If you’re unsure how to get to the Server Settings menu, you can right-click on the Server Settings icon, and it will come up.
01:16 Finally, select the + sign next to ROLES,
01:29 and select Save Changes.
01:33
Now, you’ve created an admin role that you can assign to particular users. Next, you’ll update bot.py
to check the user’s role before allowing them to initiate the command. Now that it’s been updated, in bot.py
, you have a new Command
function called create_channel()
. Before delving into the create_channel()
function, please be sure that you have included the import discord
segment at the top of your bot.py
file.
02:01
The create_channel()
function takes an optional channel_name
and creates that channel. create_channel()
is also decorated with a Check
called has_role()
.
02:12
You also use discord.utils.get()
to ensure that you don’t create a channel with the same name as an existing channel. If you run this program as it is and attempt to use the !create-channel
command in your Discord channel, then you will see an error message.
02:31
This CheckFailure
says that has_role('admin')
failed. You can see here, it says raise MissingRole
and Role 'admin' is required to run this command.
Unfortunately, this error only prints to stdout
.
02:46
It would be even better if this was reported to the user in the Discord channel. To do so, you can add the following event. This event handles an error event from the command and sends an informative error message back to the original Context
of the invoked Command
.
03:03 Try it all again, and you should see an error in the Discord channel.
03:11
“You do not have the correct role for this command.” That event is now working. Now, to resolve the issue, you will need to give yourself the admin role. With the admin role, your user will pass the Check
, and will be able to create channels using the command.
03:26 Please note that in order to assign a role, your user will have to have the right permissions. The easiest way to make sure that this happens is to sign in with the username you used to create the guild. In order to give yourself, or anyone, a role that happens to be in the guild, you can right-click on their username, go to Roles, and check the box.
03:48
This time around, when the !create_channel
command is used—and let’s add a name this time, not very creative—you can see that #test has been created up here.
04:06
As you can see, you can pass pretty much whatever you want as the optional channel_name
. Keep in mind, though, that if you have a space like I accidentally did here,
04:18 it will only pick up the first word as the channel name.
04:22
With this most recent example, you combined a Command
, an event, a Check
, and even the get()
utility to create a useful Discord bot. Well done on getting this far.
04:34 Join me in the next and final video, where everything you have learnt will be summarized.
Become a Member to join the conversation.