Extension

How does extensions works?

Grace loads the extensions automatically at start. In start (bot/grace.py), the bot fetches all modules in the extensions package and pass them to the load_extensions method.

How to add an extension?

All extensions are located in the bot/extensions package. To add your own, simply create a new module in the extensions package.

Naming convention

• All names must respect the PEP8.

• The name of the module must be descriptive. Ex simple_calculator

• Cog names must end with cog. Ex. simple_calculator_cog

If your extension needs multiple modules, add your extension in a package named after your extension, without the _cog at the end, (ex. simple_calculator).

You can see a more concrete example of a cog module here.

Create a cog.

A cog is a simple python class that inherit from the commands.Cog class.

Naming convention

• The cog's class name must be the same as the module name. Ex. simple_calculator_cog and SimpleCalculatorCog

In order for the extension to be loaded, the extension needs a setup function at the end of the extension script.

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

Note that each extension should have only one cog and one setup function.

Extension guidelines

• A Cog must have it's own file.
• An extension must provide a collection of similar commands or functionalities. For example, a calculator extension shouldn't implement a command unrelated to a calculator.
• An extension must have a setup (only one) function or it won't be loaded by the bot.
• Commands must have an help and usage parameter.
• If your commands risk or have the same names as other command, create a command group.

Examples

A simple generic example of the structure of a cog.

extension_name_cog.py

from discord.ext.commands import Cog, hybrid_command
        

class ExtensionNameCog(Cog):
    def __init__(self, bot):
        self.bot = bot
        
    @hybrid_command(help='Explain what is this command', usage='How to use this command')
    async def my_command(self, ctx):
        # do something here


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

A more realistic example for a cog.

simple_calculator_cog.py

from discord.ext.commands import Cog, hybrid_command
        

class SimpleCalculatorCog(Cog):
    def __init__(self, bot):
        self.bot = bot
        
    @hybrid_command(help='Add two number together', usage='add <addend> <addend>')
    async def add(self, ctx, first_addend, second_addend):
        sum = first_addend + second_addend

        await ctx.send(f"{first_addend} + {second_addend} = {sum}")

    @hybrid_command(help='Subtract a number from the other', usage='subtract <minuend> <subtrahend>')
    async def subtract(self, ctx, minuend, subtrahend):
        difference = minuend - subtrahend

        await ctx.send(f"{minuend} - {subtrahend} = {difference}")

    @hybrid_command(help='Multiply a number by another one', usage='multiply <multiplicand> <multiplier>')
    async def multiply(self, ctx, multiplicand, multiplier):
        product = multiplicand * multiplier

        await ctx.send(f"{multiplicand} x {multiplier} = {product}")

    @hybrid_command(help='Divide a number by another one', usage='divide <dividend> <divisor>')
    async def divide(self, ctx, dividend, divisor):
        product = dividend / divisor

        await ctx.send(f"{dividend} ÷ {divisor} = {product}")


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