consolekit.terminal_colours

Functions for adding ANSI character codes to terminal print statements.

Classes:

AnsiFore(*args, **kwargs)

ANSI Colour Codes for foreground colour.

AnsiBack(*args, **kwargs)

ANSI Colour Codes for background colour.

AnsiStyle(*args, **kwargs)

ANSI Colour Codes for text style.

AnsiCursor()

Provides methods to control the cursor.

Fore

alias of consolekit.terminal_colours.AnsiFore

Back

alias of consolekit.terminal_colours.AnsiBack

Style

alias of consolekit.terminal_colours.AnsiStyle

AnsiCodes(*args, **kwargs)

Abstract base class for ANSI Codes.

Colour(style, stack, List[str]], reset)

An ANSI escape sequence representing a colour.

Data:

ColourTrilean

Represents the True/False/None state of colour options.

Functions:

resolve_color_default([color])

Helper to get the default value of the color flag.

strip_ansi(value)

Strip ANSI colour codes from the given string to return a plaintext output.

class AnsiFore(*args, **kwargs)[source]

Bases: AnsiCodes

ANSI Colour Codes for foreground colour.

The colours can be used as a context manager, a string, or a function.

Valid values are:

  • BLACK

  • RED

  • GREEN

  • YELLOW

  • BLUE

  • MAGENTA

  • CYAN

  • WHITE

  • RESET

  • LIGHTBLACK_EX

  • LIGHTRED_EX

  • LIGHTGREEN_EX

  • LIGHTYELLOW_EX

  • LIGHTBLUE_EX

  • LIGHTMAGENTA_EX

  • LIGHTCYAN_EX

  • LIGHTWHITE_EX

This class is also available under the shorter alias Fore.

class AnsiBack(*args, **kwargs)[source]

Bases: AnsiCodes

ANSI Colour Codes for background colour.

The colours can be used as a context manager, a string, or a function.

Valid values are:

  • BLACK

  • RED

  • GREEN

  • YELLOW

  • BLUE

  • MAGENTA

  • CYAN

  • WHITE

  • RESET

  • LIGHTBLACK_EX

  • LIGHTRED_EX

  • LIGHTGREEN_EX

  • LIGHTYELLOW_EX

  • LIGHTBLUE_EX

  • LIGHTMAGENTA_EX

  • LIGHTCYAN_EX

  • LIGHTWHITE_EX

This class is also available under the shorter alias Back.

class AnsiStyle(*args, **kwargs)[source]

Bases: AnsiCodes

ANSI Colour Codes for text style.

Valid values are:

  • BRIGHT

  • DIM

  • NORMAL

Additionally, AnsiStyle.RESET_ALL can be used to reset the foreground and background colours as well as the text style.

This class is also available under the shorter alias Style.

class AnsiCursor[source]

Bases: object

Provides methods to control the cursor.

Methods:

UP([n])

Moves the cursor up n lines.

DOWN([n])

Moves the cursor down n lines.

FORWARD([n])

Moves the cursor forward (right) n lines.

BACK([n])

Moves the cursor backward (left) n lines.

POS([x, y])

Moves the cursor to the given position.

HIDE()

Hides the cursor.

SHOW()

Shows the cursor.

UP(n=1)[source]

Moves the cursor up n lines.

Parameters

n (int) – Default 1.

Return type

str

DOWN(n=1)[source]

Moves the cursor down n lines.

Parameters

n (int) – Default 1.

Return type

str

FORWARD(n=1)[source]

Moves the cursor forward (right) n lines.

Parameters

n (int) – Default 1.

Return type

str

BACK(n=1)[source]

Moves the cursor backward (left) n lines.

Parameters

n (int) – Default 1.

Return type

str

POS(x=1, y=1)[source]

Moves the cursor to the given position.

Parameters
  • x (int) – Default 1.

  • y (int) – Default 1.

Return type

str

HIDE()[source]

Hides the cursor.

New in version 0.7.0.

Return type

str

SHOW()[source]

Shows the cursor.

New in version 0.7.0.

Return type

str

Fore

alias of consolekit.terminal_colours.AnsiFore

Back

alias of consolekit.terminal_colours.AnsiBack

Style

alias of consolekit.terminal_colours.AnsiStyle

class AnsiCodes(*args, **kwargs)[source]

Bases: ABC

Abstract base class for ANSI Codes.

class Colour(style: str, stack: Union[Deque[str], List[str]], reset: str)[source]

Bases: str

An ANSI escape sequence representing a colour.

The colour can be used as a context manager, a string, or a function.

Parameters
  • style (str) – Escape sequence representing the style.

  • stack (List[str]) – The stack to place the escape sequence on.

  • reset (str) – The escape sequence to reset the style.

Methods:

__call__(text)

Returns the given text in this colour.

from_code(code[, background])

Returns a Colour to create coloured text.

from_256_code(code[, background])

Returns a Colour to create 256-colour text.

from_rgb(r, g, b[, background])

Returns a Colour to create 24-bit coloured text.

from_hex(hex_colour[, background])

Returns a Colour to create 24-bit coloured text.

__call__(text)[source]

Returns the given text in this colour.

Return type

str

classmethod from_code(code, background=False)[source]

Returns a Colour to create coloured text.

The colour can be reset using Fore.RESET or Back.RESET.

New in version 0.9.0.

Parameters
  • code (Union[str, int]) – A 3- or 4- bit ANSI colour code.

  • background (bool) – Whether to set the colour for the background. Default False.

Return type

Colour

Note

The background option only influences the reset value and the stack used. It will not handle conversion of foreground codes to background codes.

classmethod from_256_code(code, background=False)[source]

Returns a Colour to create 256-colour text.

The colour can be reset using Fore.RESET or Back.RESET.

New in version 0.9.0.

Note

Not all terminals support 256-colour mode.

Parameters
  • code (Union[str, int]) – A 256-colour ANSI code.

  • background (bool) – Whether to set the colour for the background. Default False.

Return type

Colour

Note

The background option only influences the reset value and the stack used. It will not handle conversion of foreground codes to background codes.

classmethod from_rgb(r, g, b, background=False)[source]

Returns a Colour to create 24-bit coloured text.

The colour can be reset using Fore.RESET or Back.RESET.

New in version 0.9.0.

Note

Not all terminals support 24-bit colours.

Parameters
Return type

Colour

Note

The background option only influences the reset value and the stack used. It will not handle conversion of foreground codes to background codes.

classmethod from_hex(hex_colour, background=False)[source]

Returns a Colour to create 24-bit coloured text.

The colour can be reset using Fore.RESET or Back.RESET.

New in version 0.9.0.

Note

Not all terminals support 24-bit colours.

Parameters
  • hex_colour (str) – The hex colour code.

  • background (bool) – Whether to set the colour for the background. Default False.

Return type

Colour

Note

The background option only influences the reset value and the stack used. It will not handle conversion of foreground codes to background codes.

ColourTrilean

Represents the True/False/None state of colour options.

New in version 0.8.0.

Alias of Optional[bool]

resolve_color_default(color=None)[source]

Helper to get the default value of the color flag.

If a value is passed it is returned unchanged, otherwise it’s looked up from the current context.

If the environment variable PYCHARM_HOSTED is 1 (which is the case if running in PyCharm) the output will be coloured by default.

If the environment variable NO_COLOR is 1 the output will not be coloured by default. See https://no-color.org/ for more details. This variable takes precedence over PYCHARM_HOSTED.

If no value is passed in, there is no context, and neither environment variable is set, None is returned.

Changed in version 1.3.0:
  • Added support for the NO_COLOR environment variable.

  • Only uses a value from the click context (Context.color) if it is not None. Otherwise falls back to checking the environment variables.

Parameters

color (Optional[bool]) – Default None.

Return type

Optional[bool]

strip_ansi(value)[source]

Strip ANSI colour codes from the given string to return a plaintext output.

Parameters

value (str)

Return type

str