`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

r (Union[str, int])
g (Union[str, int])
b (Union[str, int])
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_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

consolekit.terminal_colours

`consolekit.terminal_colours`