Skip to content

tldr

TLDR Pages Client Wrapper.

A pure Python implementation of the TLDR client specification v2.3, providing command documentation lookup with proper caching, localization, and platform support. This wrapper contains no Discord dependencies and can be used independently.

Classes:

  • TldrClient –

    Core TLDR client functionality for fetching and managing pages.

Classes

TldrClient

Core TLDR client functionality for fetching and managing pages.

Implements the TLDR client specification v2.3 with proper caching, platform detection, and language fallback mechanisms.

Methods:

Functions

normalize_page_name staticmethod
Python
normalize_page_name(name: str) -> str

Normalize command name according to TLDR specification.

Parameters:

  • name (str) –

    Raw command name that may contain spaces or mixed case.

Returns:

  • str –

    Normalized command name: lowercase, dash-separated, trimmed.

Examples:

Python Console Session
>>> TldrClient.normalize_page_name("git status")
"git-status"
>>> TldrClient.normalize_page_name("GyE D3")
"gye-d3"
get_cache_file_path staticmethod
Python
get_cache_file_path(command: str, platform: str, language: str) -> Path

Generate the file system path for a cached TLDR page.

Parameters:

  • command (str) –

    Normalized command name.

  • platform (str) –

    Target platform (linux, osx, windows, etc.).

  • language (str) –

    Language code (en, es, fr, etc.).

Returns:

  • Path –

    Full path to the cached page file.

have_recent_cache staticmethod
Python
have_recent_cache(command: str, platform: str, language: str) -> bool

Check if a recent cached version of a page exists.

Parameters:

  • command (str) –

    Command name to check.

  • platform (str) –

    Platform to check.

  • language (str) –

    Language to check.

Returns:

  • bool –

    True if cached file exists and is within MAX_CACHE_AGE_HOURS.

load_page_from_cache staticmethod
Python
load_page_from_cache(command: str, platform: str, language: str) -> str | None

Load a TLDR page from local cache.

Parameters:

  • command (str) –

    Command name.

  • platform (str) –

    Platform name.

  • language (str) –

    Language code.

Returns:

  • str | None –

    Page content if available, None if not found or on error.

store_page_to_cache staticmethod
Python
store_page_to_cache(page: str, command: str, platform: str, language: str) -> None

Store a TLDR page to local cache.

Parameters:

  • page (str) –

    Page content to store.

  • command (str) –

    Command name.

  • platform (str) –

    Platform name.

  • language (str) –

    Language code.

detect_platform staticmethod
Python
detect_platform() -> str

Detect the default platform for Discord bot context.

Returns:

  • str –

    Platform identifier, defaults to 'linux' for container environments.

get_language_priority staticmethod
Python
get_language_priority(user_language: str | None = None) -> list[str]

Get prioritized list of languages for Discord bot context.

Parameters:

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

    User-specified language preference.

Returns:

  • list[str] –

    Ordered list of languages to try, always ending with 'en'.

get_platform_priority staticmethod
Python
get_platform_priority(user_platform_input: str | None = None) -> list[str]

Determine platform search order based on user input and TLDR spec.

Parameters:

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

    User-specified platform preference.

Returns:

  • list[str] –

    Ordered list of platforms to search, following TLDR specification.

Notes

Implementation follows TLDR spec v2.3: - If user specifies "common", only return "common" - Otherwise: [user_platform, detected_platform, common, all_other_platforms]

fetch_tldr_page staticmethod
Python
fetch_tldr_page(
    command: str, languages: list[str], platform_preference: str | None = None
) -> tuple[str, str] | None

Fetch a TLDR page with platform priority and language fallback.

Parameters:

  • command (str) –

    Normalized command name to fetch.

  • languages (list[str]) –

    Ordered list of languages to try.

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

    User's platform preference.

Returns:

  • tuple[str, str] | None –

    Tuple of (page_content, found_platform) if successful, None if not found.

Notes

Follows TLDR spec priority: platform takes precedence over language. Tries cache first, then remote fetch with automatic caching.

list_tldr_commands staticmethod
Python
list_tldr_commands(
    language: str = "en", platform_filter: str | None = "linux"
) -> list[str]

List available TLDR commands for a given language and platform filter.

Parameters:

  • language (str, default: 'en' ) –

    Language code to search.

  • platform_filter (str | None, default: 'linux' ) –

    Platform to filter by. If None, searches linux + common platforms.

Returns:

  • list[str] –

    Sorted list of available command names.

parse_placeholders staticmethod
Python
parse_placeholders(
    line: str,
    show_short: bool = False,
    show_long: bool = True,
    show_both: bool = False,
    highlight: bool = True,
) -> str

Parse and format placeholder text in TLDR pages.

Parameters:

  • line (str) –

    Line containing TLDR placeholder syntax.

  • show_short (bool, default: False ) –

    Show only short options for placeholders.

  • show_long (bool, default: True ) –

    Show only long options for placeholders.

  • show_both (bool, default: False ) –

    Show both short and long options.

  • highlight (bool, default: True ) –

    Whether to apply highlighting markup.

Returns:

  • str –

    Processed line with placeholders resolved.

_process_description_lines staticmethod
Python
_process_description_lines(
    lines: list[str], i: int, show_short: bool, show_long: bool, show_both: bool
) -> tuple[list[str], int]

Process consecutive description lines starting with '>'.

Returns:

  • tuple[list[str], int] –

    Tuple of (parsed description lines, updated line index).

_process_command_examples staticmethod
Python
_process_command_examples(
    lines: list[str], i: int, show_short: bool, show_long: bool, show_both: bool
) -> tuple[list[str], int]

Process command examples and descriptions.

Returns:

  • tuple[list[str], int] –

    Tuple of (formatted command lines, updated line index).

format_tldr_for_discord staticmethod
Python
format_tldr_for_discord(
    md: str, show_short: bool = False, show_long: bool = True, show_both: bool = False
) -> str

Format a TLDR markdown page for Discord output.

Parameters:

  • md (str) –

    Raw TLDR markdown content.

  • show_short (bool, default: False ) –

    Show only short options for placeholders.

  • show_long (bool, default: True ) –

    Show only long options for placeholders.

  • show_both (bool, default: False ) –

    Show both short and long options.

Returns:

  • str –

    Formatted content suitable for Discord display.

not_found_message staticmethod
Python
not_found_message(command: str) -> str

Generate a message for when a page is not found.

Parameters:

  • command (str) –

    Command that was not found.

Returns:

  • str –

    Formatted not found message with GitHub link.

update_tldr_cache staticmethod
Python
update_tldr_cache(language: str = 'en') -> str

Update the TLDR cache for a specific language.

Parameters:

  • language (str, default: 'en' ) –

    Language code to update cache for.

Returns:

  • str –

    Status message indicating success or failure.

Notes

Downloads from GitHub releases following TLDR spec v2.3. Replaces existing cache completely to ensure consistency.

cache_needs_update staticmethod
Python
cache_needs_update(language: str = 'en') -> bool

Check if the cache needs updating based on age.

Parameters:

  • language (str, default: 'en' ) –

    Language to check cache for.

Returns:

  • bool –

    True if cache is missing or older than MAX_CACHE_AGE_HOURS.

split_long_text staticmethod
Python
split_long_text(text: str, max_len: int = 4000) -> list[str]

Split long text into pages for Discord embeds.

Parameters:

  • text (str) –

    Text to split.

  • max_len (int, default: 4000 ) –

    Maximum length per page.

Returns:

  • list[str] –

    List of text chunks within max_len limits.