How to: Basic Project Configuration

Configuration

Minimal configuration:

[DiscordTokens]
bot = TOKEN

[bot]
alias = !
intents = 3

Full configuration

# Bot tokens that should be run
[DiscordTokens]
bot = TOKEN

# Global bot configuration
[Discord]
# Status description 
presence = Watching how the world burns
# Activity type: none, playing, listening, watching, streaming etc
presence_type = 2
# Status like online afk dnd offline etc
status = dnd
# default message-based command prefix
alias = :
# URL if presence type is streaming
url =
# Explicit API version
api_version =10

# token-specific configuration, has to be exactly same as key in DiscordTokens
[bot]
# Explicit intents, currently in order to work as intended, at least 3 is required (so guild's cache can be initialized)
intents = 3

# SQL Database configuration settings
[Database]
# PostgreSQL is recommended. Others weren't tested
db = postgresql+psycopg2
user = postgres
password = postgres
location = localhost

# Supabase's settings for API access (via /rpc)
[Supabase]
url = sub.domain.top
apikey = API_KEY
token = SUPABASE_TOKEN

# Redis configuration. Recommended for cooldowns & data cache
[redis]
host = localhost

# Influx 2 configuration so usage tracking can be activated
[influx2]
url = sub.domain.top
org = user@domain.top
token = INFLUX_TOKEN

Omit any configuration you don't want to use, eg, don't include [influx2] section at all if you want to have it disabled

Setting Up

Minimal project structure:

root |
     |   # Code files
     | - bot |
     |       |   # Anything in this directory will be loaded on startup
     |       | - commands.py
     |   # Localization files are stored here
     | - locale
     |   # Bot configuration file
     | - secrets.ini

• secrets.ini can be anywhere else as long as location is provided by --cfg=PATH_TO_CONFIG while launching
• bot same as above, as long as location is specified while launching
• locale is currently required even if not used (This requirement most likely will change)

Launching

python3.10 -m MFramework bot --log=INFO

• -m MFramework - indicates that Python should launch MFramework's __main__.py in current working directory
• bot - This indicates directory to with bot's code to load. Relative to current working directory. Can contain multiple directories as well: bot extra third_dir_to_load. Files in all directories will be loaded recursively.
• --log - This flag enables logging on MFramework, --log=INFO sets logging to only INFO or above

Command Overview

In MFramework, typehints as well as docstrings are important to set command details.

Permissions are currently hierarchy-based groups sourced from Database's role configuration

Example command:

@register(group=Groups.GLOBAL)
async def say(ctx: Context, text: str, repeat: int = 1) -> str:
    """
    Makes bot say things!
    Params
    ------
    text:
        Text to send as a bot
    repeat:
        Amount of times bot should repeat this message
    """
    for i in range(repeat):
        await ctx.reply(text)
    return f'Said "{text}" x {repeat}!'

Decorator to Register Command

@register is a decorator that marks function as a command, it accepts multiple keyword arguments to customize it's behaviour, most notably:

• group - Which lowest permission group should have access to this command.
• interaction - By default, all commands are slash-enabled, though particular function can be set to only message-based by setting this to False
• auto_defer - By default, all interactions are ACKnowledged automatically, however responding with a modal requires sending different response, thus if your function is Modal based, it's recommended to switch this to False (Note that you still have less than 3s to respond to Discord's interaction)
• guild - If it's a guild-only command, set ID of this guild here
• private_response - Whether response should be private

Context

ctx: Context

Context is command's context - command's message or interaction - it also provides unified way of interacting with both of them.

Typehints

: str, : int

Typehints are required in order to correctly set option type (for slash commands) and later on typecast in certain cases.

Docstrings

"""
Docstring
Params
------
parameter:
    Option docstring
"""

Docstrings are used as a command and option documentation within Discord client, ommiting them will result in MISSING DOCSTRING visibile while using slash command in Discord