Skip to content

bookmarks

Bookmark service for saving and managing Discord messages.

This module provides functionality to bookmark Discord messages through reactions, allowing users to save important messages for later reference. Messages can be bookmarked by reacting with specific emojis, and bookmarks are stored in user DMs.

Classes:

  • Bookmarks –

    Discord cog for bookmarking messages.

Functions:

  • setup –

    Set up the Bookmarks cog.

Classes

Bookmarks

Python
Bookmarks(bot: Tux)

Bases: BaseCog

Discord cog for bookmarking messages.

This cog allows users to bookmark messages by reacting with specific emojis, and manages the storage and retrieval of bookmarked messages.

Initialize the Bookmarks cog.

Parameters:

  • bot (Tux) –

    The bot instance to attach this cog to.

Methods:

  • cog_unload –

    Clean up the cog, closing the aiohttp session.

  • on_raw_reaction_add –

    Handle bookmarking messages via reactions.

  • add_bookmark –

    Send a bookmarked message to the user's DMs.

  • remove_bookmark –

    Delete a bookmark DM when the user reacts with the remove emoji.

  • get_config –

    Get a configuration value from CONFIG with support for nested keys.

  • __repr__ –

    Return a string representation of the cog instance.

  • unload_if_missing_config –

    Check if required configuration is missing and log warning.

Attributes:

Attributes

db property
Python
db: DatabaseCoordinator

Get the database coordinator for accessing database controllers.

Returns:

  • DatabaseCoordinator –

    Coordinator providing access to all database controllers.

Examples:

Python Console Session
>>> await self.db.guild_config.get_guild_config(guild_id)
>>> await self.db.cases.create_case(...)
Notes

This property provides convenient access to database operations without needing to access self.bot.db directly.

Functions

cog_unload async
Python
cog_unload() -> None

Clean up the cog, closing the aiohttp session.

on_raw_reaction_add async
Python
on_raw_reaction_add(payload: RawReactionActionEvent) -> None

Handle bookmarking messages via reactions.

This listener checks for specific reaction emojis on messages and triggers the bookmarking or unbookmarking process accordingly.

Parameters:

_setup_command_usage
Python
_setup_command_usage() -> None

Generate usage strings for all commands in this cog that lack explicit usage.

The generated usage follows the pattern: <qualified_name> <param tokens>

Where: - Required parameters are denoted as <name: Type> - Optional parameters are denoted as [name: Type] - The prefix is intentionally omitted (provided by ctx.prefix)

Examples:

ban <member: Member> [reason: str] config set <key: str> <value: str>

Notes

Respects explicit usage strings if already set on a command. Errors during generation are logged but don't prevent cog loading.

add_bookmark async
Python
add_bookmark(user: User, message: Message) -> None

Send a bookmarked message to the user's DMs.

Parameters:

  • user (User) –

    The user who bookmarked the message.

  • message (Message) –

    The message to be bookmarked.

_generate_usage
Python
_generate_usage(command: Command[Any, ..., Any]) -> str

Generate a usage string with support for flags and positional parameters.

This method inspects the command's callback signature to detect: - FlagConverter parameters (e.g., --flag value) - Positional parameters (e.g., <required> or [optional])

Parameters:

  • command (Command) –

    The command to generate usage for.

Returns:

  • str –

    Generated usage string, or qualified command name as fallback.

Notes

Delegates to shared usage generator for consistency across all cogs. Falls back gracefully to command name if generation fails.

remove_bookmark async staticmethod
Python
remove_bookmark(message: Message) -> None

Delete a bookmark DM when the user reacts with the remove emoji.

Parameters:

  • message (Message) –

    The bookmark message in the user's DMs to be deleted.

_get_files_from_attachments async
Python
_get_files_from_attachments(message: Message, files: list[File]) -> None

Extract image files from message attachments.

Parameters:

  • message (Message) –

    The message to extract attachments from.

  • files (list[File]) –

    The list to append extracted files to.

_get_files_from_stickers async
Python
_get_files_from_stickers(message: Message, files: list[File]) -> None

Extract image files from message stickers.

Parameters:

  • message (Message) –

    The message to extract stickers from.

  • files (list[File]) –

    The list to append extracted files to.

get_config
Python
get_config(key: str, default: Any = None) -> Any

Get a configuration value from CONFIG with support for nested keys.

Parameters:

  • key (str) –

    The configuration key to retrieve. Supports dot notation for nested values (e.g., "BOT_INFO.BOT_NAME").

  • default (Any, default: None ) –

    Default value to return if key is not found, by default None.

Returns:

  • Any –

    The configuration value or default if not found.

Examples:

Python Console Session
>>> self.get_config("BOT_INFO.BOT_NAME")
'Tux'
>>> self.get_config("MISSING_KEY", "fallback")
'fallback'
Notes

Errors during retrieval are logged but don't raise exceptions. Returns the default value on any error.

_get_files_from_embeds async
Python
_get_files_from_embeds(message: Message, files: list[File]) -> None

Extract image files from message embeds.

Parameters:

  • message (Message) –

    The message to extract embeds from.

  • files (list[File]) –

    The list to append extracted files to.

_get_files_from_message async
Python
_get_files_from_message(message: Message) -> list[File]

Gathers images from a message to be sent as attachments.

This function collects images from attachments, stickers, and embeds, respecting Discord's 10-file limit.

Parameters:

  • message (Message) –

    The message to extract files from.

Returns:

  • list[File] –

    A list of files to be attached to the bookmark message.

__repr__
Python
__repr__() -> str

Return a string representation of the cog instance.

Returns:

  • str –

    String representation in format <CogName bot=BotUser>.

_create_bookmark_embed
Python
_create_bookmark_embed(message: Message) -> Embed

Create an embed for a bookmarked message.

This function constructs a detailed embed that includes the message content, author, attachments, and other contextual information.

Parameters:

  • message (Message) –

    The message to create an embed from.

Returns:

  • Embed –

    The generated bookmark embed.

unload_if_missing_config
Python
unload_if_missing_config(condition: bool, config_name: str) -> bool

Check if required configuration is missing and log warning.

This allows cogs to detect missing configuration at load time and return early from init to prevent partial initialization.

Parameters:

  • condition (bool) –

    True if config is missing (should unload), False otherwise.

  • config_name (str) –

    Name of the missing configuration for logging purposes.

Returns:

  • bool –

    True if config is missing (caller should return early), False if config is present.

Examples:

Python Console Session
>>> def __init__(self, bot: Tux):
...     super().__init__(bot)
...     if self.unload_if_missing_config(not CONFIG.GITHUB_TOKEN, "GITHUB_TOKEN"):
...         return  # Exit early, cog will be partially loaded but won't register commands
...     self.github_client = GitHubClient()
Notes

When this returns True, the cog's init should return early to avoid initializing services that depend on the missing config. The cog will be loaded but commands won't be registered properly, preventing runtime errors.

For complete cog unloading, the bot owner should remove the cog from the modules directory or use the reload system to unload it programmatically.

_unload_self async
Python
_unload_self(extension_name: str) -> None

Perform the actual cog unload operation.

Parameters:

  • extension_name (str) –

    Full extension name to unload.

Notes

This is called as a background task by unload_if_missing_config(). Errors during unload are logged but don't raise exceptions.

Functions

setup async

Python
setup(bot: Tux) -> None

Set up the Bookmarks cog.

Parameters:

  • bot (Tux) –

    The bot instance to add the cog to.