ANSI

Summary

Ingredient for working with ANSI Control Codes

Description

The ANSI ingredient exposes ANSI control codes in a simple way. ANSI codes can be used to control text color and style on compatible terminals.

Linux terminal emulators commonly support a wide subset of control codes. Particular support differs between the classic Linux console, Xterm, gnome-terminal and konsole (and the backing libraries). Some features are supported more widely than others. In particular, the text console is rather limited and will likely remain so until the systemd-based replacement is commonly used.

The terminal emulator included in Apple’s OS X supports a subset of the features (3rd party terminal emulators for OS X were not tested, contributions are welcome). In general you can treat OS X like a poor version of Linux.

The windows command prompt is the most limited environment as it only support several foreground and background colors and nothing else at all. It also has issues with Unicode (as in, it doesn’t support it at all). On Windows, usage of ANSI depends on the availability of colorama. Colorama is a third party library that wraps sys.stdout and sys.stderr, parses ANSI control codes and converts them to the corresponding Windows API calls.

Spices

This ingredient is not influenced by any spices.

Context

This ingredient adds two objects to the context:

ansi
An instance of ANSIFormatter. The object is automatically configured (disabled) when the extra control codes are undesired (stdout not attached to a terminal emulator).
aprint
The aprint() method, as a shorthand for ctx.ansi.aprint.

Command Line Arguments

This ingredient is not exposing any command line arguments.

Examples

Let’s construct a simple example. Note that typically you will use the context that is provided to you from the invoked() method of a command.

>>> from guacamole.core import Context
>>> from guacamole.ingredients import ansi
>>> ctx = Context()
>>> ansi.ANSIIngredient(enable=True).added(ctx)

The context now has the ansi object, which is an instance of ANSIFormatter.

It has some methods and properties that we’ll see below but it is also callable and darn convenient to use.

You can use the fg and bg keyword arguments to control the foreground and background text color respectively.

>>> str(ctx.ansi('red on blue', fg='red', bg='blue'))
'\x1b[31;44mred on blue\x1b[0m'

You can use keyword arguments that correspond to each of the countless sgr_ constants available in the class ANSI. Here, let’s get bold text using the sgr_bold code.

>>> str(ctx.ansi('bold text', bold=1))
'\x1b[1mbold text\x1b[0m'

In some cases you may want to use different code knowing that the output will be colorized (e.g. use color codes instead of longer text labels). You can achieve that by testing :meth`~guacamole.ingredients.ansi.ANSI.is_enabled`.

>>> # Let's disable the ANSI support for this test
>>> ansi.ANSIIngredient(enable=False).added(ctx)
>>> if ctx.ansi.is_enabled:
...     ctx.aprint('!!!', fg='red')
... else:
...     ctx.aprint('ALARM')
ALARM

Expressing colors

Guacaomle supports several styles of colors:

  • Named colors represented as strings:
    • "black"
    • "red"
    • "green"
    • "yellow"
    • "blue"
    • "magenta"
    • "cyan"
    • "white"
  • Bright variant of named colors (not repeated)
  • Indexed colors represented as an integer in range(256):
    • 0x00-0x07: standard colors (as in ESC [ 30–37 m)
    • 0x08-0x0F: high intensity colors (as in ESC [ 90–97 m)
    • 0x10-0xE7: 6 × 6 × 6 = 216 colors: 16 + 36 × r + 6 × g + b (0 ≤ r, g, b ≤ 5)
    • 0xE8-0xFF: grayscale from black to white in 24 steps
  • RGB colors represented as (r, g, b) where each component is an integer in range(256)
  • The special value "auto" which picks the complementary (readable) variant. Auto may be used in one of fg= or bg= if bg= or fg= (respectively) are using a concrete color.

Note

The actual colors behind the string-named colors vary between different terminal emulators. Sometimes the color is just slightly different. Sometimes it is just totally unrelated to the one specified in the ANSI standard.

Warning

RGB colors are not supported on Windows and OS X. They are only supported on modern terminal emulators, typically on Linux distributions.