From d14f83a4bc174a9c706552ba9b674cc1d9895efb Mon Sep 17 00:00:00 2001 From: vcokltfre Date: Wed, 7 Apr 2021 03:28:05 +0100 Subject: add custom command checks tag --- bot/resources/tags/customchecks.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 bot/resources/tags/customchecks.md diff --git a/bot/resources/tags/customchecks.md b/bot/resources/tags/customchecks.md new file mode 100644 index 000000000..4f0d62c8d --- /dev/null +++ b/bot/resources/tags/customchecks.md @@ -0,0 +1,21 @@ +**Custom Command Checks in discord.py** + +You may find yourself in need of a decorator to do something that doesn't exist in discord.py by default, but fear not, you can make your own! Using discord.py you can use `discord.ext.commands.check` to create you own decorators like this: +```py +from discord.ext.commands import check, Context + +def in_channel(*channels): + async def predicate(ctx: Context): + return ctx.channel.id in channels + return check(predicate) +``` +There's a fair bit to break down here, so let's start with what we're trying to achieve with this decorator. As you can probably guess from the name it's locking a command to a list of channels. The inner function named `predicate` is used to perform the actual check on the command context. Here you can do anything that requires a `Context` object. This inner function should return `True` if the check is **successful** or `False` if the check **fails**. + +Here's how we might use our new decorator: +```py +@bot.command(name="ping") +@in_channel(728343273562701984) +async def ping(ctx: Context): + ... +``` +This would lock the `ping` command to only be used in the channel `728343273562701984`. -- cgit v1.2.3 From 029f4aaeb627326e2b34a1e88b8a3108f5565426 Mon Sep 17 00:00:00 2001 From: vcokltfre Date: Wed, 7 Apr 2021 03:40:04 +0100 Subject: update wording to emphasise checks not decorators --- bot/resources/tags/customchecks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/bot/resources/tags/customchecks.md b/bot/resources/tags/customchecks.md index 4f0d62c8d..b4eb90872 100644 --- a/bot/resources/tags/customchecks.md +++ b/bot/resources/tags/customchecks.md @@ -1,6 +1,6 @@ **Custom Command Checks in discord.py** -You may find yourself in need of a decorator to do something that doesn't exist in discord.py by default, but fear not, you can make your own! Using discord.py you can use `discord.ext.commands.check` to create you own decorators like this: +You may find yourself in need of a check decorator to do something that doesn't exist in discord.py by default, but fear not, you can make your own! Using discord.py you can use `discord.ext.commands.check` to create you own checks like this: ```py from discord.ext.commands import check, Context @@ -9,9 +9,9 @@ def in_channel(*channels): return ctx.channel.id in channels return check(predicate) ``` -There's a fair bit to break down here, so let's start with what we're trying to achieve with this decorator. As you can probably guess from the name it's locking a command to a list of channels. The inner function named `predicate` is used to perform the actual check on the command context. Here you can do anything that requires a `Context` object. This inner function should return `True` if the check is **successful** or `False` if the check **fails**. +There's a fair bit to break down here, so let's start with what we're trying to achieve with this check. As you can probably guess from the name it's locking a command to a list of channels. The inner function named `predicate` is used to perform the actual check on the command context. Here you can do anything that requires a `Context` object. This inner function should return `True` if the check is **successful** or `False` if the check **fails**. -Here's how we might use our new decorator: +Here's how we might use our new check: ```py @bot.command(name="ping") @in_channel(728343273562701984) -- cgit v1.2.3 From fddfc7610a1402afaae3b1f5084b0735fa75afcf Mon Sep 17 00:00:00 2001 From: vcokltfre Date: Wed, 7 Apr 2021 13:27:01 +0100 Subject: rename function to in_any_channel in accordance with d.py naming --- bot/resources/tags/customchecks.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/bot/resources/tags/customchecks.md b/bot/resources/tags/customchecks.md index b4eb90872..96f833430 100644 --- a/bot/resources/tags/customchecks.md +++ b/bot/resources/tags/customchecks.md @@ -4,18 +4,18 @@ You may find yourself in need of a check decorator to do something that doesn't ```py from discord.ext.commands import check, Context -def in_channel(*channels): +def in_any_channel(*channels): async def predicate(ctx: Context): return ctx.channel.id in channels return check(predicate) ``` -There's a fair bit to break down here, so let's start with what we're trying to achieve with this check. As you can probably guess from the name it's locking a command to a list of channels. The inner function named `predicate` is used to perform the actual check on the command context. Here you can do anything that requires a `Context` object. This inner function should return `True` if the check is **successful** or `False` if the check **fails**. +There's a fair bit to break down here, so let's start with what we're trying to achieve with this check. As you can probably guess from the name it's locking a command to a **list of channels**. The inner function named `predicate` is used to perform the actual check on the command context. Here you can do anything that requires a `Context` object. This inner function should return `True` if the check is **successful** or `False` if the check **fails**. Here's how we might use our new check: ```py @bot.command(name="ping") -@in_channel(728343273562701984) +@in_any_channel(728343273562701984) async def ping(ctx: Context): ... ``` -This would lock the `ping` command to only be used in the channel `728343273562701984`. +This would lock the `ping` command to only be used in the channel `728343273562701984`. If this check function fails it will raise a `CheckFailure` exception, which can be handled in your error handler. -- cgit v1.2.3 From 15aa872d6ff7de253e3383380013aa7e52bab6c0 Mon Sep 17 00:00:00 2001 From: vcokltfre Date: Thu, 15 Apr 2021 06:40:57 +0100 Subject: chore: update wording as requested --- bot/resources/tags/customchecks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/bot/resources/tags/customchecks.md b/bot/resources/tags/customchecks.md index 96f833430..23ff7a66f 100644 --- a/bot/resources/tags/customchecks.md +++ b/bot/resources/tags/customchecks.md @@ -1,6 +1,6 @@ **Custom Command Checks in discord.py** -You may find yourself in need of a check decorator to do something that doesn't exist in discord.py by default, but fear not, you can make your own! Using discord.py you can use `discord.ext.commands.check` to create you own checks like this: +Often you may find the need to use checks that don't exist by default in discord.py. Fortunately, discord.py provides `discord.ext.commands.check` which allows you to create you own checks like this: ```py from discord.ext.commands import check, Context @@ -9,9 +9,9 @@ def in_any_channel(*channels): return ctx.channel.id in channels return check(predicate) ``` -There's a fair bit to break down here, so let's start with what we're trying to achieve with this check. As you can probably guess from the name it's locking a command to a **list of channels**. The inner function named `predicate` is used to perform the actual check on the command context. Here you can do anything that requires a `Context` object. This inner function should return `True` if the check is **successful** or `False` if the check **fails**. +This check is to check whether the invoked command is in a given set of channels. The inner function, named `predicate` here, is used to perform the actual check on the command, and check logic should go in this function. It must be an async function, and always provides a single `commands.Context` argument which you can use to create check logic. This check function should return a boolean value indicating whether the check passed (return `True`) or failed (return `False`). -Here's how we might use our new check: +The check can now be used like any other commands check as a decorator of a command, such as this: ```py @bot.command(name="ping") @in_any_channel(728343273562701984) -- cgit v1.2.3