Tutorial ======== In addition to this tutorial, you can find examples in the `examples `_ folder. **Table of Contents:** 1. `Basic Usage <#basic-usage>`__ 2. `colorise.cprint <#colorise-cprint>`__ 3. `colorise.fprint <#colorise-fprint>`__ 4. `colorise.highlight <#colorise-highlight>`__ 5. `Attributes <#attributes>`__ 6. `Disabling Colors <#disabling-colors>`__ 7. `More Colors! <#more-colors>`__ 8. `Redefining Colors <#redefining-colors>`__ Basic Usage ----------- You may be interested to know how many colors your terminal can represent, which you can check using :py:func:`colorise.num_colors` which tries its best to guess the number of colors supported. >>> import colorise >>> colorise.num_colors() 256 Returned values may be 8, 16, 88, 256 and 16,777,216 (or 256^3 i.e. 24-bit true-color). You can also run the `color_test.py script `__ which prints all the capabilities of your console. To set the current color, you can use the :py:func:`colorise.set_color` function. For example, .. raw:: html

         >>> colorise.set_color(fg='red'); print('Hello')
   Hello
      

sets the current foreground color to red while .. raw:: html

         >>> colorise.set_color(fg='red', bg='green'); print('Hello')
   Hello
      

sets the current foreground color to red and the background color to green. Supported color names can be queried via :py:func:`colorise.color_names`. >>> colorise.color_names() ['black', 'red', 'green', 'yellow', 'blue', 'purple', 'magenta', 'cyan', 'gray', 'grey', 'lightgrey', 'lightgray', 'lightred', 'lightgreen', 'lightyellow', 'lightblue', 'lightpurple', 'lightmagenta', 'lightcyan', 'white'] Use :py:func:`colorise.reset_color` to reset colors to their defaults. .. raw:: html

         >>> colorise.set_color(fg='red'); print('Hello')
   Hello
   >>> colorise.reset_color()
   >>> print('Hello')
   Hello
      

:py:func:`colorise.cprint` -------------------------- To print colored text, you can use the :py:func:`colorise.cprint` function. .. raw:: html

         >>> colorise.cprint('This has yellow text and a green background', fg='yellow', bg='green')
   This has yellow text and a green background
      

:py:func:`colorise.fprint` -------------------------- The :py:func:`colorise.fprint` function provides more control than :py:func:`colorise.cprint` by letting you specify colors akin to Python 3's `string formatting `_. .. raw:: html

         >>> colorise.fprint('{fg=yellow,bg=green}This has yellow text and a green background')
   This has yellow text and a green background
   >>> colorise.fprint('{fg=yellow,bg=green}This has a green background and yellow foreground but{fg=red} changes to red')
   This has a green background and yellow foreground but changes to red
      

The :py:func:`colorise.fprint` function provides the `autoreset` keyword argument to control if colors should be reset when a new color format is encountered. It is ``True`` by default. .. raw:: html

         >>> colorise.fprint('{fg=yellow,bg=green}This has a green background and yellow foreground but{fg=red} changes to red', autoreset=False)
   This has a green background and yellow foreground but changes to red
   >>> colorise.fprint('{fg=yellow,bg=green}This has a green background and yellow foreground but{fg=red} changes to red', autoreset=True)
   This has a green background and yellow foreground but changes to red
      

Notice in the second example that both fore- and background colors are reset. It would correspond to the following example where we explicitly reset all colors and attributes with ``{reset}`` before setting the foreground color to red. .. raw:: html

         >>> colorise.fprint('{fg=yellow,bg=green}This has a green background and yellow foreground but{reset}{fg=red} changes to red', autoreset=False)
   This has a green background and yellow foreground but changes to red
      

.. note:: It is not currently possible to mix color formats and Python's string formatting such as ``colorise.fprint('{fg=red}{0}', 'test')``. See `this issue `__ if you want to know more or help. :py:func:`colorise.highlight` ----------------------------- The :py:func:`colorise.highlight` function can be used to highlight ranges of characters within a string. .. raw:: html

         >>> colorise.highlight('This is a highlighted string', fg='red', indices=[0, 3, 5, 10, 13, 15, 16, 17, 22, 26, 27])
   This is a highlighted string
      

Attributes ---------- Text attributes are supported via the :py:class:`colorise.attributes.Attr` class. .. raw:: html

         >>> from colorise import Attr
   >>> colorise.cprint('Hello', fg='yellow', bg='purple', attributes=[Attr.Italic])
   Hello
   >>> colorise.cprint('Hello', fg='yellow', bg='purple', attributes=[Attr.Underline])
   Hello
      

As for :py:func:`colorise.fprint`, you can specify the attributes directly in the format string. .. raw:: html

         >>> colorise.fprint('{fg=red,bg=cyan,italic}Hello')
   Hello
   >>> colorise.fprint('Hello {bold}Hello')
   Hello Hello
      

Disabling Colors ---------------- It is sometimes useful to disable colors, for example in an application where colored output is controlled by a configuration file. The :py:func:`colorise.cprint`, :py:func:`colorise.fprint` and :py:func:`colorise.highlight` functions all support the ``enabled`` keyword argument for this purpose. Colors are enabled by default. .. raw:: html

         >>> colorise.cprint('Enabled!', fg='red', enabled=True)
   Enabled!
   >>> colorise.cprint('Disabled!', fg='red', enabled=False)
   Disabled!
      

Disabling colors means that *no* ANSI escape sequences are emitted and no Windows Console API calls are made so if a color has been set previously, outputting disabled colors are still affected. .. raw:: html

         >>> colorise.set_color(fg='red')
   >>> colorise.cprint('Disabled!', fg='red', enabled=False)
   Disabled
      

More Colors! ------------ Besides named colors, you can also specify colors via color table index, RGB, hex, `HLS and HSV `__. Color indices index into color tables commonly supported by different platforms. .. raw:: html

         >>> colorise.cprint('Via color indices', fg=198)
   Via color indices
   >>> colorise.cprint('Via hex', fg='#43fff3', bg='0xd60c74')
   Via hex
   >>> colorise.cprint('Via short-hand hex', fg='#09c', bg='0xfd9')
   Via short-hand hex
   >>> colorise.fprint('{fg=rgb(255;0;135)}Via RGB')
   Via RGB
   >>> colorise.cprint('Via HSV', bg='hsv(0.7;41.1;82)')
   Via HSV
   >>> colorise.fprint('{bg=hls(0.21;0.48;0.98)}Via HLS')
   Via HLS
      

HSV values are hue ([0; 360]), saturation ([0; 100]), and value ([0; 100]). HLS values are hue ([0; 360]), lightness ([0; 100]), and saturation ([0; 100]). .. note:: Even if your terminal does not support 88/256 index color tables or true-color, colorise will attempt to approximate the color by finding the closest one and use that. For example, Windows usually supports only 16 colors but using ``colorise.cprint('Hello', fg='rgb(240;240;0)')`` on such a system will still give you a yellow color (assuming standard Windows console colors). Also see the sprites in the :doc:`screenshots` section. Redefining Colors ----------------- Some platforms allow you to redefine the standard colors but currently you can only redefine colors on Windows. As an example, let us redefine 'green' (color index 2 in the :ref:`logical color table `). .. raw:: html

         >>> colorise.cprint('This should be green', fg='green')
   This should be green
   >>> colorise.redefine_colors({2: (255, 0, 255)})
   >>> colorise.cprint('This should be green', fg='green')
   This should be green
      

:py:func:`colorise.redefine_colors` takes a dictionary of colortable indices as keys and RGB tuples as values. Here, we redefine the entry in the colortable at the color index for green (2) to be magenta instead. This change persists until the color is redefined again or colorise is quit and automatically restores the original color table. .. note:: Redefining colors does not currently work with `ConEmu `__ or on Mac and Linux systems.