Config¶

Config was introduced in V3 as a way to make data storage easier and safer for all developers regardless of skill level. It will take some getting used to as the syntax is entirely different from what Red has used before, but we believe Config will be extremely beneficial to both cog developers and end users in the long run.

Basic Usage¶

from core import Config

class MyCog:
    def __init__(self):
        self.config = Config.get_conf(self, identifier=1234567890)

        self.config.register_global(
            foo=True
        )

    @commands.command()
    async def return_some_data(self, ctx):
        await ctx.send(config.foo())

API Reference¶

Important

Before we begin with the nitty gritty API Reference, you should know that there are tons of working code examples inside the bot itself! Simply take a peek inside of the tests/core/test_config.py file for examples of using Config in all kinds of ways.

Config¶

class core.Config¶

You should always use get_conf() or get_core_conf() to initialize a Config object.

Important

Most config data should be accessed through its respective group method (e.g. guild()) however the process for accessing global data is a bit different. There is no global method because global data is accessed by normal attribute access:

conf.foo()

cog_name¶: The name of the cog that has requested a Config object.

unique_identifier¶: Unique identifier provided to differentiate cog data when name conflicts occur.

spawner¶: A callable object that returns some driver that implements drivers.red_base.BaseDriver.

force_registration¶: A boolean that determines if Config should throw an error if a cog attempts to access an attribute which has not been previously registered.

Note

You should use this. By enabling force registration you give Config the ability to alert you instantly if you’ve made a typo when attempting to access data.

classmethod get_conf(cog_instance, identifier[, force_registration=False])¶

All cogs should use this classmethod to get a config instance.

Parameters:	cog_instance – The `self` arg inside of your cog’s `__init__` function. identifier (int) – A random sequence of integers you provide to keep your cog’s data safe in case of naming conflicts. This number should never change. force_registration (Optional[bool]) – See `force_registration`

classmethod get_core_conf(identifier[, force_registration=False])¶

All core modules that require a config instance should use this classmethod instead of get_conf()

Parameters:	identifier (int) – See `get_conf()` force_registration (Optional[bool]) – See `force_registration`

register_global(**kwargs)¶

Registers default values for attributes you wish to store in Config at a global level.

You can register a single value or multiple values:

conf.register_global(
    foo=True
)

conf.register_global(
    bar=False,
    baz=None
)

You can also now register nested values:

defaults = {
    "foo": {
        "bar": True,
        "baz": False
    }
}

# Will register `foo.bar` == True and `foo.baz` == False
conf.register_global(
    **defaults
)

You can do the same thing without a defaults dict by using double underscore as a variable name separator:

# This is equivalent to the previous example
conf.register_global(
    foo__bar=True,
    foo__baz=False
)

register_guild(**kwargs)¶: Registers default values on a per-guild level. See register_global() for more details.

register_channel(**kwargs)¶: Registers default values on a per-channel level. See register_global() for more details.

register_role(**kwargs)¶: Registers default values on a per-role level. See register_global() for more details.

register_member(**kwargs)¶: Registers default values on a per-member level. See register_global() for more details.

register_user(**kwargs)¶: Registers default values on a per-user (independent of guild) level. See register_global() for more details.

guild(guild)¶

Returns a Group for the given guild.

Parameters:	guild (discord.Guild) – A discord.py guild object.

channel(channel)¶

Returns a Group for the given channel. This does not currently support differences between text and voice channels.

Parameters:	channel (discord.TextChannel) – A discord.py text channel object.

role(role)¶

Returns a Group for the given role.

Parameters:	role (discord.Role) – A discord.py role object.

member(member)¶

Returns a MemberGroup for the given member.

Parameters:	member (discord.Member) – A discord.py member object.

user(user)¶

Returns a Group for the given user.

Parameters:	user (discord.User) – A discord.py user object.

class core.config.Group¶

A “group” of data, inherits from Value which means that all of the attributes and methods available in Value are also available when working with a Group object.

defaults¶: A dictionary of registered default values for this Group.

force_registration¶: See Config.force_registration.

__getattr__(item)¶

Takes in the next accessible item.

If it’s found to be a group of data we return another Group object.

If it’s found to be a data value we return a Value object.

If it is not found and force_registration is True then we raise AttributeError.

Otherwise return a Value object.

Parameters:	item (str) – The name of the item a cog is attempting to access through normal Python attribute access.

is_group(item)¶

A helper method for __getattr__(). Most developers will have no need to use this.

Parameters:	item (str) – See `__getattr__()`.

is_value(item)¶

A helper method for __getattr__(). Most developers will have no need to use this.

Parameters:	item (str) – See `__getattr__()`.

get_attr(item)¶

This is available to use as an alternative to using normal Python attribute access. It is required if you find a need for dynamic attribute access.

Note

Use of this method should be avoided wherever possible.

A possible use case:

@commands.command()
async def some_command(self, ctx, item: str):
    user = ctx.author

    # Where the value of item is the name of the data field in Config
    await ctx.send(self.conf.user(user).get_attr(item))

Parameters:	item (str) – The name of the data field in `Config`.

coroutine set_attr(item, value)¶: Please see get_attr() for more information.

Note

Use of this method should be avoided wherever possible.

all()¶

This method allows you to get “all” of a particular group of data. It will return the dictionary of all data for a particular Guild/Channel/Role/User/Member etc.

Return type:	dict

all_from_kind()¶

This method allows you to get all data from all entries in a given Kind. It will return a dictionary of Kind ID’s -> data.

Return type:	dict

coroutine clear()¶: Wipes all data from the given Guild/Channel/Role/Member/User. If used on a global group, it will wipe all global data.

coroutine clear_all()¶: Wipes all data from all Guilds/Channels/Roles/Members/Users. If used on a global group, this method wipes all data from everything.

class core.config.MemberGroup¶

A specific group class for use with member data only. Inherits from Group. In this group data is stored as GUILD_ID -> MEMBER_ID -> data.

all_guilds()¶

Returns a dict of MEMBER_ID -> data.

Return type:	dict

class core.config.Value¶

A singular “value” of data.

identifiers¶: This attribute provides all the keys necessary to get a specific data element from a json document.

default¶: The default value for the data element that identifiers points at.

spawner¶: A reference to Config.spawner.

__call__([default=None])¶

Each Value object is created by the __getattr__ method of a Group object and the data of the Value object is accessed by this method. It is a replacement for a get() method.

For example:

foo = conf.guild(some_guild).foo()

# Is equivalent to this

group_obj = conf.guild(some_guild)
value_obj = conf.foo
foo = value_obj()

Parameters:	default (Optional[object]) – This argument acts as an override for the registered default provided by `default`. This argument is ignored if its value is `None`.

coroutine set(value)¶

Sets the value of the data element indicate by identifiers.

For example:

# Sets global value "foo" to False
await conf.foo.set(False)

# Sets guild specific value of "bar" to True
await conf.guild(some_guild).bar.set(True)

Drivers¶

class core.config.drivers.red_base.BaseDriver¶