Skip to content

Useful functions and information

Jump to bottom
Gerald Siegert edited this page Aug 22, 2021 · 10 revisions

Logging

For logging, you gan use the Python built-in logger, which logs all to command line and daily log files per default. If you want to use logging or debug outputs to discord, you can use the logging functions in the botutils.utils module to log data to admin, debug (bot admin) or mod channels:

  • write_XXX_channel(bot, message: Union[str, discord.Embed]): Writes the given message or embed directly to the channel.
  • log_to_XXX_channel_without_ctx(bot, **kwargs): Converts the given key-value-arguments into embed fields and writes it to the channel.
  • log_to_XXX_channel(context): Writes author name, timestamp, channel name and the message of the given command context as embed to the channel.

All data which will be sended using these functions will also be logged to command line and log file. The channel IDs will be setted in the geckarbot.json config file. Note that the message or embeds will be sended to the discord channels only if bot.DEBUG_MODE is False and the channel IDs are a valid ID for the server!

Exception handling

You can throw Exceptions on everytime you want. For the most Exception types provided by the discord.py framework the Geckarbot.on_command_error() event provides an exception handling. Other no command related exceptions are cought by the Geckarbot.on_error() event. If bot.DEBUG_MODE is True, every Exception will be sent to the parents events, which outputs the Exception on the command line only. Otherwise the User gets an short description of the error, if the Exception is one of the most frequently Exceptions. For unknown Exceptions additional information like the stack trace will be sent to the debug channel.

The handled Exceptions and their default output are:

  • discord.ext.commands.CommandNotFound: No output
  • discord.ext.commands.DisabledCommand: No output
  • discord.ext.commands.MissingRole: You don't have the required role for this command.
  • discord.ext.commands.MissingAnyRole: You don't have the required role for this command.
  • discord.ext.commands.NoPrivateMessage: Command can't be used in private messages.
  • discord.ext.commands.CheckFailure: Permission error.
  • discord.ext.commands.MissingRequiredArgument: Required argument missing: <argument>
  • discord.ext.commands.TooManyArguments: Too many arguments given.
  • discord.ext.commands.BadArgument: Argument don't have the required format: <argument>
  • discord.ext.commands.UserInputError: Argument error for argument: <argument>
  • botutils.permchecks.WrongChannel: Command can only be used in channel <channel>.
  • subsystems.ignoring.UserBlockedCommand: <User> has blocked the command <command>.
  • Any other Exception: Unknown error while executing command.

Some Exceptions already provides some informations like the given argument, user or channel. Based on Pythons Exception class, every Exception can hold a message. If a message is given or the Exception type has an argument user_message, this message will be displayed to the User instead of the default message.

General and misc information

Register discord.py events

Always use @commands.Cog.listener() in plugins to register event listener! If you use @bot.listen() it will cause trouble on managing plugins like on errors during loading a plugin. If you use @bot.event() it will overwrites the bot events which can cause problems that commands are prevented from being executed.

Reactions and Bot-blocking Users

If you want to add reactions to messages, don't use message.add_reaction(emoji). If someone blocks the Bot using Discords blocking feature it will raise an Exception and the further command execution won't be performed. To add reactions to messages use instead botutils.utils.add_reaction(message, emoji) which handles if a User blocks the Bot. In that case it won't add the reaction to the given message, it will post the reaction as a seperate message.

For other features like DMs the plugins which uses it have to handle by itself that nothing gets broken if someone blocks the bot!

Current embed limits

  • Embed titles are limited to 256 characters
  • Embed descriptions are limited to 2048 characters
  • There can be up to 25 fields
  • A field's name is limited to 256 characters and its value to 1024 characters
  • The footer text is limited to 2048 characters
  • The author name is limited to 256 characters
  • In addition, the sum of all characters in an embed structure must not exceed 6000 characters
  • A bot can have 1 embed per message

Mention and custom emoji format

  • User: <!@ID> or <@ID>
  • Channel: <#ID>
  • Roles: <@&ID>
  • Custom emojis: <:name:ID>
  • Animated custom emojis: <a:name:ID>

The emoji ID can also be get using !getemojiid <emoji> command from debugger plugin (in format :name:ID)

Howtos

Change version tag commit

  1. git push origin :refs/tags/TAGNAME deletes the remote tag
  2. git tag TAGNAME -f overwrites the local tag
  3. git push origin refs/tags/TAGNAME pushing the new tag
  4. Republish the GitHub release, which was resetted to draft

Create a Google service account

Short:

  1. Go to Googles Dev Console
  2. Create a project
  3. Activate Drive and Sheets API
  4. Go to credentials
  5. Create Service Account
  6. Download and save credential json file as config/google_service_account.json

Full: https://medium.com/@denisluiz/python-with-google-sheets-service-account-step-by-step-8f74c26ed28e

Clone this wiki locally