# ubelt.util_colors module

This module defines simple functions to color your text and highlight your code using ANSI escape sequences. This works using the Pygments library, which is an optional requirement. Therefore, these functions only work properly if Pygments is installed, otherwise these functions will return the unmodified text and a warning will be printed.

The `highlight_code()` function uses pygments to highlight syntax of a programming language.

The `color_text()` function colors text with a solid color.

Note the functions in this module require the optional `pygments` library to work correctly. These functions will warn if `pygments` is not installed.

This module contains a global variable `NO_COLOR`, which if set to True will force all ANSI text coloring functions to become no-ops. This defaults to the value of the `bool(os.environ.get('NO_COLOR'))` flag, which is compliant with [NoColor].

New in 1.3.4: The `rich` backend was added as an alternative to pygments.

Related work:

  https://github.com/Textualize/rich

References

[NoColor]

https://no-color.org/

Requirements:

  pip install pygments

ubelt.util_colors.highlight_code(text, lexer_name='python', backend='pygments', **kwargs)

  Highlights a block of text using ANSI tags based on language syntax.

  Parameters:

    - text (str) – Plain text to parse and highlight

    - lexer_name (str) – Name of language. eg: python, docker, c++. For an exhaustive list see `pygments.lexers.get_all_lexers()`. Defaults to “python”.

    - backend (str) – Either “pygments” or “rich”. Defaults to “pygments”.

    - **kwargs – If the backend is “pygments”, passed to pygments.lexers.get_lexer_by_name.

  Returns:

    text - highlighted text if the requested backend is installed, otherwise the plain text is returned unmodified.

  Return type:

    str

  Example

      >>> import ubelt as ub
      >>> text = 'import ubelt as ub; print(ub)'
      >>> new_text = ub.highlight_code(text)
      >>> print(new_text)

  Example

      >>> import ubelt as ub
      >>> text = 'import ubelt as ub; print(ub)'
      >>> new_text = ub.highlight_code(text, backend='pygments')
      >>> print(new_text)
      >>> new_text = ub.highlight_code(text, backend='rich')
      >>> print(new_text)

ubelt.util_colors._pygments_highlight(text, lexer_name, **kwargs)

  Original pygments highlight logic

ubelt.util_colors._rich_highlight(text, lexer_name)

  Alternative rich-based highlighter

  References

  [RichDiscuss3076]

  https://github.com/Textualize/rich/discussions/3076

ubelt.util_colors.color_text(text, color)

  Colorizes text a single color using ansi tags.

  Parameters:

    - text (str) – text to colorize

    - color (str) – color code. different systems may have different colors. commonly available colors are: ‘red’, ‘brown’, ‘yellow’, ‘green’, ‘blue’, ‘black’, and ‘white’.

  Returns:

    text - colorized text. If pygments is not installed plain text is returned.

  Return type:

    str

  SeeAlso:

    https://rich.readthedocs.io/en/stable/markup.html

  Example

      >>> text = 'raw text'
      >>> import pytest
      >>> import ubelt as ub
      >>> if ub.modname_to_modpath('pygments'):
      >>>     # Colors text only if pygments is installed
      >>>     ansi_text = ub.color_text(text, 'red')
      >>>     prefix = '\x1b[31'
      >>>     print('prefix = {!r}'.format(prefix))
      >>>     print('ansi_text = {!r}'.format(ansi_text))
      >>>     assert ansi_text.startswith(prefix)
      >>>     assert ub.color_text(text, None) == 'raw text'
      >>> else:
      >>>     # Otherwise text passes through unchanged
      >>>     assert ub.color_text(text, 'red') == 'raw text'
      >>>     assert ub.color_text(text, None) == 'raw text'

  Example

      >>> # xdoctest: +REQUIRES(module:pygments)
      >>> import pygments.console
      >>> import ubelt as ub
      >>> # List available colors codes
      >>> known_colors = pygments.console.codes.keys()
      >>> for color in known_colors:
      ...     print(ub.color_text(color, color))