ANSI Escape Codes#
Colorist uses ANSI escape codes to style text in the terminal. This page explains how ANSI escape codes work, and how to use them in your own code.
What Are ANSI Escape Codes?#
ANSI escape sequences were introduced in the 1970s as a standard to style text terminals with color, font styling, and other options. They are supported by most modern terminals in operating systems like Windows, macOS, and Linux.
They always start with \x1b
, \e
, or \033
depending on the operating system or programming language. Technically this inserts byte 27 into a string, which is equivalent to 0x1b
and the ESC
key when you look at an ASCII table. Hence the name.
Though ANSI escape sequences appear in a string as multiple characters, they are in reality interpreted by the terminal as a single command. For example:
\x1b[31m
: Change the color to red\x1b[0m
: Reset any styling
How to apply this in a print command:
And yet, the characters of the sequences are hidden in the terminal output apart from the color change:
% I want red color inside this paragraph
Humanised Sequences#
This is also why it's convenient to use Colorist instead of manually writing raw ANSI escape codes. The Color
class will generate the ANSI escape sequences and keep the code readable. This example generates the same terminal output as above:
from colorist import Color
print(f"I want {Color.RED}red{Color.OFF} color inside this paragraph")
Standard Colors#
Color Codes and Building Blocks#
All ANSI escape sequences follow the same pattern. For example, the sequence \x1b[31m
can be broken down into:
\x1b[
: Starts sequence, also called the Control Sequence Introducer (CSI)31
: The color codem
: Ends sequence, also called the Select Graphic Rendition (SGR)
There are 8 standard colors and 8 bright colors – 16 in total. The bright colors are the same as the standard colors, yet with a higher intensity, and each color can be in the foreground (i.e. as text) or background.
The 8 colors are simply black and white, plus the 6 colors of the rainbow. Firstly, the three primary colors red, green, and blue. Then the secondary colors yellow, magenta, and cyan:
Code | Color | Example |
---|---|---|
0 | Black | |
1 | Red | |
2 | Green | |
3 | Yellow | |
4 | Blue | |
5 | Magenta | |
6 | Cyan | |
7 | White |
Each color then needs to be prepended by a foreground or background option. When combining the two codes – simply replace the underscore _
with the missing color code – 34
for example is blue text, and 44
is blue background:
Code | Placement | Intensity |
---|---|---|
3_ | Text | Standard |
4_ | Background | Standard |
9_ | Text | Bright |
10_ | Background | Bright |
Foreground Text and Background Colors#
To apply different color and styling options, simply replace the two underscores __
in \x1b[__m
with any of the following color codes:
Color | Example | Text | Background | Bright Example | Bright Text | Bright Background |
---|---|---|---|---|---|---|
Black | 30 | 40 | 90 | 100 | ||
Red | 31 | 41 | 91 | 101 | ||
Green | 32 | 42 | 92 | 102 | ||
Yellow | 33 | 43 | 93 | 103 | ||
Blue | 34 | 44 | 94 | 104 | ||
Magenta | 35 | 45 | 95 | 105 | ||
Cyan | 36 | 46 | 96 | 106 | ||
White | 37 | 47 | 97 | 107 | ||
Default | 39 | 49 | 99 | 109 | ||
Reset | 0 | 0 | 0 | 0 |
Tip
Remember to use \x1b[0m
every time you want to revert back to the default terminal text style. Otherwise, any color or styling may spill over and into other terminal messages.
When using Colorist, you can for example use Color.OFF
to reset the terminal text style.
Effects#
For effects, the codes are. And as before, replace the two underscores __
in \x1b[__m
with any of the following color codes:
Effect | On | Off | Example |
---|---|---|---|
Bold | 1 | 21 | This is BOLD |
Dim | 2 | 22 | This is DIMMED |
Underline | 4 | 24 | This is UNDERLINED |
Blink | 5 | 25 | This is BLINKING |
Reverse | 7 | 27 | This is REVERSED |
Hide | 8 | 28 | This is HIDDEN |
Different Color Schemes in Different Terminals
Most terminals apply different color schemes so \x1b[31m
or Color.RED
won't produce the exact same screen color of red. Some straight, others with an orange tint. For further reading, refer to this list of common terminals and their color schemes.
Non-Standard Colors#
To have more control of the colors or want to be more creative, you aren't limited to 16 colors. In addition, the escape codes can be used with an extended 256 color palette or the RGB color space.
Not All Terminals Support Extended Color Palettes
While most terminals support the standard ANSI color sequences, far from all support the extended 256 or RGB color space. For example, the Windows Command Prompt does not support RGB colors while the Windows Terminal does support RGB colors.
Refer to the terminal's documentation to see if it supports extended color palettes.
Extended 256 Colors#
The extended palette of 256 colors is a 6x6x6 color cube, with 216 colors, plus 24 shades of gray. The color cube is made up of 6 levels of red, green, and blue, respectively. The color cube is then combined with the 24 shades of gray to make up the 256 colors.
It works both with foreground text and background colors. Simply replace the two underscores __
with any number from 0
to 255
:
Code | Placement |
---|---|
\x1b[38;5;__m | Text |
\x1b[48;5;__m | Background |
For example, \x1b[38;5;243m
is a light gray foreground text color, and \x1b[48;5;243m
is a light gray background color.
RGB Colors#
The RGB color space represents a much broader array of colors. Simply use any number from 0
to 255
to set each of the red r
, green g
, and blue b
colors in the sequences 38;2;r;g;b
for text color and 38;2;r;g;b
for background color:
Code | Placement |
---|---|
\x1b[38;2;r;g;bm | Text |
\x1b[48;2;r;g;bm | Background |
For example, \x1b[38;2;255;0;0m
is a red foreground text color, and \x1b[48;2;255;0;0m
is a red background color.
In Colorist, the RGB color space is used to furthermore support definition of colors as HSL or Hex.