functions ¶

Shared Utility Functions for Tux Bot.

This module contains common utility functions used throughout the Tux Discord bot, including text processing, time conversion, parameter validation, and documentation formatting utilities.

Functions:

truncate –

Truncate a string to a specified length.
strip_formatting –

Strip formatting from a string.
parse_time_string –

Convert a string representation of time into a datetime.timedelta object.
convert_to_seconds –

Convert a formatted time string with the formats Mwdhms.
seconds_to_human_readable –

Convert a number of seconds into a human readable string.
is_optional_param –

Check if a parameter is optional.
get_matching_string –

Match the given argument to a specific string based on common usage.
generate_usage –

Generate the usage string for a command.
docstring_parameter –

Parameterize docstrings with format-style substitution.

Functions¶

truncate ¶

Python

truncate(text: str, length: int) -> str

Truncate a string to a specified length.

If the string is longer than the specified length, it will be truncated and an ellipsis will be appended. Otherwise, the original string is returned.

Parameters:

text (str) –

The string to truncate.
length (int) –

The maximum length of the string.

Returns:

str –

The truncated string.

strip_formatting ¶

Python

strip_formatting(content: str) -> str

Strip formatting from a string.

Parameters:

content (str) –

The string to strip formatting from.

Returns:

str –

The string with formatting stripped.

parse_time_string ¶

Python

parse_time_string(time_str: str) -> timedelta

Convert a string representation of time into a datetime.timedelta object.

Parameters:

time_str (str) –

The string representation of time to convert. (e.g., '60s', '1m', '2h', '10d')

Returns:

timedelta –

The timedelta object representing the time string.

Raises:

ValueError –

If the time format is invalid.

convert_to_seconds ¶

Python

convert_to_seconds(time_str: str) -> int

Convert a formatted time string with the formats Mwdhms.

Parameters:

time_str (str) –

The formatted time string to convert to total seconds.

Returns:

int –

The total seconds from the formatted time string. Returns 0 if the format is invalid.

seconds_to_human_readable ¶

Python

seconds_to_human_readable(seconds: int) -> str

Convert a number of seconds into a human readable string.

Parameters:

seconds (int) –

The number of seconds to convert

Returns:

str –

A string that breaks the time down by months, weeks, days, hours, minutes, and seconds.

is_optional_param ¶

Python

is_optional_param(param: Parameter) -> bool

Check if a parameter is optional.

Parameters:

param (Parameter) –

The parameter to check.

Returns:

bool –

True if the parameter is optional, False otherwise.

get_matching_string ¶

Python

get_matching_string(arg: str) -> str

Match the given argument to a specific string based on common usage.

Parameters:

arg (str) –

The argument to match.

Returns:

str –

The matching string, or None if no match is found.

generate_usage ¶

Python

generate_usage(
    command: Command[Any, Any, Any], flag_converter: type[FlagConverter] | None = None
) -> str

Generate the usage string for a command.

Parameters:

command (Command[Any, Any, Any]) –

The command to generate the usage string for.
flag_converter (type[FlagConverter] | None, default: None ) –

The flag converter to use.

Returns:

str –

The usage string for the command.

docstring_parameter ¶

Python

docstring_parameter(*sub: Any) -> Any

Parameterize docstrings with format-style substitution.

Parameters:

*sub (Any, default: () ) –

Substitution values to use in the docstring formatting.

Returns:

Any –

The decorator function.