tldr ¶

TLDR command integration for Discord.

This module provides TLDR (Too Long; Didn't Read) command documentation lookup functionality, allowing users to search and view command summaries from various platforms with interactive pagination.

Classes:

Tldr –

Discord cog for TLDR command integration.

Functions:

setup –

Set up the Tldr cog.

Classes¶

Tldr ¶

Python

Tldr(bot: Tux)

Bases: BaseCog

Discord cog for TLDR command integration.

Initialize the TLDR cog.

Parameters:

bot (Tux) –

The bot instance to attach this cog to.

Methods:

cog_load –

Schedule cache check when the cog is loaded (initial startup only).
detect_bot_language –

Detect the bot's default language. For Discord bots, default to English.
command_autocomplete –

Autocomplete for the command parameter.
platform_autocomplete –

Autocomplete for the platform parameter.
language_autocomplete –

Autocomplete for the language parameter.
slash_tldr –

Show a TLDR page for a CLI command.
get_config –

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

Show a TLDR page for a CLI command. If spaces are required, use hyphens instead.
__repr__ –

Return a string representation of the cog instance.
unload_if_missing_config –

Check if required configuration is missing and log warning.

Attributes:

db (DatabaseCoordinator) –

Get the database coordinator for accessing database controllers.

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_load `async` ¶

Python

cog_load()

Schedule cache check when the cog is loaded (initial startup only).

_initialize_cache_async `async` ¶

Python

_initialize_cache_async()

Asynchronously initialize TLDR cache after event loop is ready.

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

detect_bot_language ¶

Python

detect_bot_language() -> str

Detect the bot's default language. For Discord bots, default to English.

Returns:

str –

The language code (always "en" for this bot).

command_autocomplete `async` ¶

Python

command_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]

Autocomplete for the command parameter.

Returns:

list[Choice[str]] –

List of command choices for autocomplete.

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

platform_autocomplete `async` ¶

Python

platform_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]

Autocomplete for the platform parameter.

Returns:

list[Choice[str]] –

List of platform choices for autocomplete.

language_autocomplete `async` ¶

Python

language_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]

Autocomplete for the language parameter.

Returns:

list[Choice[str]] –

List of language choices for autocomplete.

slash_tldr `async` ¶

Python

slash_tldr(
    interaction: Interaction,
    command: str,
    platform: str | None = None,
    language: str | None = None,
    show_short: bool | None = False,
    show_long: bool | None = True,
    show_both: bool | None = False,
) -> None

Show a TLDR page for a CLI 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.

prefix_tldr `async` ¶

Python

prefix_tldr(ctx: Context[Tux], command: str, *, flags: TldrFlags) -> None

Show a TLDR page for a CLI command. If spaces are required, use hyphens instead.

Parameters:

ctx (Context[Tux]) –

The context of the command.
command (str) –

The command to look up (e.g. tar, git-commit, etc).
flags (TldrFlags) –

The flags for the command. (platform: str | None, language: str | None, show_short: bool, show_long: bool, show_both: bool)

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.

_handle_tldr_command_slash `async` ¶

Python

_handle_tldr_command_slash(
    interaction: Interaction,
    command_name: str,
    platform: str | None = None,
    language: str | None = None,
    show_short: bool = False,
    show_long: bool = True,
    show_both: bool = False,
) -> None

Handle the TLDR command for slash commands.

_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_tldr_command_prefix `async` ¶

Python

_handle_tldr_command_prefix(
    ctx: Context[Tux],
    command_name: str,
    platform: str | None = None,
    language: str | None = None,
    show_short: bool = False,
    show_long: bool = True,
    show_both: bool = False,
) -> None

Handle the TLDR command for prefix commands.

Functions¶

setup `async` ¶

Python

setup(bot: Tux) -> None

Set up the Tldr cog.

Parameters:

bot (Tux) –

The bot instance to add the cog to.

tldr ¶

Classes¶

Tldr ¶

Attributes¶

db property ¶

Functions¶

cog_load async ¶

_initialize_cache_async async ¶

_setup_command_usage ¶

detect_bot_language ¶

command_autocomplete async ¶

_generate_usage ¶

platform_autocomplete async ¶

language_autocomplete async ¶

slash_tldr async ¶

get_config ¶

prefix_tldr async ¶

__repr__ ¶

unload_if_missing_config ¶

_handle_tldr_command_slash async ¶

_unload_self async ¶

_handle_tldr_command_prefix async ¶

Functions¶

setup async ¶

db `property` ¶

cog_load `async` ¶

_initialize_cache_async `async` ¶

command_autocomplete `async` ¶

platform_autocomplete `async` ¶

language_autocomplete `async` ¶

slash_tldr `async` ¶

prefix_tldr `async` ¶

repr ¶

_handle_tldr_command_slash `async` ¶

_unload_self `async` ¶

_handle_tldr_command_prefix `async` ¶

setup `async` ¶