Canary

Canary is a Python3 bot designed for the McGill University Community Discord Server. The bot provides helper functions to users, as well as fun functions, a quote database and custom greeting messages.

Build Statuses

Installation

1. If you wish to use the update command to update to the latest version of the bot, configure your GitHub account in your environment of choice and clone into the repository with:

   git clone https://github.com/idoneam/Canary

2. Dependencies are managed with poetry (1.8.3+), which can be installed via pip with:

   python3 -m pip install poetry

3. Dependencies may be installed using poetry with the following command:

   poetry install --no-dev

4. Use of the LaTeX equation functionality requires a working LaTeX installation (at the very minimum, latex and dvipng must be present). The easiest way to do this is to install TeX Live (usually possible through your distro's package manager, or through TeX Live's own facilities for the latest version). See the TeX Live site for more information.

5. Development dependencies (YAPF and pytest) can be installed alongside all other dependencies with:

   poetry install

6. You may enter the virtual environment generated by the Poetry installation with: poetry shell or simply run the bot with poetry run canary

7. In order to run bots on Discord, you need to create a bot account.

8. In the Discord Developer Portal, you must enable the "Presence" and "Server Members" Privileged Gateway Intents (In the Bot tab of your application)

You must set certain values in the config.ini file, in particular your Discord bot token (which you get in the previous link) and the values in the [Server] section.

Click here to see descriptions for a few of those values

(For values that use Discord IDs, see this to know how to find them)

• [Discord]
  • Key: Your Discord bot token.
• [Server]
  • ServerID: Your server ID.
  • CommandPrefix: What a message should begin with to be considered a command.
  • BotName: The name of your bot.
• [Emoji]
  • UpvoteEmoji: The name of your upvote emoji (for the score function).
  • DownvoteEmoji: The name of your downvote emoji.
  • BannerVoteEmoji: The name of the emoji that is used to vote on Banner of the Week Contests.
• [Roles]
  • ModeratorRole: The name of the role that your moderators have (for functions like DMing users).
  • DeveloperRole: The name of the role that your developers have (for functions like restarting the bot). This could be the same role as moderator.
  • McgillianRole: The name of the role that verified McGillians have.
  • HonoraryMcGillianRole: The name of the role that Honorary McGillians (verified Non-McGillians) have.
  • BannerRemindersRole: The name of the role that is pinged when a Banner of the Week Contest starts.
  • BannerWinnerRole: The name of the role that is given to users that win a Banner of the Week Contest.
  • TrashTierBannerRole: The name of the role that is given to users that are banned from submitting in Banner of the Week Contests.
  • NoFoodSpottingRole: The name of the role assigned to abusers of the foodspotting command that will prevent them from using it.
  • MutedRole: (Optional) The name of the role used to mute users and create an appeal channel for them. (The role presumably also removes some permissions; exact role implementation is up to the server's administrators.)
  • SecretCrabbo: The name of the role for users that wish to be pinged for secret crabbo celebrations.
• [Channels]
  • ReceptionChannel: The name of the channel that will receive messages sent to the bot through the answer command (and where messages sent by mods to users with the dm command will be logged)
  • BannerOfTheWeekChannel: The name of the channel where winning submissions for Banner of the Week Contests are sent.
  • BannerSubmissionsChannel: The name of the channel where submissions for Banner of the Week Contests are sent. This is where users vote.
  • BannerConvertedChannel: The name of the channel where the converted submissions for Banner of the Week Contests are sent. This is where the bot will fetch the winning banner.
  • FoodSpottingChannel: The name of the channel where foodspotting posts are sent.
  • MetroStatusChannel: The name of the channel where metro status alerts are sent.
  • BotsChannel: The name of the channel for bot spamming.
  • VerificationChannel: The name of the channel where verification pictures are sent.
  • AppealsLogChannel: The name of the channel where messages sent in individual appeal channels are logged.
  • AppealsCategory: The name of the channel category where individual appeal channels are created.
• [Meta]
  • Repository: The HTTPS remote for this repository, used by the update command as the remote when pulling.
• [Logging]
  • LogLevel: See this for a list of levels. Logs from exceptions and commands like mix and bac are at the info level. Logging messages from the level selected and from more severe levels will be sent to your logging file. For example, setting the level to info also sends logs from warning, error and critical, but not from debug.
  • LogFile: The file where the logging output will be sent (will be created there by the bot if it doesn't exist). Note that all logs are sent there, including those destined for devs and those destined for mods.
  • DevLogWebhookID: Optional. If the ID of a webhook is input (and it's token below), logs destined for devs will also be sent to it. These values are contained in the discord webhook url: discordapp.com/api/webhooks/WEBHOOK_ID/WEBHOOK_TOKEN
  • DevLogWebhookToken: Optional. See above.
  • ModLogWebhookID: Optional. If the ID of a webhook is input (and it's token below), logs destined for mods will also be sent to it. See the URL above to see how to find those values.
  • ModLogWebhookToken: Optional. See above.
• [DB]
  • Schema: Location of the Schema file that creates tables in the database (This file already exists, so you shouldn't have to change this unless you rename it or change its location).
  • Path: Your database file path (will be created there by the bot if it doesn't exist).
• [Helpers]
  • CourseTemplate: McGill course schedule URL. Changes every school year.
  • CourseSearchTemplate: McGill course search URL. Changes every school year.
  • GCWeatherURL: Government of Canada weather URL. Region-specific.
  • GCWeatherAlertURL: Government of Canada weather alerts URL. Region-specific.
  • WttrINTemplate: http://wttr.in/ URL template. Region-specific.
  • TepidURL: TEPID screensaver endpoint for printer status.
• [Subscribers]
  • FoodRecallChannel: Channel where you want CFIA recall notices posted.
  • FoodRecallLocationFilter: Regions you want to receive CFIA recall notices for.
  • FoodSpottingChannel: Channel where you want foodspotting posts to be sent, ideally in a dedicated channel.
  • NoFoodSpottingRole: Name of role assigned to abusers of the foodspotting command that will prevent them from using it.
  • MetroStatusChannel: Channel where you want metro status alerts to be sent, ideally in a dedicated channel with opt-in read permissions for users.
• [Currency]
  • Name: The name of the bot currency.
  • Symbol: The currency's symbol (e.g. $).
  • Precision: How many decimal digits after the decimal point are "official" for the currency.
  • Initial: How much currency is given out by the initial_claim command.
  • SalaryBase: Currently unused.
  • Inflation: Currently unused.
• [IncomeTax]: Currently unused.
• [AssetTax]: Currently unused.
• [OtherTax]: Currently unused.
• [Betting]:
  • RollCases: Intervals for bet_roll. For example, a value of 66, 90, 99, 100 gives the intervals [1, 66], [67, 90], [91, 99], and [100].
  • RollReturns: The multiplier return for each interval. For example, a value of 0, 2, 4, 10 with the intervals described above gives a 0x return for random <= 66, a 2x return for 66 < random <= 90, a 4x return for 90 < random <= 99, and a 10x return for random == 100.
• [Images]
  • MaxImageSize: Maximum image size to allow to be sent without compression, in bytes.
  • ImageHistoryLimit: Maximum amount of messages to check in history for an image before giving up.
  • MaxRadius: Maximum radius used for various image transformation functions.
  • MaxIterations: Maximum iterations allowed for various image transformation functions.
• [Games]:
  • HangmanNormalWin: Value of normal hangman win.
  • HangmanCoolWin: Value of cool hangman win.
  • HangmanTimeOut: Time before a hangman game will time out if not interacted with.
• [AssignableRoles]:
  • Pronouns: Comma separated list of pronoun roles in server.
  • Fields: Comma separated list of field of study roles in server.
  • Faculties: Comma separated list of faculty roles in server.
  • Years: Comma separated list of year roles in server.
  • Generics: Comma separated list of generic or meme roles in server.

Testing functions

If you installed all dev dependencies, you can run tests with poetry run pytest.

Running the bot

Run poetry run canary in your shell. Ensure that your Discord token is set in the config.ini file within the canary/config directory.

Docker Container

A Docker Container is provided for easier development.

Building the Image

Freeze requirements to a requirements.txt

poetry export -f requirements.txt > requirements.txt

From within the root of the repository:

docker build -t canary:latest .

Running the Container

You will need to set environment variables according to the values configured in the Pydantic configuration object described in config.py. These environment variables correspond to the properties of the object, uppercased, underscore-spaced, and prefixed with CANARY_.

A bare minimum set of environment variables to set can be found in example.env. These variables must be set inside the container in order for the bot to function.

From within the root of the repository:

# Make a folder (if needed) to store database, pickles, etc.
mkdir -f runtime-data

# Run the container
docker run -d \
  --env-file my.env \
  -v $(pwd)/runtime-data:/app/data/runtime \
  canary:latest

Optionally provide the -d flag to run the container in detached state.

Code Linting

We format our code using PSF's black. Our builds will reject code that do not conform to the standards defined in pyproject.toml . You may format your code using:

poetry run black . -t py310

and ensure your code conforms to our linting with :

poetry run black --diff . -t py310

Contributions

Contributions are welcome, feel free to fork our repository and open a pull request or open an issue. Please review our contribution guidelines before contributing.