Cogs
What are cogs?⚓︎
Cogs are a way to organize your bot's code into modules. They are a way to keep your code clean and organized, and to prevent your main file from getting too big and messy.
Difference between Cogs and Extensions⚓︎
Cog is a class that inherits from commands.Cog
while extension is a Python module (file) that most of the time contains a Cog and is used to load them into your bot.
Loading extensions⚓︎
To load an extension, you use bot.load_extension()
method.
Note
The extension path is made almost the same like importing a module. If we had our extension under cogs/super_cog.py
we would use cogs.super_cog
as the extension path.
Unloading extensions⚓︎
To unload an extension, you use bot.unload_extension()
method.
Register command⚓︎
To register a command we use @commands.command()
decorator.
class SuperCog(commands.Cog):
@commands.command()
async def super_command(self, ctx: commands.Context):
...
Register event⚓︎
To register an event we use @commands.Cog.listener()
decorator.
class SuperCog(commands.Cog):
@commands.Cog.listener()
async def on_message(self, message: discord.Message):
...
Register task⚓︎
To register a task we use @tasks.loop()
decorator.
Example Extension⚓︎
from discord.ext import commands
class SuperCog(commands.Cog):
def __init__(self, bot):
self.bot = bot
@commands.command()
async def super_command(self, ctx: commands.Context):
...
@commands.Cog.listener()
async def on_message(self, message: discord.Message):
...
@tasks.loop(...)
async def super_task(self):
...
async def setup(bot):
await bot.add_cog(SuperCog(bot))
Lets break this down.
setup
function⚓︎
This function is used to load the extension into your bot. It is called by the bot when you load the extension.
Note
This function is required for the extension to work.
bot.add_cog
method⚓︎
This method is used to add the Cog to the bot.
SuperCog
class⚓︎
This is the Cog
class. It inherits from commands.Cog
and has a constructor that takes bot
as an argument. This allows you to access the bot instance within the Cog.
How to load extensions from a folder⚓︎
Lets say you have a folder called cogs
and you want to load all extensions from it.
We can use os
module to get all files from the folder and then load them.
@bot.event
async def setup_hook():
for file in os.listdir("cogs"):
if file.endswith(".py"):
await bot.load_extension(f"cogs.{file[:-3]}")
Note
file[:-3]
is used to remove .py
from the file name.
Managing extensions using commands⚓︎
Load extension⚓︎
@bot.command()
async def load(ctx: commands.Context, extension: str):
await bot.load_extension(f"cogs.{extension}")
await ctx.send(f"Loaded {extension}!")
Reload extension⚓︎
@bot.command()
async def reload(ctx: commands.Context, extension: str):
await bot.reload_extension(f"cogs.{extension}")
await ctx.send(f"Reloaded {extension}!")
Unload extension⚓︎
@bot.command()
async def unload(ctx: commands.Context, extension: str):
await bot.unload_extension(f"cogs.{extension}")
await ctx.send(f"Unloaded {extension}!")
Cog Groups⚓︎
GroupCog
is a Cog
subclass hence all Cog
methods are supported. Every command in the Cog will be registered as a subcommand of the group. You can set name of the group using group_name
metadata option.
class SuperCog(commands.GroupCog, group_name="utility"):
@commands.command()
async def ping(self, ctx: commands.Context):
...
Warning
Group Cogs only work with slash commands and hybrid commands. If you define a prefixed command inside it will be defined at root level hence command will be registered as ping
.
Advanced settings⚓︎
Extensions⚓︎
teardown
function⚓︎
This function is called when the extension is being unloaded. It is used to cleanup.
Cogs⚓︎
cog_load
method⚓︎
This method is called when the Cog is being loaded. It is used to start tasks and do other setup.
cog_unload
method⚓︎
This method is called when the Cog is being unloaded. It is used to cancel tasks and do other cleanup.
cog_check
method⚓︎
This method registers a check that will be used for all commands in the Cog. This method must take ctx
as an argument.
class SuperCog(commands.Cog):
async def cog_check(self, ctx: commands.Context):
return ctx.author.id == 1234567890
interaction_check
method⚓︎
This method registers a check that will be used for all interactions in the Cog. This method must take interaction
as an argument.
class SuperCog(commands.Cog):
async def interaction_check(self, interaction: discord.Interaction):
return interaction.user.id == 1234567890
cog_before_invoke
method⚓︎
This method registers a before invoke hook that will be used for all commands in the Cog. This method must take ctx
as an argument.
class SuperCog(commands.Cog):
async def cog_before_invoke(self, ctx: commands.Context):
print("Before invoke!")
cog_after_invoke
method⚓︎
This method registers a after invoke hook that will be used for all commands in the Cog. This method must take ctx
as an argument.
class SuperCog(commands.Cog):
async def cog_after_invoke(self, ctx: commands.Context):
print("After invoke!")
Cogs metadata⚓︎
name
attribute⚓︎
This attribute is used to set the name of the Cog. If not set, the name will be the class name.
Jishaku⚓︎
Jishaku is a debugging and testing cog for discord.py bots. It is a very useful tool for bot developers. Installation can be found on the following sites.