Skip to content

starboard

Starboard service for highlighting popular messages.

This module implements a starboard system that automatically reposts messages to a designated channel when they receive enough reactions, allowing communities to highlight and celebrate high-quality content.

Classes:

  • Starboard –

    Discord cog for starboard functionality.

Functions:

  • setup –

    Set up the Starboard cog.

Classes

Starboard

Python
Starboard(bot: Tux)

Bases: BaseCog

Discord cog for starboard functionality.

This cog monitors reactions on messages and automatically posts messages to a designated starboard channel when they reach a configured threshold.

Initialize the Starboard cog.

Parameters:

  • bot (Tux) –

    The bot instance to attach this cog to.

Methods:

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

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

Handle reaction add events for starboard functionality.

Parameters:

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

Handle reaction remove events for starboard functionality.

Parameters:

starboard_on_reaction_clear async
Python
starboard_on_reaction_clear(payload: RawReactionClearEvent) -> None

Handle reaction clear events for starboard functionality.

Parameters:

starboard_on_reaction_clear_emoji async
Python
starboard_on_reaction_clear_emoji(payload: RawReactionClearEmojiEvent) -> None

Handle reaction clear emoji events for starboard functionality.

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.

starboard async
Python
starboard(ctx: Context[Tux]) -> None

Configure the starboard for this server.

setup_starboard async
Python
setup_starboard(
    ctx: Context[Tux], channel: TextChannel, emoji: str, threshold: int
) -> None

Configure the starboard for this server.

Parameters:

  • channel (TextChannel) –

    The channel to use for the starboard.

  • emoji (str) –

    The emoji to use for the starboard.

  • threshold (int) –

    The number of reactions required to trigger the starboard.

_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_starboard async
Python
remove_starboard(ctx: Context[Tux]) -> None

Remove the starboard configuration for this server.

Parameters:

  • ctx (Context[Tux]) –

    The context of the command.

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_existing_starboard_message async
Python
get_existing_starboard_message(
    starboard_channel: TextChannel, original_message: Message
) -> Message | None

Get the existing starboard message for a given original message.

Parameters:

  • starboard_channel (TextChannel) –

    The starboard channel.

  • original_message (discord.Message`) –

    The original message.

Returns:

  • Message | None –

    The existing starboard message or None if it does not exist.

__repr__
Python
__repr__() -> str

Return a string representation of the cog instance.

Returns:

  • str –

    String representation in format <CogName bot=BotUser>.

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.

create_or_update_starboard_message async
Python
create_or_update_starboard_message(
    starboard_channel: TextChannel, original_message: Message, reaction_count: int
) -> None

Create or update a starboard message.

Parameters:

  • starboard_channel (TextChannel) –

    The starboard channel.

  • original_message (Message) –

    The original message.

  • reaction_count (int) –

    The number of reactions on the original message.

_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.

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

Handle starboard reaction add or remove.

handle_reaction_clear async
Python
handle_reaction_clear(
    payload: RawReactionClearEvent | RawReactionClearEmojiEvent,
    emoji: PartialEmoji | None = None,
) -> None

Handle reaction clear for all emojis or a specific emoji.

Parameters:

Functions

setup async

Python
setup(bot: Tux) -> None

Set up the Starboard cog.

Parameters:

  • bot (Tux) –

    The bot instance to add the cog to.