A collection of Cogs for discord.py bots
This project is a collection of general-use modules, called Cogs, for discord bots written with the discord.py v2.0 Python library.
To install the modules, you can install them directly from the repository's master branch:
pip install -U "git+https://github.com/Snaptraks/SnapCogs@master"
To install with optional dependencies, use:
pip install -U "snapcogs[deps-here] @ git+https://github.com/Snaptraks/SnapCogs@master"
where deps-here is a comma seperated list of the following:
developmenthoroscopetimestamps
Then load the extensions in your bot's code inside the setup_hook method:
import asyncio
from discord.ext import commands
class MyBot(commands.Bot):
async def setup_hook(self):
await self.load_extension("snapcogs.<COGNAME>")
async def main():
bot = MyBot(...)
async with bot:
await bot.start(TOKEN)
asyncio.run(main())where <COGNAME> is one of the modules in Cogs Description.
You can of course load more than one cog:
import asyncio
from discord.ext import commands
class MyBot(commands.Bot):
async def setup_hook(self):
startup_extensions = [
"my_cogs_folder.SomeCog",
"snapcogs.Admin",
"snapcogs.Poll",
]
for extension in startup_extensions:
await self.load_extension(extension)
async def main():
bot = MyBot(...)
async with bot:
await bot.start(TOKEN)For ease of use, the package comes with a commands.Bot subclass that takes the extensions to load at startup as a keyword argument.
from snapcogs import Bot
async def main():
startup_extensions = [
"my_cogs_folder.SomeCog",
"snapcogs.Admin",
"snapcogs.Poll",
]
bot = Bot(..., startup_extensions=startup_extensions)
async with bot:
await bot.start(TOKEN)We provide a commands.Bot subclass that handles the creation of a SQLite database and other utilities needed for the cogs to work properly.
This subclass also provides a custom on_command_error where errors that are explicitely not handled by the command's or cog's error handler will be logged with the logging module. This is different from the default behaviour from discord.py where errors were silenced no matter what when an error handler was found.
To make sure errors are logged here even when application commands have an error handler, you should use the following pattern for the handler:
async def error_handler(ctx: commands.Context, error: Exception):
if isinstance(error, ...):
# do something here
elif isinstance(error, ...):
# for another type of exception
else:
# this is the important part
ctx.error_handled = FalseSimilar to the Bot subclass, we provide a custom app_commands.CommandTree subclass that overwrites the on_error method to log errors to the logger, whenever errors are explicitely not handled.
By default, the Bot subclass will use this custom CommandTree.
To make sure errors are logged here even when commands have an error handler, you should use the following pattern for the handler:
async def error_handler(interaction: discord.Interaction, error: Exception):
if isinstance(error, ...):
# do something here
elif isinstance(error, ...):
# for another type of exception
else:
# this is the important part
interaction.extras["error_handled"] = FalseHere is a list of the cogs, and their functionalities.
Application commands (discord.app_commands.AppCommands) are prefixed with the / character.
Context menus (right click) are indicated as User | Member > command_name or Message > command_name, and discord.ext.commands.Commands are left without prefix (you are free to use your own prefix).
Required arguments in commands are marked with angle brackets <>, and optional ones with square brackets [].
The cog has a bot owner check. Only the bot owner(s) can use these commands.
Sync AppCommands to the provided guilds or globally if none are passed, or to the current guild if "~" is passed instead.
Clear AppCommands of the provided guilds or globally if none are passed, or of the current guild if "~" is passed instead.
Launch an interactive REPL session. A Read-Eval-Print-Loop allows you to run code interactively. This is a possibly very dangerous command, so be careful who can use it! For ease of use, some variables are defined automatically:
ctx: ctxbot: ctx.botmessage: ctx.messageguild: ctx.guildchannel: ctx.channelauthor: ctx.author
Commands to announce stuff in your server, such as members birthdays!
Register your birthday on the current server.
Display the next birthday in the current server.
Celebrate a member's birthday in the current server.
Show information on up to 25 unicode characters. This includes unicode endpoints and string literals.
Convert a value from one unit to another. The from and to parameters have autocomplete enabled, suggesting different units as you are typing, according to dimentionality (either the units are of length, mass, time, etc.).
Fortune-telling or advice seeking. Ask the Magic 8 Ball a yes-or-no question, and maybe it will answer!
Bonk a member, and add a message! This command creates an image with the member's profile picture and the bonk meme.
Get today's horoscope for the given Zodiac sign. Information is taken from horoscope.com.
View information about the bot itself. This includes servers statistics, and possible link to the bot's repository.
View information about the current server. This include members and channels statistics.
View information about a user / member. This includes individual user data such as their ID and account creation date, and possibly server join date and roles (if used in a server context).
Member context menu sinilar to the /info user command.
Create a role selection menu, to select many roles from the list. By defaut, send the menu in the current channel, but can be specified with the channel argument. The content of the message can also be specified, and will show above the selection menu.
Create a role selection menu, to select one role from the list. By defaut, send the menu in the current channel, but can be specified with the channel argument. The content of the message can also be specified, and will show above the selection menu.
Add a role to the selection menu. You need to specify the message by either it's ID (123456789123456789), combo <channel ID>-<message ID> (Shift + Copy ID), or jump url (Copy Message Link).
Remove a role to the selection menu. You need to specify the message in the same way as mentionned above.
Edit the content of a role selection menu message. YYou need to specify the message in the same way as mentionned above.
Delete a role selection menu message. This way ensures that the data is also deleted from the bot. You need to specify the message in the same way as mentionned above.
Example of a roles selection menu:
This cog allows to create nicely formatted Discord timestamps (example here) from a provided time and time zone. The arguments in the following commands all feature autocompletes, so be sure to use them to avoid errors!
Create timestamps of now to send to get rich formatting.
Create timestamps of the given time to send to get rich formatting.
Create a new tip for the current server, owned by you. This sends a modal to the user, with a form to fill out. Tips support markdown and mentions.
Show a tip in the current channel. This command, as well as all the others taking a tip's name as argument, feature autocomplete with a list of names similar to what is being typed. This command autocompletes from all tips in the server.
Modify the content of a tip that you own. This sends a modal to the user with the current tip data already filled out. The autocomplete will only suggest tip names that are written by you.
Get information about a tip. The information provided includes the tip's author, when it was created and last edited, and number of uses (one usage is recorded when /tip show is used).
Get the raw content of a tip, escaping markdown. This is useful when trying to see how a tip was formatted.
Delete a tip that you wrote. Members with the Manage Messages server permission, as well as the bot author, can delete tips from other members.
Delete all tips from the given member in this server. You need the Manage Messages server permission to be able to use this command.
Transfer tip ownership to another member. You can only transfer tips that you own, to another member that isn't you, or a bot!
Claim a tip where the author has left the server.
List all the tips that you, or someone else, wrote. Using this command without the member argument will list your tips.
List all the tips from this server.
Get statistics for a member or the whole server. Using this command without the member argument will show statistics for the whole server. Member statistics include total tips and tips usage, as well as the top 3 tips most used in the server. Server statistics add the top 3 members with the most written tips.
The snapcog.utils package is not a Cog, but rather a collection of useful objects and functions, some necessary for the rest of the package. The following are therefore not application commands, context menus, nor text commands.
A shortcut for discord.utils.format_dt(dt, style="R") used here.
Run a command in shell. This then returns the stdout and stderr inside a tuple. This is potentially dangerous, so be careful how you use it!
Similar to app_commands.checks.has_permissions, but operates on guild wide permissions instead of the current channel permissions. If this check is called in a DM context, it will raise an exception, app_commands.NoPrivateMessage. Ported from discord.ext.commands and adapted for ApplicationCommands.
Similar to app_commands.checks.has_guild_permissions, but checks the bot members guild permissions. Ported from discord.ext.commands and adapted for ApplicationCommands.
A view that asks the user to confirm a choice, by the press of ui.Buttons.
Sends a message to the user from the interaction, with views.Confirm attached to it. Once the interaction is done, returns a bool whether or not the action was confirmed.
Application command transformers that converts an argument to a discord.Message. The Bot version ensures that the message's author was the bot itself.
Exception raised by MessageTransformer when the message could not be found.
Exception raised by BotMessageTransformer when the provided message was not sent by the bot.
- HatBot: Bot for the Hatventures Community Discord server
- Zenyatta: Bot for a single private server
- PhysBot: Bot for the PHYSUM Discord server
The SnapCogs logo was created using the Unicorn icon created by rddrt - Flaticons and the Development icons created by Smashicons - Flaticon