wetsuite.helpers.shellcolor

module documentation

(should arguably be in extras) Eases production of colors in the terminal, mostly for a few command line debug tools.

Tries to only produce color escapes when the terminal supports it: (whether we detect we are in a tty, and TERM suggests we are color-capable). You can override that in manual checks with the arguments on guess_color_support(), You can override that in the automatic checks (necessary for the convenience function) by setting the globals default_forceifnoterm and/or default_forceifnotty)

Currently provides some convenience functions for a single foreground color, meant to be used like: :

    import helpers.shellcolor as sc
    print( sc.red('shown as red') )

Or without checking it is suported: :

    print( sc.BRIGHT+sc.BLUE+sc.UNDERLINE+'shown bright blue'+sc.RESET )

Tries to only add the control codes when the context seems capable of it. (TODO: this needs some tuning) check whether we are in a tty, and whether the TERM suggests we are color-capable. You can override that in manual checks with the arguments on guess_color_support(), You can override that in the automatic checks (necessary for the convenience function) by setting the globals default_forceifnoterm and/or default_forceifnotty

Function	`_add_color_if_supported`	Undocumented
Function	`_format_segment`	Helper for cformat() (NOW REDUNDANT?) e.g. :
Function	`_percent_parse`	Will rewrite any format strings with a width to have more width by the amount specified.
Function	`_strip_escapes_if_not_supported`	Undocumented
Function	`bgblack`	add color on string if supported
Function	`bgblue`	add color on string if supported
Function	`bgcyan`	add color on string if supported
Function	`bggreen`	add color on string if supported
Function	`bgmagenta`	add color on string if supported
Function	`bgorange`	add color on string if supported
Function	`bgred`	add color on string if supported
Function	`bgyellow`	add color on string if supported
Function	`black`	add color on string if supported
Function	`blend`	add an RGB color around a string that is some fraction between two colors Note this only really makes sense on true-color terminals.
Function	`blue`	add color on string if supported
Function	`brightblack`	add color on string if supported
Function	`brightblue`	add color on string if supported
Function	`brightcyan`	add color on string if supported
Function	`brightgray`	add color on string if supported
Function	`brightgreen`	add color on string if supported
Function	`brightgrey`	add color on string if supported
Function	`brightmagenta`	add color on string if supported
Function	`brightred`	add color on string if supported
Function	`brightyellow`	add color on string if supported
Function	`cformat`	EXPERIMENT: A percent formatter that is aware that color escapes have zero display width, so you can feed it strings with color escapes and avoid some magic reindenting weirdness.
Function	`clearscreen`	output clear-screen code, if supported
Function	`closest_from_rgb255`	Given a r,g,b color (0..255 scale), pick the closest shell color (returns the function)
Function	`color_degree`	color string s according to where v lies between fromv and tov, ...from a discrete set of colors (if you wanted something more gradual, perhaps use redgreen (if you like the fixed colors), or do it yourself with e...
Function	`cyan`	add color on string if supported
Function	`darkgray`	add color on string if supported
Function	`darkgrey`	add color on string if supported
Function	`default`	add "default colors" code before string if supported
Function	`gray`	add color on string if supported
Function	`green`	add color on string if supported
Function	`grey`	add color on string if supported
Function	`guess_color_support`	Tries to guess whether we can use color code output.
Function	`hash_color`	return string wrapped in a (non-black basic shell) color (and RESET after) based on (a hash of) the string
Function	`magenta`	add color on string if supported
Function	`orange`	add color on string if supported
Function	`real_len`	Returns 2-tuple:
Function	`red`	add color on string if supported
Function	`redgreen`	turns a fraction in 0..1 to red..green
Function	`reset`	add color reset code before string if supported
Function	`supported`	return what guess_color_support() estimated. (if that was not run yet, do that before returning)
Function	`true_colf`	true-color escape from 0..255 r,g,b
Function	`truncate_real_len`	Truncate a string after so-many real characters. Written for "truncate colored text according to the terminal width" functionality.
Function	`tty_size`	fetches current terminal size
Function	`white`	add color on string if supported
Function	`yellow`	add color on string if supported
Constant	`BGBLACK`	Undocumented
Constant	`BGBLUE`	Undocumented
Constant	`BGBRIGHTGRAY`	Undocumented
Constant	`BGCYAN`	Undocumented
Constant	`BGGREEN`	Undocumented
Constant	`BGMAGENTA`	Undocumented
Constant	`BGRED`	Undocumented
Constant	`BGYELLOW`	Undocumented
Constant	`BLACK`	Undocumented
Constant	`BLUE`	Undocumented
Constant	`BRIGHT`	Undocumented
Constant	`BRIGHTBLACK`	Undocumented
Constant	`BRIGHTBLUE`	Undocumented
Constant	`BRIGHTCYAN`	Undocumented
Constant	`BRIGHTGREEN`	Undocumented
Constant	`BRIGHTGREY`	Undocumented
Constant	`BRIGHTMAGENTA`	Undocumented
Constant	`BRIGHTRED`	Undocumented
Constant	`BRIGHTYELLOW`	Undocumented
Constant	`CLEARSCREEN`	Undocumented
Constant	`CYAN`	Undocumented
Constant	`DEFAULT`	Undocumented
Constant	`DEFAULT_FORCE_IF_NO_TERM`	Undocumented
Constant	`DEFAULT_FORCE_IF_NO_TTY`	Undocumented
Constant	`ERASEDISP`	Undocumented
Constant	`ERASELINE`	Undocumented
Constant	`GOTO00`	Undocumented
Constant	`GREEN`	Undocumented
Constant	`GREY`	Undocumented
Constant	`MAGENTA`	Undocumented
Constant	`NOCOLOR`	Undocumented
Constant	`RED`	Undocumented
Constant	`RESET`	Undocumented
Constant	`UNDERLINE`	Undocumented
Constant	`YELLOW`	Undocumented
Variable	`_guess`	Undocumented
Variable	`ere`	Undocumented
Variable	`pre`	Undocumented

def _add_color_if_supported(s, colcode, prepend=''): ¶

Undocumented

def _format_segment(s): ¶

Helper for cformat() (NOW REDUNDANT?) e.g. :

   '  \x1b[33mfork\x1b[0m\x1b[39m'

becomes :

    ['  ', '\x1b[33m', 'fork', '\x1b[0m', '\x1b[39m']

The numbers are the bytestring length and the print length

def _percent_parse(s, add=()): ¶

Will rewrite any format strings with a width to have more width by the amount specified.

The add sequence must have as many items as there are format strings.

TODO: deal with %r sensibly?

def _strip_escapes_if_not_supported(s, forceaway=False): ¶

Undocumented

def bgblack(s, prepend=''): ¶

add color on string if supported

def bgblue(s, prepend=''): ¶

add color on string if supported

def bgcyan(s, prepend=''): ¶

add color on string if supported

def bggreen(s, prepend=''): ¶

add color on string if supported

def bgmagenta(s, prepend=''): ¶

add color on string if supported

def bgorange(s, prepend=''): ¶

add color on string if supported

def bgred(s, prepend=''): ¶

add color on string if supported

def bgyellow(s, prepend=''): ¶

add color on string if supported

def black(s, prepend=''): ¶

add color on string if supported

def blend(s, frac, rgb1, rgb2): ¶

add an RGB color around a string that is some fraction between two colors Note this only really makes sense on true-color terminals.

Parameters
s	Undocumented
frac:`float`	Undocumented
rgb1	Undocumented
rgb2	Undocumented

def blue(s, prepend=''): ¶

add color on string if supported

def brightblack(s, prepend=''): ¶

add color on string if supported

def brightblue(s, prepend=''): ¶

add color on string if supported

def brightcyan(s, prepend=''): ¶

add color on string if supported

def brightgray(s, prepend=''): ¶

add color on string if supported

def brightgreen(s, prepend=''): ¶

add color on string if supported

def brightgrey(s, prepend=''): ¶

add color on string if supported

def brightmagenta(s, prepend=''): ¶

add color on string if supported

def brightred(s, prepend=''): ¶

add color on string if supported

def brightyellow(s, prepend=''): ¶

add color on string if supported

def cformat(fs, seq, fsinstead=False): ¶

EXPERIMENT: A percent formatter that is aware that color escapes have zero display width, so you can feed it strings with color escapes and avoid some magic reindenting weirdness.

cformat(arg1,arg2) acts like arg1%arg2

e.g. cformat('%20s', (WHITE+'fork'+RESET,) ) == ' \x1b[1;37mfork\x1b[0m\x1b[39m' instead of '\x1b[1;37mfork\x1b[0m\x1b[39m'

Assumption is that escapes have zero width, which is true for colors but not for weirder things.

def clearscreen(): ¶

output clear-screen code, if supported

def closest_from_rgb255(r, g, b, mid=170, full=255, nobright=False): ¶

Given a r,g,b color (0..255 scale), pick the closest shell color (returns the function)

The brightness that color is rendered as depends on the terminal, see e.g. https://en.wikipedia.org/wiki/ANSI_escape_code#3.2F4_bit

To get some semblance of control, you can control the brightness the non-bright color is assumed to have. (hint: you can cheat your way to less of the garish bright colors by upping mid, or more by lowering it)

You can completely avoid the bright colors by specifying nobright=True

def color_degree(s, v, fromv=0, tov=0, colors=(BRIGHTBLACK, GRAY, WHITE, YELLOW, RED)): ¶

color string s according to where v lies between fromv and tov, ...from a discrete set of colors (if you wanted something more gradual, perhaps use redgreen (if you like the fixed colors), or do it yourself with e.g. true_colf)

Parameters
s:`str`	Undocumented
v:`float`	Undocumented
fromv	Undocumented
tov	Undocumented
colors	Undocumented

def cyan(s, prepend=''): ¶

add color on string if supported

def darkgray(s, prepend=''): ¶

add color on string if supported

def darkgrey(s, prepend=''): ¶

add color on string if supported

def default(s, prepend=''): ¶

add "default colors" code before string if supported

def gray(s, prepend=''): ¶

add color on string if supported

def green(s, prepend=''): ¶

add color on string if supported

def grey(s, prepend=''): ¶

add color on string if supported

def guess_color_support(forceifnottty=False, forceifnoterm=False, fallback=True): ¶

Tries to guess whether we can use color code output.

If we are not on a tty/pty (usually a pipe), return False If the TERM mentions we can, returns True, if it mensions we cannot, return False If we do not know, return the fallback (by default is True)

TODO: fix the logic for this, it does not do exactly what was intended.

User code should probably always prefer supported(), and only use guess_color_support if it wants a different test or fallback later.

def hash_color(s, rgb=False, append=RESET, prepend='', hash_instead=None, on=None): ¶

return string wrapped in a (non-black basic shell) color (and RESET after) based on (a hash of) the string

If you want to color an entire string based on just a part of it, hand the part into hash_instead

TODO: variant that gives just the escapes, so we can avoid calling this a lot

Parameters
s	Undocumented
rgb	if False, uses the basic set of ~8 colors and brightness. if True, uses true color (recommended if you can)
append	Undocumented
prepend	Undocumented
hash_instead	if you want to color a verbose string based on just part of it, hand the color-determining part into `hash_instead`, and the whole into `s`
on	if 'dark' suggests we're drawing on dark background, so we stay away from very dark rgb values if on == 'light', we stay away from very light rgb values by default we don't care, which might be good for area fills

def magenta(s, prepend=''): ¶

add color on string if supported

def orange(s, prepend=''): ¶

add color on string if supported

def real_len(s): ¶

Returns 2-tuple:

amount of printed characters,
amount spent in control codes (which is calculated as the byte length minus the first part)

def red(s, prepend=''): ¶

add color on string if supported

def redgreen(s, frac): ¶

turns a fraction in 0..1 to red..green

def reset(): ¶

add color reset code before string if supported

def supported(): ¶

return what guess_color_support() estimated. (if that was not run yet, do that before returning)

def true_colf(s, r, g, b): ¶

true-color escape from 0..255 r,g,b

def truncate_real_len(s, targetlen, append=RESET): ¶

Truncate a string after so-many real characters. Written for "truncate colored text according to the terminal width" functionality.

Parameters
s	Undocumented
targetlen	Undocumented
append	By default, it appends a reset to default colors, so that it doesn't leave things as the last-used color. To avoid that, say append=''

def tty_size(debug=False): ¶

fetches current terminal size

Has a few methods under *nix, probably largely redundant. Under windows there is only one, and counts on ctypes

returns a dict with keys 'cols' and 'rows'. Values are None when we cannot determine them. You probably want fallback logic around this

def white(s, prepend=''): ¶

add color on string if supported

def yellow(s, prepend=''): ¶

add color on string if supported

BGBLACK: str = ¶

Undocumented

Value

'\x1b[40m'

BGBLUE: str = ¶

Undocumented

Value

'\x1b[44m'

BGBRIGHTGRAY: str = ¶

Undocumented

Value

'\x1b[1;47m'

BGCYAN: str = ¶

Undocumented

Value

'\x1b[46m'

BGGREEN: str = ¶

Undocumented

Value

'\x1b[42m'

BGMAGENTA: str = ¶

Undocumented

Value

'\x1b[45m'

BGRED: str = ¶

Undocumented

Value

'\x1b[41m'

BGYELLOW: str = ¶

Undocumented

Value

'\x1b[43m'

BLACK: str = ¶

Undocumented

Value

'\x1b[30m'

BLUE: str = ¶

Undocumented

Value

'\x1b[34m'

BRIGHT: str = ¶

Undocumented

Value

'\x1b[1m'

BRIGHTBLACK: str = ¶

Undocumented

Value

'\x1b[1;30m'

BRIGHTBLUE: str = ¶

Undocumented

Value

'\x1b[1;34m'

BRIGHTCYAN: str = ¶

Undocumented

Value

'\x1b[1;36m'

BRIGHTGREEN: str = ¶

Undocumented

Value

'\x1b[1;32m'

BRIGHTGREY: str = ¶

Undocumented

Value

'\x1b[1;37m'

BRIGHTMAGENTA: str = ¶

Undocumented

Value

'\x1b[1;35m'

BRIGHTRED: str = ¶

Undocumented

Value

'\x1b[1;31m'

BRIGHTYELLOW: str = ¶

Undocumented

Value

'\x1b[1;33m'

CLEARSCREEN = ¶

Undocumented

Value

ERASEDISP+GOTO00

CYAN: str = ¶

Undocumented

Value

'\x1b[36m'

DEFAULT: str = ¶

Undocumented

Value

'\x1b[39m'

DEFAULT_FORCE_IF_NO_TERM = ¶

Undocumented

Value

None

DEFAULT_FORCE_IF_NO_TTY = ¶

Undocumented

Value

None

ERASEDISP: str = ¶

Undocumented

Value

'\x1b[2J'

ERASELINE: str = ¶

Undocumented

Value

'\x1b[2K'

GOTO00: str = ¶

Undocumented

Value

'\x1b[;H'

GREEN: str = ¶

Undocumented

Value

'\x1b[32m'

GREY: str = ¶

Undocumented

Value

'\x1b[37m'

MAGENTA: str = ¶

Undocumented

Value

'\x1b[35m'

NOCOLOR: str = ¶

Undocumented

Value

'\x1b[0m'

RED: str = ¶

Undocumented

Value

'\x1b[31m'

RESET = ¶

Undocumented

Value

NOCOLOR+DEFAULT

UNDERLINE: str = ¶

Undocumented

Value

'\x1b[4m'

YELLOW: str = ¶

Undocumented

Value

'\x1b[33m'

_guess = ¶

Undocumented

ere = ¶

Undocumented

pre = ¶

Undocumented