Convenience functions for ANSI terminal colour sequences [color].

Latest release 20260531: Add a bunch of other SGR parameters, though terminal support for these is very spotty.

Mapping and function for adding ANSI terminal colour escape sequences to strings for colour highlighting of output.

Short summary:

• colour_escape: Return the ANSI escape sequence to activate the colour code. code may be an int or a str which indexes COLOUR_CODES.
• colourise: Return a string enclosed in colour-on and colour-off ANSI sequences.
• colourise_patterns: Colourise a string s according to patterns.
• env_no_color: Test the $NO_COLOR environment variable per the specification at https://no-color.org/.
• make_pattern: Convert a pattern specification into a (colour,regexp) tuple.
• make_patterns: Convert an iterable of pattern specifications into a list of (colour,regexp) tuples.
• TerminalColors: A parser for /etc/terminal-colors.d' files.

Module contents:

• colour_escape(code): Return the ANSI escape sequence to activate the colour code. code may be an int or a str which indexes COLOUR_CODES.

• colourise(s, colour=None, uncolour=None, colour_padding=False): Return a string enclosed in colour-on and colour-off ANSI sequences.

  Parameters:

  • s: the string to colour
  • colour: names the desired ANSI colour.
  • uncolour: may be used to specify the colour-off colour; the default is 'normal' (from NORMAL_COLOUR).
  • colour_padding: default False; if true colour the entire text, otherwise do not colour the leading and trailing whitespace of each line.

• colourise_patterns(s, patterns, default_colour=None): Colourise a string s according to patterns.

  Parameters:

  • s: the string.
  • patterns: a sequence of patterns.
  • default_colour: if a string pattern has no colon, or starts with a colon, use this colour; default "cyan" (from DEFAULT_HIGHLIGHT).

  Each pattern may be:

  • a string of the form "[colour]:regexp"
  • a string containing no colon, taken to be a regexp
  • a tuple of the form (colour,regexp)
  • a regexp object

  Returns the string with ANSI colour escapes embedded.

• env_no_color(environ=None): Test the $NO_COLOR environment variable per the specification at https://no-color.org/

• make_pattern(pattern, default_colour=None): Convert a pattern specification into a (colour,regexp) tuple.

  Parameters:

  • pattern: the pattern to parse
  • default_colour: the highlight colour, default "cyan" (from DEFAULT_HIGHLIGHT).

  Each pattern may be:

  • a string of the form "[colour]:regexp"
  • a string containing no colon, taken to be a regexp
  • a tuple of the form (colour,regexp)
  • a regexp object

• make_patterns(patterns, default_colour=None): Convert an iterable of pattern specifications into a list of (colour,regexp) tuples.

  Parameters:

  • patterns: an iterable of patterns to parse
  • default_colour: the highlight colour, default "cyan" (from DEFAULT_HIGHLIGHT).

  Each pattern may be:

  • a string of the form "[colour]:regexp"
  • a string containing no colon, taken to be a regexp
  • a tuple of the form (colour, regexp)
  • a regexp object

• class TerminalColors: A parser for /etc/terminal-colors.d' files.

TerminalColors.__init__(self, util_name=None, term_name=None, type_name=None, colors_dirpath=None, envvar=None): Initialise the TerminalColors instance.

Parameters:

• util_name: optional utility name, default from sys.argv[0]
• term_name: optional terminal name, default from the $TERM envvar
• type_name: optional type name, default 'enable'
• colors_dirpath: optional specification files directory path, default from TerminalColors.TERMINAL_COLORS_D
• envvar: environment variable to override matches; the default util_name+'_COLORS', thus $LS_COLORS if util_name=='ls'. That may be the value False if no environment variable should be an override.

TerminalColors.convert_sequence(sequence): Convert a colour specification to an escape sequence.

TerminalColors.find_specfile(self): Locate the most specific specification file matching our criteria. Return None if no file matches.

TerminalColors.mapping: The mapping of name to escape sequence.

TerminalColors.scan(self, path=None): Scan the colour specification in path and yield (name,escape_sequence) tuples.

Release Log

Release 20260531: Add a bunch of other SGR parameters, though terminal support for these is very spotty.

Release 20250306: colourise: do not colour the leading and trailing whitespace, provide colour_padding=False optional flag to disable.

Release 20220227:

• New TerminalColors class parsing /etc/terminal-colors.d and honouring $*_COLORS.
• New colour_escape(code) to make the escape sequence for a colour code.
• New COLOUR_CODES mapping of known colour names.

Release 20200729:

• New env_no_color() test function honouring the $NO_COLOUR envvar per https://no-color.org/
• colourise: get the "normal" default from the global NORMAL_COLOUR.

Release 20180726: greater markdowning of docstrings

Release 20180725.2: some markdown, still release testing

Release 20180725.1: Trivial changes, testing release process.

Release 20180725: rename second colourise function to colourise_patterns, was shadowing things

Release 20180422:

• New function colourise to colour strings with regexp matches.
• New helper functions make_pattern and make_patterns to construct (colour, regexp)s from specifications.
• New public names NORMAL_COLOUR and DEFAULT_HIGHLIGHT.

Release 20170902: Release metadata changes.

Release 20160828: Add PyPI category, other minor tweaks.

Release 20150112: PyPI release.

Release 20150107: first standalone pypi release