frank/README.md

Frank

Description

Playing around with creating a Discord bot is a fun pass-time, and a good way to learn a programming language. Sadly, however, discord.py can be a little hard to work with at times. That's when I got the idea to create Frank. The goal of Frank is to make creating Discord bots easier. It handles all the bot-related stuff in the background, so you can focus on writing the functionality of the bot itself, not how the bot works/interacts with Discord.

Frank works by dividing the bot into modules. Each module has its own prefix, commands, and daemons. Frank handles routing the Discord commands to their respective functions.

Installation

You can install the frank-discord package from PyPi:

pip install frank-discord

Example Module

In this section, I've written an example module for you, to understand the basic mechanics behind Frank.

import frank

class ExampleMod(frank.Module):
    PREFIX = 'examp'
    NAME = 'example'
    HELP = 'an example module'

This first part shows the three important variables in any module.

• PREFIX defines the string used to use the commands defined in this module. This means you can use the module as such inside your Discord server:

  fr examp [NAME_OF_COMMAND] [ARGS]
  

  With fr being the default prefix for Frank (can be overwritten). As you define more modules, they should all have a unique prefix. This is how Frank's modular system works, and any modules added to the list will automatically be picked up by Frank. The PREFIX value can also be list, allowing for multiple prefixes: for example a long, descriptive one, and a short, easy to type one (e.g. minecraft and mc).

    def pre_start(self):
        self.some_var = 'a value needed for working'

The pre_start function is where you define any variables which should be created before any daemons are started or commands are run. I don't recommend overwriting __init__, as this might break compatibility with future versions of Frank.

    @frank.command('command', help_str='a small description of the command')
    async def some_command(self, cmd, author, channel, mid):
        # do some stuff
        pass

    @frank.daemon()
    async def some_daemon(self):
        while True:
            # do some stuff
            pass

    @frank.default()
    async def default_cmd(self, author, channel, mid):
        # do some default action
        pass

These three decorators are the bread and butter of Frank. Let's break them down:

• frank.command defines a command. The first argument is its keyword, which will be used to execute the command. The help_str value is used in the help command, to show some information about the module. The syntax is the same as before:

  fr examp command [ARGS]
  

  This is how you can define as many Discord commands as you want, without needing to know how to parse the messages etc. Each command gets the author, channel, and id of the message. The cmd variable contains all the arguments passed to the command.
• frank.daemon defines a daemon, a process that should run in the background for as long as the bot is active. It should contain a while loop and preferably a sleep function using asyncio.sleep() (there are plans to improve this behavior). Because a daemon is just a method of the module class, it has access to all class variables, including those defined in pre_start.
• frank.default defines the command that should be run if the module is called without explicitly giving a command. For example, if you call fr examp without specifying a command, it will run the default command. This is useful for making a command that's used very often easier to execute.

In the end, all you need to do is add the following in your main script:

from frank import Frank
# Or whatever your package containing your modules is called
from modules import ExampleMod

if __name__ == '__main__':
    client = Frank([ExampleMod])
    client.run(YOUR_DISCORD_TOKEN)