ruby.utils

from ruby.utils import (
    DEFAULT_STRINGS, get_config, get_string,
    success, error,
    require_guild, require_normal, get_role,
)

Config and strings

get_config(path=Path("config.yaml"), force=False) -> Config

Loads config.yaml the first time it's called, then returns the cached Config. Pass force=True to read the file again.

get_string(string, default="", config=None, default_table=DEFAULT_STRINGS) -> str

Looks up a message by key. config.strings is checked first, then default_table, and default is returned if neither has the key. See Strings.

get_string("NOT_OWNER")                                   # "You are not the owner of the bot!"
get_string("WAVE_DONE", default_table=DEFAULT_STRINGS)    # a cog's own table
get_string("MISSING_KEY", "fallback text")                # "fallback text"

DEFAULT_STRINGS: dict[str, str]

Ruby's built-in messages. Extend it for your cog with ruby.utils.DEFAULT_STRINGS | {...}. The keys are listed on the Strings page.

Replies

await success(ctx, message=None, silent_on_slash=False, default_table=DEFAULT_STRINGS)

await error(ctx, message=None, silent_on_slash=False, default_table=DEFAULT_STRINGS)

Tell the user that a command worked (✅, green) or didn't (❌, red).

Parameter
ctx	The command context.
message	A string key (looked up in default_table and the config) or plain text. None for just the emoji.
silent_on_slash	With no message, say nothing on slash commands instead of replying with the emoji.
default_table	The string table to look message up in.

What appears where is described in Errors and replies.

Checks

These reply with an error and return 1 if the check fails, or None if it passes:

if await require_guild(ctx):
    return

await require_guild(ctx) -> 1 | None

Fails with NO_SERVER outside a server.

await require_normal(ctx) -> 1 | None

Fails outside a server (NO_SERVER) and in threads, DMs and group DMs (UNSUPPORTED_CHANNEL).

await get_role(ctx, role_id) -> Role | 1 | None

Finds a role in the current server. It checks the cache first, then asks Discord.

• Role: found
• 1: not in a server (the user has already been told)
• None: no role with that ID