format_codes

FormatCodes

This class includes methods to easily transform formatting codes to ANSI and use them for pretty console output.

The Easy Formatting

First, let's take a look at a small example of what a highly styled print string with formatting could look like using this module:

This here is just unformatted text. [b|u|br:blue](Next we have text that is bright blue + bold + underlined.)\n
[#000|bg:#F67](Then there's also black text with a red background.) And finally the ([i](boring)) plain text again.

How all of this exactly works is explained in the sections below. 🠫

---

Formatting Codes and Keys

In this module, you can apply styles and colors using simple formatting codes. These formatting codes consist of one or multiple different formatting keys in between square brackets.

If a formatting code is placed in a print-string, the formatting of that code will be applied to everything behind it until its formatting is reset. If applying multiple styles and colors in the same place, instead of writing the formatting keys all into separate brackets (e.g. [x][y][z]), they can also be put in a single pair of brackets, separated by pipes (e.g. [x|y|z]).

A list of all possible formatting keys can be found under all possible formatting keys.

---

Auto Resetting Formatting Codes

Certain formatting can automatically be reset, behind a certain amount of text, just like shown in the following example:

This is plain text, [br:blue](which is bright blue now.) Now it was automatically reset to plain again.

This will only reset formatting codes, that have a specific reset (listed below, under all possible formatting keys). That means if you use it where another formatting is already applied, that formatting is still there after the automatic reset:

[cyan]This is cyan text, [dim](which is dimmed now.) Now it's not dimmed any more but still cyan.

If you want to ignore the auto-reset functionality of () brackets, you can put a / or \\ between them and the formatting code:

[cyan]This is cyan text, [u]\\(which is underlined now.) And now it is still underlined and cyan.

You can also escape formatting codes themselves by putting a / or \\ at the beginning, inside the square brackets:

This is a formatting code: [br:green]([\\b|#000|bg:br:green])\n
And here's what it looks like: [b|#000|bg:br:green]Sample text.

---

All possible Formatting Keys

• RGB Colors:
  Change the text color directly with an RGB color inside the square brackets. (With or without rgb() brackets doesn't matter.)
  Examples:
  • [rgb(115, 117, 255)]
  • [(255, 0, 136)]
  • [255, 0, 136]
• HEX Colors:
  Change the text color directly with a HEX color inside the square brackets. (Whether the RGB or RRGGBB HEX format is used, and if there's a # or 0x prefix, doesn't matter.)
  Examples:
  • [0x7788FF]
  • [#7788FF]
  • [7788FF]
  • [0x78F]
  • [#78F]
  • [78F]
• Background RGB / HEX Colors:
  Change the background color directly with an RGB or HEX color inside the square brackets, using the background: BG: prefix. (Same RGB / HEX formatting code rules as for text color.)
  Examples:
  • [background:rgb(115, 117, 255)]
  • [BG:(255, 0, 136)]
  • [background:#7788FF]
  • [BG:#78F]
• Standard Console Colors:
  Change the text color to one of the standard console colors by just writing the color name in the square brackets.
  • [black]
  • [red]
  • [green]
  • [yellow]
  • [blue]
  • [magenta]
  • [cyan]
  • [white]
• Bright Console Colors:
  Use the prefix bright: BR: to use the bright variant of the standard console color.
  Examples:
  • [bright:black] [BR:black]
  • [bright:red] [BR:red]
  • ...
• Background Console Colors:
  Use the prefix background: BG: to set the background to a standard console color. (Not all consoles support bright standard colors.)
  Examples:
  • [background:black] [BG:black]
  • [background:red] [BG:red]
  • ...
• Bright Background Console Colors:
  Combine the prefixes background: / BG: and bright: / BR: to set the background to a bright console color. (The order of the prefixes doesn't matter.)
  Examples:
  • [background:bright:black] [BG:BR:black]
  • [background:bright:red] [BG:BR:red]
  • ...
• Text Styles:
  Use the built-in text formatting to change the style of the text. There are long and short forms for each formatting code. (Not all consoles support all text styles.)
  • [bold] [b]
  • [dim]
  • [italic] [i]
  • [underline] [u]
  • [inverse] [invert] [in]
  • [hidden] [hide] [h]
  • [strikethrough] [s]
  • [double-underline] [du]
• Specific Reset:
  Use these reset codes to remove a specific style, color or background. Again, there are long and short forms for each reset code.
  • [_bold] [_b]
  • [_dim]
  • [_italic] [_i]
  • [_underline] [_u]
  • [_inverse] [_invert] [_in]
  • [_hidden] [_hide] [_h]
  • [_strikethrough] [_s]
  • [_double-underline] [_du]
  • [_color] [_c]
  • [_background] [_bg]
• Total Reset:
  This will reset all previously applied formatting codes.
  • [_]

---

Additional Formatting Codes when a default_color is set

1. [*] resets everything, just like [_], but the text color will remain in default_color (if no default_color is set, it resets everything, exactly like [_])
2. [*color] will reset the text color, just like [_color], but then also make it default_color (if no default_color is set, both are treated as invalid formatting codes)
3. [default] will just color the text in default_color (if no default_color is set, it's treated as an invalid formatting code)
4. [background:default] [BG:default] will color the background in default_color (if no default_color is set, both are treated as invalid formatting codes)

Unlike the standard console colors (under all possible formatting keys), the default color can be changed by using the following modifiers:

• [l] will lighten the default_color text by brightness_steps%
• [ll] will lighten the default_color text by 2 × brightness_steps%
• [lll] will lighten the default_color text by 3 × brightness_steps%
• ... etc. Same thing for darkening:
• [d] will darken the default_color text by brightness_steps%
• [dd] will darken the default_color text by 2 × brightness_steps%
• [ddd] will darken the default_color text by 3 × brightness_steps%
• ... etc. Per default, you can also use + and - to get lighter and darker default_color versions. All of these lighten/darken formatting codes are treated as invalid if no default_color is set.

print()

This is a print function, whose print values can be formatted using formatting codes.
Params:

• *values: object the values to format and print
• default_color: Optional[Rgba | Hexa] = None the default text color to use if no other text color was applied
• brightness_steps: int = 20 the amount (%) to lighten/darken the default color after a [l] or [d] formatting code
• sep: str = " " the separator to join the *values with
• end: str = "\n" the string to print after the *values
• flush: bool = True whether to flush the output

Returns: no return value

input()

This is an input function, whose input prompt can be formatted using formatting codes.
Params:

• prompt: object = "" the prompt to display
• default_color: Optional[Rgba | Hexa] = None the default text color to use if no other text color was applied
• brightness_steps: int = 20 the amount (%) to lighten/darken the default color after a [l] or [d] formatting code
• reset_ansi: bool = False whether the ANSI formatting should be reset after the user confirms the input and the program continues to run

Returns: the user's entry as a string

to_ansi()

This method converts the formatting codes in a string to ANSI codes.
Params:

• string: str the string that contains the formatting codes to convert
• default_color: Optional[Rgba | Hexa] = None the default text color to use if no other text color was applied
• brightness_steps: int = 20 the amount (%) to lighten/darken the default color after a [l] or [d] formatting code

Returns: the string with the valid formatting codes converted to ANSI codes

escape_ansi()

This method escapes all ANSI codes in a string, so they are visible when output to the console.
Param: ansi_string: str the string that contains the ANSI codes to escape
Returns: the string with the ANSI codes escaped

remove_ansi()

This method removes all ANSI codes from a string.
Params:

• ansi_string: str the string that contains the ANSI codes to remove
• get_removals: bool = False whether to additionally return a tuple with the removed codes and their removal position
• _ignore_linebreaks: bool = False whether to ignore line breaks for the removal positions

Returns: the cleaned string or a tuple with the cleaned string and the removals

Removals:

If get_removals is true, the ANSI removals will be returned as a tuple.
Inside the tuple is another tuple for each removed ANSI code. This tuple contains the removal position and the removed ANSI code.

Example:

If we use the method on the string "\x1b[1mHello \x1b[0mWorld!", the returned tuple from the method would look like this:

(
    # CLEANED STRING
    "Hello World!",
    # REMOVED CODES
    (
        (0, "\x1b[1m"),
        (6, "\x1b[0m"),
    ),
)

remove_formatting()

This method removes all formatting codes from a string.
Params:

• string: str the string that contains the formatting codes to remove
• get_removals: bool = False whether to additionally return a tuple with the removed codes and their removal position
• _ignore_linebreaks: bool = False whether to ignore line breaks for the removal positions

Returns: the cleaned string or a tuple with the cleaned string and the removals

Removals:

If get_removals is true, the formatting code removals (already translated to ANSI codes) will be returned as a tuple.
Inside the tuple is another tuple for each removed formatting code. This tuple contains the removal position and the removed ANSI code.

Example:

If we use the method on the string "[br:red](Hello) [b]World!", the returned tuple from the method would look like this:

(
    # CLEANED STRING
    "Hello World!",
    # REMOVED CODES
    (
        (0, "\x1b[91m"),
        (5, "\x1b[39m"),  # AUTO RESET CODE
        (6, "\x1b[1m"),
    ),
)