Apollo is a Discord bot for the University of Warwick Computing Society.
It is designed to augment our Discord server with a few of the user services available on our website.
If you are new to Apollo / Discord Bots, read a minimum of
- Incredibly Quick Start
- General Structure
- Top of Contributing
¶ Installation
¶ Incredibly Quick Start
- Clone repo:
git clone https://github.com/UWCS/apollo - Install pipenv
pip install pipenv - Install project dependencies
pipenv install
Trypython -m pipenv installif pipenv is not found - Create your Discord Bot Account and copy token: follow Discord.py's guide
- Copy
config.example.yamltoconfig.yaml
Setdiscord_token: <COPIED TOKEN> - In
apollo.pycomment out all the commands inEXTENSIONSexcept the one you are working on
(This avoids loading any that depend on the database or unconfigured fields) - Run with
pipenv run python apollo.py
¶ Proper Installation Instructions
¶ Dependencies
Apollo uses pipenv for dependency and venv management. Install it with pip install pipenv, and then run pipenv install to install all the required dependencies into a new virtual environment.
¶ Development Setup
pipenv install, as above- Copy
config.example.yamltoconfig.yamland configure the fields. - Copy
alembic.example.initoalembic.iniand configure any fields you wish to change. - Set up the database by running migrations with
alembic upgrade head.- The default database location is
postgresql+psycopg://apollo:apollo@localhost/apollo(inconfig.example.yaml)
This requires PostgreSQL to be installed, with a database calledapolloand a user with name and passwordapollowith access to it. - For testing purposes, you may wish to change it to a locally stored file such as
sqlite:///apollo.sqlite3. - Alternatively, see the instructions below for using Docker.
- The default database location is
- On the Discord Developer Portal, make sure that your bot has the required intents.
- Currently, the Messages and Members intents are necessary.
Run Apollo using pipenv run python apollo.py
¶ Using Docker
A Dockerfile and docker-compose are provided for easily running Apollo. Assuming you already have docker installed, run docker compose up to start both Apollo and a postgres database.
The compose file uses a docker compose config to mount config.yaml into the container at runtime, not at build time. Copy config.example.yaml to config.yaml and configure the fields so that compose can do this. You will need to change the database url to postgresql+psycopg://apollo:apollo@db/apollo if you wish to connect to the containerised database.
The docker image builds alembic.ini into it by copying the example, as it is rare any values in this wish to be changed on a per-deployment basis.
When you first create the database container, you'll need to apply migrations:
- Run
docker compose upto start both services. The python one won't work, but leave it running.- When changing any source files, the container will have to be rebuilt:
docker compose up --build
- When changing any source files, the container will have to be rebuilt:
- Run
docker compose exec apollo alembic upgrade headto apply the database migrations. - Run
docker compose restart apolloto restart the bot with migrations applied.
Migrations will need to be re-applied every time the database schema changes.
¶ General Structure
cogs/commands: Where the main code for commands reside.config: Config parser.migrations: Handles database upgrades.models: Database ORM classes to map between Python and SQL.tests: Unit tests for some commands, still very WIP.utils: Some general shared utility functions.karma,roll,printer,voting: commands that have enough code to warrant a separate directory.
¶ Contributing
-
As always, check GitHub Issues first, make sure to tell us when you are working on something
- Both so we can help and so nobody doubles up on issues
-
When creating a PR, I highly recommend ticking
Allow edits from maintainers -
This project uses
blackandruffto format the code and enforce code style.- Before submitting your code for a PR, run
black .andruff check --fix .in the root directory - If this doesn't work, run
pipenv shellfirst to drop into the venv where the tools are installed.
- Before submitting your code for a PR, run
-
See
flip.pyfor an example of a basic command. -
We generally want to use
@commands.hybrid_command, so we get a slash command and text command, this does have some restrictions though -- see the following point aboutclean_content-- which you should use to take user input btw.
-
When writing anything that needs to reply to a specific username, please do
from utils import get_name_stringand get the display string using this function, with the discordMessageobject as the argument (e.g.display_name = get_name_string(ctx.message)).- This will return either a discord username, formatted correctly, or an irc nickname depending on the source of the message.
- This result can be used as normal in a format string e.g.
await ctx.send(f'Sorry {display_name}, that won't work.'). - Using something like
ctx.replydoesn't notify IRC users due to bridge limiations
-
To handle IRC and Discord users, we have a 3rd type: Database users. It's kinda confusing what is needed where, and do ask if you need.
- To get the Database user for a message's author (or similar), use
utils.get_database_user.
- To get the Database user for a message's author (or similar), use
-
If you want to get a longer text field as input, use
async def cmd(self, ctx, [...], *, args: str), and the remaining text (after other arguments) will be consumed into theargsparameter. We also recommend theclean_contentconverter to remove mentions, etc. however it has not been converted to aTransformeryet (needed for slash/hybrid commands), only aConverter(for text commands only).- For now, type the field as a string (as above), and manually call
clean_contenton it:args = await clean_content().convert(ctx, args). - If you want to split this by words, use
.split()orshlex.splitif it is a shell-like style. - If you want a list of words/phrases (e.g. poll options), I recommend
voting.splitutils.split_args, which infers the delimiter from a list (["\n", ";", ",", " "]by default) and allows escaping them where necessary.
- For now, type the field as a string (as above), and manually call
-
We have a few more useful functions:
utils.is_compsoc_exec_in_guilddecorator adds a check to the command that the author is exec only.utils.rerun_to_confirmdecorator, which gives a prompt to rerun the command to confirm intent (e.g. delete something important)announcement_utils.get_long_msgfor when you want a multiline input.- As slash commands don't allow multiple lines, it looks at the command arg first, then the message replied to, then if nothing, it sends a popup modal asking for input.
-
For testing CI locally, use act-cli, although I have not found this a perfect replica.
¶ Database Handling
There are currently some problems with the database schema, so downgrading may not work perfectly. These shall be fixed soon.
We use SQLAlchemy for queries and Alembic for migration management. We use SQLAlchemy to write DB queries and it links objects and the data stored in the DB tables. If you are unfamiliar, SQLAlchemy queries are fairly directly comparable to SQL, and result in Python objects that are a whole lot easier to work with:
db_session.query(Announcement)
.where(Announcement.id == announcement_id)
.first()
Models, the classes that define the DB schema, are found in /models/. They define the Python classes that are equivalent to the SQL tables (see models/votes.py for a fairly complete example). It also defines shorthands for getting related objects. To get objects linked by a foreign key, you define a relationship, which becomes shorthand for that link, instead of writing another SQL query.
Migrations are the way we add new features and tables to the database, while still keeping the old data. When you ran this bot, you ran alembic upgrade head, which runs all the migrations from base (nothing) to head (latest version). The code from each migration is stored within /migrations/versions. Each migration describes the changes to upgrade to a version (usually creating a new table or adding a new field/column), and how to downgrade from that version (usually dropping tables).
You can create a migration by running alembic revision -m "<summary>" which creates the template file. You can let Alembic autogenerate the migration with alembic revision --autogenerate -m "<summary>". This is usually good enough, but check it carefully, making sure it drops enums and constraints as well as tables.
¶ Creating a Migration
- Create your model in
/models - Import it from
/models/__init__.py(so Alembic knows it exists) - Run
alembic revision --autogenerate -m "<summary>" - Check the newly created upgrade and downgrade is correct
- If ugrading apollo itself run
~/apollo/backup-db.shon berylliun to back up the databases - Upgrade your database with
alembic upgrade head
¶ SQLite
Due to differences between SQLite and Postgres, we recommend you use Postgres for development, as that is what we use once deployed. SQLAlchemy and Alembic do a fairly good job of being agnostic between drivers, but they certainly aren't perfect.
The major example of this is altering tables, tables cannot be directly altered to remove a column or a constraint (e.g. foriegn key), so a new table must be created, data copied and edited across, and the old one replaced. Thankfully, Alembic can handle this for us, with a batch operation:
with op.batch_alter_table("<table>") as bop:
bop.drop_column("<column>")
Note: batch operations automatically become normal alter commands instead of copy and move on drivers that support alter, such as Postgres.
¶ To make a new command
Add the name of your command in a file in the cogs/commands directoy. A base command called example should have the following boilerplate in the file example.py:
import discord
from discord.ext import commands
from discord.ext.commands import Bot, Context
class Example(commands.Cog):
def __init__(self, bot: Bot):
self.bot = bot
@commands.hybrid_command(help=<long help>, brief=<short help>)
async def example(self, ctx: Context, <optional args>):
<command goes here>
async def setup(bot: Bot):
await bot.add_cog(Example(bot))
This then needs to be added to apollo.py with the line "cogs.commands.example" in the EXTIONS list.
If a command needs to be run on every message sent then it can be called in the on_message() subroutine in the cogs/database.py file. This should be done sparingly though as it could very easily overwhelm Apollo especially in high-traffic scenarios.
¶ Commands
Cogs are how Discord.py organizes commands, each file is a separate cog with separate functionality. If you don't know about cogs already, ask on Discord or go some d.py docs. If you want to temporarily disable a Cog, comment out its line in apollo.py while developing.
¶ Welcome
Sends the welcome message to new users, which looks like this:
Functionality
- Draws the message template and random favourite thing from
resources/welcome_message.yaml. - Each category has a weight and a list of possible values.
- If membership verification (e.g. read the rules pop-up) is enabled, it waits until after that
Config
resources/welcome_message.yamlfor contentUWCS_welcome_channel_idis the message to post this inUWCS_roles_channel_idis the role channel to mention in the message
¶ IRC
Ensures IRC users can use this bot too. Apollo does not do the actual bridging.
IRC makes some parts of this more complex, e.g. we have both IRC and Discord users, text commands must be provided for
Functionality
- Parses any IRC bot messages into a command
Some general notes on IRC
- We have a separate User class in the DB to a Discord user, ensure you are using the right one, some code is not clear which it requires.
- TODO more
Configuration
UWCS_discord_bridge_bot_idis the ID of the IRC bridging bot
¶ Database
Creates user objects in database and dispatches Karma checks on message.
Functionality
- Originally logged messages and edits as well, perhaps refactor into main karma file now.
¶ Channel Checker
Checks if channel order has been changed by accident. Sends a warning message on change.
Functionality
- Polls for changes on intervals and checks the diff of the order.
- Sends a message to an exec channel with a warning
- This is one thing that Discord doesn't have an audit log entry or perms for
Configuration
UWCS_exec_spam_channel_idsets the channel to send the warning message tochannel_check_intervalsets the period of the checking - keep somewhat large so multiple purposeful changes are limited to one message.
¶ Parallelism
Thread pool manager used for !roll and (used to be) others
¶ Announce
Allows exec to make scheduled announcements. Will post through a webhook if possible.
Functionality
- Mostly ripped off from the existing Reminder system and Minesoc's announcements
- Getting the announcement content is a bit of a mess, since we need to allow multi-line announcements
- Slash commands don't do multiple lines, so use a pop-up as a backup case for these. Prefers message content or replying to a message with the command.
- Has some Markdown like formatting - if the correct fonts are included, it will render titles as images with the font
- It also handles splitting it into multiple messages and inserting images with a line starting with
IMG <link>
Configuration
announcement_search_intervalsets the interval for checking for announcement times passingannouncement_impersonatewhether the bot should post through a Webhook and appear like the original author
¶ Counting
Everyone's favourite counting game
Functionality
- Records runs and highest numbers reached by user
¶ ChatGPT
We decided we had too much money and wanted to give it all to openAI. Makes appollo into a chat bot.
Functionality
- use
!chator!promptalong with your intial message to start the chain - then reply to any message apollo sends to continue the chat (message history is maintained)
¶ Dalle
Wasting more money on openAI. Generates image based on a prompt
Functionality
- use
!dalle <prompt>to generate an initial message - can then use
regenerateorvariantto alter the original image - for example, if the prompt was "a dog" and the initial image was a black labrador,
regeneratewould result in a differnt breeed (say a husky) where asvariantwould maintian the breed and colour
¶ Date
Fetches the date and time in Discord timestamp formats
Functionality
- Day of the week, date, time, time until (and more through
!timestamps) - Discord has various options for rendering a timestamp (see https://hammertime.cyou/en-GB), this gives easy access to them.
¶ Event Sync
Fetches events from the UWCS website iCal and syncs onto Discord
Functionality
- Is unfortunately limited to the short preview description instead of the rich text one through the iCal
- Records these events in DB, so subsequent calls edit the existing event instead of creating a new one
- Doesn't pick up on manually created events
¶ Flip
Flips a coin or picks from a set of options
Functionality
- Uses
shlexto split options, unlike elsewhere in this project
¶ Karma
The big boy, allows adding or subtracting from the karma of topics (anything) with <thing>++ or <thing>-- in a message (+- also exists for neutral).
Functionality
- Karma reasons are stored if the ++/-- is followed by
fororbecauseor a reason in brackets or quotes. - Karma functionaility is split across quite a few files (
cogs/commands/karma,.../karma_admin,.../karma_blacklist,cogs/database,karma/karma,karma/parser,karma/transactions) would be nice to organize some of these together in future. - Channels with more traffic can be put into mini karma mode, where the feeback message is a single line instead of very long.
- Can also ignore channels (in
karma_admin) or blacklist topics (karma_blacklist)
- Can also ignore channels (in
- Karma parsing could be somewhat improved (see issues #28 #91), but it's already a monstrosity
- Various karma info and graphing commands also exist
Configuration
karma_cooldowndetermines the cooldown time between the karma of a topic being changed (by anyone). This stops complete spam wars.!admin minikarma <channel>: toggle minikarma mode (shortened karma change report).!admin channel <channel> [Ignore|Watch]: setkarma detection ignoring a channel.!blacklist <add|remove> <topic>: add topic to the blacklist.
¶ Lambda Calculus (LCalc)
Lambda calculus interpreter and reducer. Another case of someone felt like writing a parser. This still needs converting to use hybrid/slash commands at some point.
¶ Misc
A set of alias commands for various memes and useful info. Sometime might be nice to create a more flexible !alias command to add these through Discord.
¶ Quotes
Allows quoting users and fetching these later. There is currently a PR to makes quotes more useful.
¶ Reminders
Allows users to get reminders through this bot.
Functionality
- It periodically queries the DB for reminders that are due
- There is no reminder list or delete at the moment, these could be backported from Announcements
Configuration
reminder_search_intervalsets the interval between checks. Effectively the accuracy of the reminders.
¶ Role Menu
Functions similarly to the vote system. Creates a role menu with buttons (not reacts).
Functionality
- Button clicks toggle the role.
- It has been suggested to add a button that triggers an ephemeral message to each user showing their current roles and allowing toggling them.
- Each menu can either be limited to one role, or allow arbitrarily many per user.
- It automatically adds placeholder line to the message when a button is added. This can be edited (or removed)
- On bot startup, the buttons for each menu need to be re-set to connect the interactions.
Configuration
!roles set_msgsets the body of the message -- will check replies or modal- Note
UWCS_roles_channel_idis for the welcome message only, and nothing here.
¶ Roll
Rolls (a set) of dice. Very flexible on arithmetic operations and nesting rolls.
Functionality
- The full parser is in
/roll/and consists ofparser(parses the text into tokens),ast(constructs and evaluates the tree of operations), andexceptions(possible errors in the command).- These are all called from
cogs/commands/rolland evaluation is handled in a separate thread to avoid particularly complex expressions causing problems.
- These are all called from
¶ Roomsearch
Brings together various Warwick APIs to lookup rooms and locations.
Functionality
- Unfortunately these mappings are not well defined, and are sourced from various Warwick projects
- Borrows the campus map API, it has a static single auth token for its API, which we have also borrowed.
resources/rooms/source/README.mddescribes the full process of refreshing these mappings- Room info from ITS, Tabula to Sciencia (timetable) from Tabula source code, timetable name to timetable URL mapping from timetable reports interface.
- Most of these steps have custom mappings since they are incomplete somewhere.
Configuration
- Custom mappings for each stage of the Map API -> Tabula Name -> Sciencia (timetable) name -> Timetable URL exist
- The structure of those files is a bit of a mess, but most only need to be considered when updating the mappings.
¶ Say
Gets the bot to repeat something.
¶ Tex
Renders a LaTeX expression
Functionality
- It is recommended to wrap the input in backticks (code), but this can handle any combination of backticks and dollars (LaTeX math markers)
- In fact, can even handle mixing maths and text:
!tex try $a+b$ this $c+d$ - Uses https://latex.codecogs.com/ to render, then masks the black and white into Discord bg grey and white.
¶ Vote
Supports votes and polls. Some painful complexity to allow polls over Discord's limit of 25 buttons per message. Originally taken from ericthelemur/VoteBot
TODO Write this mess up see voting/README for now
¶ Widen
Replaces the contents of the message with wide versions of characters and larger spacing.
¶ XKCD
Everyones favourite web comic.
Functionality
Use /xkcd or !xkcd to get a random comic or add an ID to the query to get a spefic comic. Name searches coming soonTM.
¶ Unused
print_tools: Gave information about the society's 3D printing services, but 3D printer hasn't been working for ages
verify: We used to give a verified role to society members, but this is entirely unecessary and is exclusionary to new joiners.
fact: generates a random fact