Skip to content
This repository has been archived by the owner on Sep 10, 2022. It is now read-only.

Core API

Jump to bottom
Aaron Graubert edited this page Nov 13, 2018 · 2 revisions

CoreBot (class)

This page contains documentation for the Beymax framework. If you're making a bot using the pre-made suites and looking for documentation of the various commands, you're in the wrong place. Checkout one of the sub-bots listed on the right

This is the center of the API. This class extends from discord.Client and adds several features, such as decorators for easily registering commands or background tasks, as well as utilities for message parsing when sending.

  • add_command(command, *spec, aliases=None, delimiter=None, empty=False, **kwargs)

    Decorator. Registers the given function as the handler for the specified command. Arguments:

    • command : The name of the command. Messages starting with this word (with the command prefix prepended) will run this function
    • *spec : (Optional) A variable number of Arg objects. These objects follow the argparse.add_argument syntax.
    • aliases : (Optional) List of other words to accept as the command.
    • delimiter : (Optional) A string to use to split individual arguments of the command, instead of whitespace
    • empty : (Optional) If true, the command will not accept any arguments (only the command word itself)
    • **kwargs : (Optional) A set of keyword arguments to pass on the the argument parser

    If at least one spec is provided, user messages will be passed through the argparse API and the third argument to the command function will be an argparse Namespace argument instead of a list of words in the message.

    Setting empty to True will also use the argparse API but require 0 arguments.

    The decorated function must be a coroutine (async def) and use one of the following call signatures: The first two arguments will be the bot object and the message object.

    • If empty is False and no spec is provided, the last argument will be a list of lowercase strings from splitting the message content by the delimiter
    • Otherwise, the last argument will be an argparse.Namespace object containing the arguments parsed from the message

    Note: The docstring of command functions is used as the command's help text.

  • add_task(interval)

    Decorator. Sets the decorated function to run on the specified interval. Arguments:

    • interval : The interval in which to run the function, in seconds

    The decorated function must be a coroutine (async def) and take only the bot object as an argument

  • add_special(checker)

    Decorator. Sets the decorated function to run whenever the given check function is True. Arguments:

    • check : A function which takes a message argument and returns True if the decorated function should be run

    The decorated function must be a coroutine (async def) and take the three following arguments:

    • The bot object
    • The message object
    • A list of lowercased, whitespace delimited strings

  • subscribe(event)

    Decorator. Sets the decorated function to be run whenever the given event is dispatched. Arguments:

    • event : A string argument name. WHen that argument is dispatched, the decorated function will run

    The decorated function must be a coroutine (async def). The function must take the event name as the first argument, and any additional arguments/keyword arguments are determined by the arguments to the dispatch() function

  • reserve_channel(name)

    Call to declare a channel reference. The bot configuration can then map this reference to an actual channel. By default all undefined references map to general Arguments:

    • name : A string channel reference to reserve

  • fetch_channel(name)

    Fetch the channel object for a given reference name. If the reference is undefined, it returns general Arguments:

    • name : A string channel reference to lookup

  • EnableAll(*bots)

    Enables all of the given Enable_ sub-bot suites. Arguments:

    • *bots : A set of functions which take the bot object. Each function should perform setup required to initialize a sub-bot, such as registering commands, tasks, and channel references

  • strip_prefix(command)

    Returns a string with the command prefix removed. Arguments:

    • command : A string to remove the command prefix from

  • dispatch(event, *args, manual=False, **kwargs)

    Manually dispatches an event (may be used to trigger tasks, commands, etc programatically). Arguments:

    • event : The string event name to dispatch
    • *args : Arguments to provide to the event handler
    • manual : (Optional) If True, do not attempt to dispatch before: and after: events
    • **kwargs : Keyword arguments to provide to the event handler

    By default, when dispatch is called:

    • Run any functions subscribed to before:{event}
    • Run any functions subscribed to the event in the base class (discord.Client)
    • Run any functions subscribed to the event
    • Run any functions subscribed to after:{event}

  • config_get(*keys, default=None)

    Retrieve a given key from the configuration. A multiple keys may be given to retrieve a nested value. Arguments:

    • *keys : List of nested keys to read from the configuration default : (Optional) The fallback value to return if the requested key path does not exist or is undefined. Defaults to None

  • trace(send=True)

    Coroutine. Prints a stack trace to the console, and optionally sends it to the registered bugs channel Arguments:

    • send : (Optional) If True (the default) post the stack trace to the bugs channel

  • shutdown()

    Coroutine. Use this function for a clean shutdown. Dispatches the 'cleanup' event, waits for all tasks to complete, then disconnects the bot

  • send_message(destination, content, *, delim='\n', quote='', interp=None, skip_debounce=False, **kwargs)

    Coroutine. Primary send-message function. Use to post a message to any channel. Arguments:

    • destination : A channel or User object to specify where to send the message
    • content : A string containing the message body to send Keyword Only arguments:
    • delim : String to use to break up the content if it is too large to send in one message. Defaults to newline
    • quote : String to use to quote the message content (prepend and append to content). Defaults to empty string
    • interp : Object to use to interpolate substitutions in the message content. Interp may be any of the following:
      • None : (Default) Build a default Interpolator object relative to the given destination to parse the message content
      • False : Disable interpolation. Message will be sent as-is
      • Interpolator instance : A premade Interpolator instance to use in addition to the default Interpolator for the channel. Substitutions from both Interpolators are used, but the user provided one takes priority when they both substitute a string
      • discord.Channel instance : Build a default Interpolator but for a channel other than the current destination
      • dict instance : Substitute each occurence of a key in the dictionary with the associated value
    • skip_debounce : If set to True, send the message immediately without debouncing. By default, messages are debounced for 500ms so that messages going to the same channel can be concatenated to avoid rapidly sending short messages
    • **kwargs : Additional keyword arguments to provide to the base class (discord.Client) send_message function.

    Setting quote or providing any kwargs will also disable message debouncing.

  • get_user(reference, *servers)

    Gets a user object given a form of reference. Optionaly provide a subset of servers to check Arguments:

    • reference : A string reference which can either be a user's id or a username to identify a user
    • *servers : A list of servers to check. By default, this function checks the primary_server, then all others

    Checks servers for a user based on id first, then username. Returns the first match

  • build_permissions_chain(user)

    Used to assemble the chain of permissions rules for the given user Arguments:

    • user : A user object

    Returns a list of permissions rules which apply to the given user, in order of highest to lowest priority

  • check_permissions_chain(user, chain=None)

    Used to check if a user has permissions to use underscore (administrator) commands. Arguments:

    • user : A user object to check for underscore permissions
    • chain : (Optional) a prebuilt permissions chain from build_permissions_chain. By default, the permissions chain is rebuilt
Clone this wiki locally