Base Cog Class

[Tobotimus]

This issue aims to provide information about why I plan on introducing a base cog class to Red. Some people have already noticed its inclusion in #2149, and rightly suspect it's a breaking change they will need to adjust for going forwards.

We've never really needed a base cog class up until now, because we tend to describe the settings and properties of particular cogs in a proxy-like style, rather than attach these settings and properties directly to the cog object. We haven't needed many settings pertaining to specific cogs, so this usage has served us fine. However, #2149 proposes using a different approach - modifying and retrieving properties of a cog during runtime through a direct API to the cog object, similar to how Command objects are used. In fact, the Permissions cog draws some new similarities between how we treat cogs and Command objects.

As always with significant structural changes like these, I imagine we will find many usages going forward for this base cog object which greatly simplify some problems, which would be otherwise quite complex to solve. It's an incredibly simple change for the cog creator to incorporate, whilst potentially adding lots of freedom for us developers to add new functionality to all cogs.

[Tobotimus]

Now, as for semantic details: the new base cog class will be located at redbot.core.commands.Cog; so incorporating this change won't even involve an extra import.

As a transitional measure, you can do this to prepare for the new base cog class:

BaseCog = getattr(commands, "Cog", object)

class MyCog(BaseCog):
    ...

You may call super().__init__() if you'd like, but if you don't, it will be done for you in bot.add_cog anyway (Disregard this sentence if you don't understand).

The following attributes as added in #2149 will be reserved for cogs, so please don't have any attributes or methods with these names, or things will break!

• requires
• all_commands
• allow_for
• deny_to
• clear_rule_for
• set_default_rule
• reevaluate_rules_for

[Redjumpman]

Other than making the permissions cog play better with cogs, what other benefits (either now or in the future) can cog creators expect from inheriting this base class?

[useruser3]

What other functions will the base class Have? One function I can see it having is allowing a master config file that can be used for many cogs and not tied to a specific one ?

[Tobotimus]

@Redjumpman @useruser3 I don't plan on polluting this class with methods and attributes or try to provide a plethora of functionality to it, however I'm sure in the future it will make solving complicated problems quite simple for us maintainers. Just look at how redbot.core.commands turned out - initially we only needed that for i18n on command help, but looking back, it's hard to know what we would have done without it.

For now, you get the all_commands property, which returns a dict mapping command names to commands which come from that cog 😃 I don't have any specific plans otherwise. There's a possibility that in the future it'll allow the use of check decorators like @checks.is_owner() on cogs to apply that check to every command from that cog.

[Tobotimus]

Closing now that the base cog class has been merged.