src/KERNEL_PY/kernel/termcolor.py

   1 # -*- coding: utf-8 -*-
   2 #
   3 # Copyright (C) 2007-2023  CEA, EDF, OPEN CASCADE
   4 #
   5 # This library is free software; you can redistribute it and/or
   6 # modify it under the terms of the GNU Lesser General Public
   7 # License as published by the Free Software Foundation; either
   8 # version 2.1 of the License, or (at your option) any later version.
   9 #
  10 # This library is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 # Lesser General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU Lesser General Public
  16 # License along with this library; if not, write to the Free Software
  17 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  18 #
  19 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  20 #
  21
  22 #  Author : Renaud Barate (EDF R&D)
  23 #  Date   : August 2009
  24
  25 ## \defgroup termcolor termcolor
  26 #  \{
  27 #  \details
  28 #  This module provides utility functions to display colored text in the
  29 #  terminal. It is based on ISO 6429 standard that defines control codes to
  30 #  change characters representation in color-capable ASCII terminals.
  31 #
  32 #  In this module, colors are represented as lists of codes, so they can be added
  33 #  to obtain special effects (e.g. RED + GREEN_BG to display red text on green
  34 #  background). Several constants are defined for the most usual codes to
  35 #  facilitate the use of colors, but it is also possible to define colors
  36 #  directly from the corresponding code from ISO 6429 standard. In fact it is
  37 #  even necessary for less usual codes that don't have an associated constant
  38 #  (e.g. PURPLE + ['09'] can be used to display a crossed-out purple text).
  39 #
  40 #  \code
  41 #  import sys
  42 #  from salome.kernel import termcolor
  43 #  if termcolor.canDisplayColor(sys.stdout):
  44 #      print(termcolor.makeColoredMessage("Hello world!", termcolor.BLUE))
  45 #  else:
  46 #      print("Hello world!")
  47 #  \endcode
  48 #  \}
  49
  50 """
  51 This module provides utility functions to display colored text in the
  52 terminal. It is based on ISO 6429 standard that defines control codes to
  53 change characters representation in color-capable ASCII terminals.
  54
  55 In this module, colors are represented as lists of codes, so they can be added
  56 to obtain special effects (e.g. RED + GREEN_BG to display red text on green
  57 background). Several constants are defined for the most usual codes to
  58 facilitate the use of colors, but it is also possible to define colors
  59 directly from the corresponding code from ISO 6429 standard. In fact it is
  60 even necessary for less usual codes that don't have an associated constant
  61 (e.g. PURPLE + ['09'] can be used to display a crossed-out purple text).
  62
  63 Example::
  64
  65     import sys
  66     from salome.kernel import termcolor
  67     if termcolor.canDisplayColor(sys.stdout):
  68         print(termcolor.makeColoredMessage("Hello world!", termcolor.BLUE))
  69     else:
  70         print("Hello world!")
  71
  72 """
  73
  74 # Constants for color codes
  75 ## Default color for the terminal
  76 #  \ingroup termcolor
  77 DEFAULT    = ['00']
  78 """Default color for the terminal"""
  79 ## Bold text and brighter colors
  80 #  \ingroup termcolor
  81 BOLD       = ['01']
  82 """Bold text and brighter colors"""
  83 ## Underlined text
  84 #  \ingroup termcolor
  85 UNDERLINED = ['04']
  86 """Underlined text"""
  87 ## Black foreground
  88 #  \ingroup termcolor
  89 BLACK_FG   = ['30']
  90 """Black foreground"""
  91 ## Red foreground
  92 #  \ingroup termcolor
  93 RED_FG     = ['31']
  94 """Red foreground"""
  95 ## Green foreground
  96 #  \ingroup termcolor
  97 GREEN_FG   = ['32']
  98 """Green foreground"""
  99 ## Yellow foreground
 100 #  \ingroup termcolor
 101 YELLOW_FG  = ['33']
 102 """Yellow foreground"""
 103 ## Blue foreground
 104 #  \ingroup termcolor
 105 BLUE_FG    = ['34']
 106 """Blue foreground"""
 107 ## Purple foreground
 108 #  \ingroup termcolor
 109 PURPLE_FG  = ['35']
 110 """Purple foreground"""
 111 ## Cyan foreground
 112 #  \ingroup termcolor
 113 CYAN_FG    = ['36']
 114 """Cyan foreground"""
 115 ## White foreground
 116 #  \ingroup termcolor
 117 WHITE_FG   = ['37']
 118 """White foreground"""
 119 ## Black background
 120 #  \ingroup termcolor
 121 BLACK_BG   = ['40']
 122 """Black background"""
 123 ## Red background
 124 #  \ingroup termcolor
 125 RED_BG     = ['41']
 126 """Red background"""
 127 ## Green background
 128 #  \ingroup termcolor
 129 GREEN_BG   = ['42']
 130 """Green background"""
 131 ## Yellow background
 132 #  \ingroup termcolor
 133 YELLOW_BG  = ['43']
 134 """Yellow background"""
 135 ## Blue background
 136 #  \ingroup termcolor
 137 BLUE_BG    = ['44']
 138 """Blue background"""
 139 ## Purple background
 140 #  \ingroup termcolor
 141 PURPLE_BG  = ['45']
 142 """Purple background"""
 143 ## Cyan background
 144 #  \ingroup termcolor
 145 CYAN_BG    = ['46']
 146 """Cyan background"""
 147 ## White background
 148 #  \ingroup termcolor
 149 WHITE_BG   = ['47']
 150 """White background"""
 151
 152 # Constants for common colored text
 153 ## Black text (equivalent to BLACK_FG)
 154 #  \ingroup termcolor
 155 BLACK      = BLACK_FG
 156 """Black text (equivalent to BLACK_FG)"""
 157 ## Red text (equivalent to BOLD + RED_FG)
 158 #  \ingroup termcolor
 159 RED        = BOLD + RED_FG
 160 """Red text (equivalent to BOLD + RED_FG)"""
 161 ## Green text (equivalent to BOLD + GREEN_FG)
 162 #  \ingroup termcolor
 163 GREEN      = BOLD + GREEN_FG
 164 """Green text (equivalent to BOLD + GREEN_FG)"""
 165 ## Yellow text (equivalent to BOLD + YELLOW_FG)
 166 #  \ingroup termcolor
 167 YELLOW     = BOLD + YELLOW_FG
 168 """Yellow text (equivalent to BOLD + YELLOW_FG)"""
 169 ## Blue text (equivalent to BOLD + BLUE_FG)
 170 #  \ingroup termcolor
 171 BLUE       = BOLD + BLUE_FG
 172 """Blue text (equivalent to BOLD + BLUE_FG)"""
 173 ## Purple text (equivalent to BOLD + PURPLE_FG)
 174 #  \ingroup termcolor
 175 PURPLE     = BOLD + PURPLE_FG
 176 """Purple text (equivalent to BOLD + PURPLE_FG)"""
 177 ## Cyan text (equivalent to BOLD + CYAN_FG)
 178 #  \ingroup termcolor
 179 CYAN       = BOLD + CYAN_FG
 180 """Cyan text (equivalent to BOLD + CYAN_FG)"""
 181 ## White text (equivalent to WHITE_FG)
 182 #  \ingroup termcolor
 183 WHITE      = WHITE_FG
 184 """White text (equivalent to WHITE_FG)"""
 185
 186 ## Return True if the stream can display colored text, False otherwise.
 187 #  \ingroup termcolor
 188 def canDisplayColor(stream):
 189     """
 190     Return True if the stream can display colored text, False otherwise.
 191     """
 192     return hasattr(stream, "isatty") and stream.isatty()
 193
 194 ## Return the control sequence for the color in parameter, i.e. the string
 195 #  telling the terminal to display the following text in the given color.
 196 #  \ingroup termcolor
 197 def getControlSequence(color):
 198     """
 199     Return the control sequence for the color in parameter, i.e. the string
 200     telling the terminal to display the following text in the given color.
 201     """
 202     seq = "\x1b["
 203     for i in range(len(color)):
 204         seq += color[i]
 205         if i < len(color)-1:
 206             seq += ";"
 207     seq += "m"
 208     return seq
 209
 210 ## Return a string that can be used to display the message in parameter with
 211 #  the given color.
 212 #  \ingroup termcolor
 213 def makeColoredMessage(message, color):
 214     """
 215     Return a string that can be used to display the message in parameter with
 216     the given color.
 217     """
 218     return (getControlSequence(color) +
 219             str(message) +
 220             getControlSequence(DEFAULT))
 221
 222 ## Test function for termcolor module.
 223 #  \ingroup termcolor
 224 def TEST_termcolor():
 225     """Test function for termcolor module."""
 226     import sys
 227     if not canDisplayColor(sys.stdout):
 228         print("Standard output does not support colors.")
 229         return
 230     print(makeColoredMessage("This message must appear in blue.", BLUE))
 231     print(makeColoredMessage("This message must appear in red on green " +
 232                              "background.", RED + GREEN_BG))
 233     print(makeColoredMessage("This message must appear in magenta and " +
 234                              "crossed-out.", PURPLE + ['09']))
 235
 236
 237 # Main function only used to test the module
 238 if __name__ == "__main__":
 239     TEST_termcolor()