Skip to content

snippets

Base utilities and classes for snippet management.

This module provides the foundational classes and utilities for managing code snippets in Discord guilds, including base functionality for snippet commands and permission checking.

Modules:

Classes:

  • SnippetsBaseCog –

    Base class for Snippet Cogs, providing shared utilities.

Classes

SnippetsBaseCog

Python
SnippetsBaseCog(bot: Tux)

Bases: BaseCog

Base class for Snippet Cogs, providing shared utilities.

Initialize the snippets base cog.

Parameters:

  • bot (Tux) –

    The bot instance to attach this cog to.

Subclassed by:

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

is_snippetbanned async
Python
is_snippetbanned(guild_id: int, user_id: int) -> bool

Check if a user is currently snippet banned in a guild.

Parameters:

  • guild_id (int) –

    The ID of the guild to check.

  • user_id (int) –

    The ID of the user to check.

Returns:

  • bool –

    True if the user is snippet banned, False otherwise.

_create_snippets_list_embed
Python
_create_snippets_list_embed(
    ctx: Context[Tux],
    snippets: list[Snippet],
    total_snippets: int,
    search_query: str | None = None,
) -> Embed

Create an embed for displaying a paginated list of snippets.

Parameters:

  • ctx (Context[Tux]) –

    The context object.

  • snippets (list[Snippet]) –

    The list of snippets for the current page.

  • total_snippets (int) –

    The total number of snippets matching the query.

  • search_query (str | None, default: None ) –

    The search query used, if any.

Returns:

  • Embed –

    The generated embed.

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

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

check_if_user_has_mod_override async
Python
check_if_user_has_mod_override(ctx: Context[Tux]) -> bool

Check if the user invoking the command has moderator permissions (rank >= 2).

Returns:

  • bool –

    True if user has moderator permissions, False otherwise.

snippet_check async
Python
snippet_check(
    ctx: Context[Tux], snippet_locked: bool = False, snippet_user_id: int = 0
) -> tuple[bool, str]

Check if a user is allowed to modify or delete a snippet.

Checks for moderator override, snippet bans, role restrictions, snippet lock status, and snippet ownership.

Parameters:

  • ctx (Context[Tux]) –

    The context object.

  • snippet_locked (bool, default: False ) –

    Whether the snippet is locked. Checked only if True. Defaults to False.

  • snippet_user_id (int, default: 0 ) –

    The ID of the snippet's author. Checked only if non-zero. Defaults to 0.

Returns:

  • tuple[bool, str] –

    A tuple containing a boolean indicating permission status and a reason string.

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_snippet_or_error async
Python
_get_snippet_or_error(ctx: Context[Tux], name: str) -> Snippet | None

Fetch a snippet by name and guild, sending an error embed if not found.

Parameters:

  • ctx (Context[Tux]) –

    The context object.

  • name (str) –

    The name of the snippet to fetch.

Returns:

  • Snippet | None –

    The fetched Snippet object, or None if not found.

send_snippet_error async
Python
send_snippet_error(ctx: Context[Tux], description: str) -> None

Send a standardized snippet error embed.

Parameters:

  • ctx (Context[Tux]) –

    The context object.

  • description (str) –

    The error message description.

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

_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