termcolor-dg 1.0.2
ANSI Color formatting for terminal output and log coloring
License: MIT
Requires Python: >=2.7

termcolor_dg
============

📦 [pypi/termcolor_dg](https://pypi.python.org/pypi/termcolor_dg) |
📑 [ANSI escape code](https://en.wikipedia.org/wiki/ANSI_escape_code) |
📑 [Color codes cheatsheet](https://delameter.github.io/termcolor)

ANSI Color formatting for terminal output and log coloring. Supports 16 colors, 256 colors and 24-bit color modes.

Python 2 support is present for legacy projects, and because it is not too much work and I have to use it for now.


Example
-------

```python
from termcolor_dg import colored, cprint

print(colored('Hello, World!', 'light_red', 'on_blue'))
cprint('Hello, World!', 'blue', 'on_light_red', ['reverse', 'blink'])
print_red_on_cyan = lambda x: cprint(x, 'red', 'on_cyan')
print_red_on_cyan('Hello, World!')
for i in range(10):
  cprint(str(i), 'magenta', end=' ' if i != 9 else '\n')
import sys

cprint("Attention!", 196, attrs='bold', file=sys.stderr)  # 256 color mode
cprint("Attention!", (255, 0, 0), attrs='bold', file=sys.stderr)  # 24-bit color mode
import logging
from termcolor_dg import logging_basic_color_config

logging_basic_color_config()
logging.log(logging.INFO, 'test')
```


Colors demo screenshot (`python -m termcolor_dg`):
--------------------------------------------------

![colors.png](https://raw.githubusercontent.com/gunchev/termcolor_dg/master/colors.png "Colors demo")


Colored logs demo screenshot (`python -m termcolor_dg logs`):
-------------------------------------------------------------

![color_logs.png](https://raw.githubusercontent.com/gunchev/termcolor_dg/master/color_logs.png "Colorized logs demo")


Environment variables
---------------------

- **ANSI_COLORS_FORCE**:
  If set to anything, even empty string, color escape sequences will be added.

- **ANSI_COLORS_DISABLED**:
  If set to anything no coloring will be performed, overrides **ANSI_COLORS_FORCE**.

- **NO_COLOR**:
  If set to anything no coloring will be performed, overrides **ANSI_COLORS_FORCE**,
  see https://no-color.org/.

If none of the environment variables is set the colors are used
only if the ``stdout`` is attached to a terminal: ``sys.stdout.isatty()``.


Text properties
---------------

| Text colors   | Text highlights | Alt Text highlights | Attributes |
|---------------|-----------------|---------------------|------------|
| black         | black           | on_black            | bold       |
| red           | red             | on_red              | dark       |
| green         | green           | on_green            | underline  |
| yellow        | yellow          | on_yellow           | blink      |
| blue          | blue            | on_blue             | reverse    |
| magenta       | magenta         | on_magenta          | concealed  |
| cyan          | cyan            | on_cyan             |            |
| light_grey    | light_grey      | on_light_grey       |            |
| dark_grey     | dark_grey       | on_dark_grey        |            |
| light_red     | light_red       | on_light_red        |            |
| light_green   | light_green     | on_light_green      |            |
| light_yellow  | light_yellow    | on_light_yellow     |            |
| light_blue    | light_blue      | on_light_blue       |            |
| light_magenta | light_magenta   | on_light_magenta    |            |
| light_cyan    | light_cyan      | on_light_cyan       |            |
| white         | white           | on_white            |            |


Functions
---------

### Adding ANSI colors

**always_colored(text, color=None, on_color=None, attrs=None, reset=True)**
:   Returns the text with ANSI color code in front and ANSI color reset after. Arguments:
:   - **text** is the text to add color to
:   - **color** and **on_color** define the character and background color. Each can be a name for 16 color mode, number for the 256 color variant and list/tuple of R, G and B for the 24 bit color support. The following all define light red: **'light_red'**, **9**, **196** and **(255, 0, 0)**.
:   - **attrs** attributes, single attribute name, list or tuple of attributes.
:   - **reset** if set to **False** will suppress adding of the reset ANSI sequence at the end. Useful if you are joining another colored string, only the last reset is really needed.

**colored(text, color=None, on_color=None, attrs=None, reset=True)**
:   same as always_colored but checks if the app is running on a terminal and if the colors have been forced or disabled. The boolean **termcolor_dg.DISABLED** is the variable checked.


### Utility functions

**cprint(text='', color=None, on_color=None, attrs=None, \*\*kwargs)**
:   same as colored, but prints the resulting string instead of returning it.

**rainbow_color(n, steps, nmax=255)**
:   calculates the color at step **n** needed to produce a rainbow in **steps** steps with intensity up to **nmax**. Ex: **rainbow_color(0, 120)** returns **(255, 0, 0)**, **rainbow_color(30, 120)** returns **(128, 255, 0)**.

**monkey_patch_logging**
:   Monkeypatch **logging.Formatter** to add colors to the logs on a terminal, not customizable for now. Monkeypatch **logging.LogRecord.getMessage** to log formatting errors in the log format instead of throwing useless exception.

**logging_basic_color_config(level='DEBUG', fmt='%(asctime)s %(message)s  # %(filename)s:%(lineno)d %(name)s', color_on_terminal=True)**
:   Basic logging configuration, coloring and report formatting errors (**monkey_patch_logging**). Coloring code relies on '  # ' to determine the section to print in pale dark blue (comment).

**monkey_unpatch_logging**
:   Undo the monkeypatching done by **monkey_patch_logging** and remove coloring and error handling.

**COLOR_RESET_STR**
:   The color and attribute ANSI reset code.


## Similar projects

You may want to check out:

- 📦 [pypi/termcolor](https://pypi.python.org/pypi/termcolor) - the original project
- 📦 [natmey/termcolor](https://github.com/natmey/termcolor) - fork of the original termcolor that termcolor_dg extends
- 📦 [pypi/colorama](https://pypi.org/project/colorama/) for more advanced options.


## Interesting links

- 📑 [Terminal Colors](https://github.com/termstandard/colors) discussion with examples
- 📑 [ANSI/VT100 Terminal Control Escape Sequences](https://www2.ccs.neu.edu/research/gpc/VonaUtils/vona/terminal/vtansi.htm)
- 📑 [ANSI escape code](https://en.wikipedia.org/wiki/ANSI_escape_code)
- 📑 [Color codes cheatsheet](https://delameter.github.io/termcolor)
- 📑 [MarkdownGuide - Basic Syntax](https://www.markdownguide.org/basic-syntax)


Terminal properties support
---------------------------
Assume this information is outdated.

| Terminal         |  bold   | dark  | underline |  blink  | reverse | concealed | 256 colors | 24-bit color |
|:-----------------|:-------:|:-----:|:---------:|:-------:|:-------:|:---------:|:----------:|:------------:|
| **linux**        |  ❌[^3]  | ❌[^3] |   ✅[^3]   |  ✅[^3]  |    ✅    |     ❌     |     ❌      |      ❌       |
| **konsole**      |    ✅    |   ✅   |     ✅     |    ✅    |    ✅    |     ✅     |     ✅      |      ✅       |
| **terminator**   |    ✅    |   ✅   |     ✅     |    ✅    |    ✅    |     ✅     |     ✅      |      ✅       |
| **kitty**        |    ✅    |   ✅   |     ✅     |    ✅    |    ✅    |     ❌     |     ✅      |      ✅       |
| **xterm**        |    ✅    |   ❌   |     ✅     |    ✅    |    ✅    |     ✅     |     ✅      |      ✅       |
| **rxvt**         |    ✅    |   ❌   |     ✅     |    ✅    |    ✅    |     ❌     |     ✅      |      ❌       |
| **dtterm**       |    ✅    |   ✅   |     ✅     | reverse |    ✅    |     ✅     |     ❓      |      ❓       |
| **teraterm**     | reverse |   ❌   |     ✅     | rev/red |    ✅    |     ❌     |     ❓      |      ❓       |
| **aixterm**      | normal  |   ❌   |     ✅     |    ❌    |    ✅    |     ✅     |     ❓      |      ❓       |
| **Windows**      |    ❌    |   ❌   |     ❌     |    ❌    |    ✅    |   ✅[^4]   |     ❓      |      ✅       |
| **PuTTY**        |  ✅[^2]  |   ✅   |     ✅     |  ✅[^1]  |    ✅    |     ❌     |     ✅      |      ✅       |
| **Cygwin SSH**   |    ✅    |   ❌   |   color   |  color  |  color  |     ✅     |     ❓      |      ❓       |
| **Mac Terminal** |    ✅    |   ❓   |     ✅     |    ✅    |    ✅    |     ✅     |     ✅      |      ❓       |
| **iTerm2**       |    ✅    |   ❓   |     ✅     |    ✅    |    ✅    |     ✅     |     ✅      |      ✅       |

[^1]: Disabled by default

[^2]: Supports color change, bold text or both.

[^3]: See [VGA text mode](https://en.wikipedia.org/wiki/VGA_text_mode)

[^4]: See [Add support for the "concealed" graphic rendition attribute #6876 ](https://github.com/microsoft/terminal/issues/6876)

termcolor_dg changes
====================

1.0.0 (2023-05-25)
------------------

- fix DISABLED detection
- logging.basicConfig has no disable_existing_loggers argument.
- move back to GitHub, workflows does work and is free.

0.9.3.1 (2022-02-14)
--------------------

- Adjust the log color scheme.
- pylint fixes in the color demo.

0.9.3 (2022-02-14)
------------------

- Adjust the log color scheme.
- pylint fixes in the color demo.

0.9.2 (2022-02-07)
------------------

- Combine color, background and attributes in a single escape sequence.
- Minor enhancements.

0.9.1 (2022-02-05)
------------------

- Rename to termcolor_dg (termcolor2 is taken).

0.9.0 (2022-02-05)
------------------

- Fork to termcolor2.
- Add 24-bit colors support.
- Add logging and color demos.
- Add ANSI_COLORS_DISABLED and ANSI_COLORS_FORCE environment variables.
- Add always_colored, rainbow_color.
- Add monkey_patch_logging and logging_basic_color_config utility functions.
- Better cprint and print compatibility (no arguments = new line).
- Drop 'gray' and 'on_gray' (it was an alias for black, bad idea?).
- Make the trailing reset sequence optional for colored.
- Use `python -m build` to build the project.
- Remove regex usage, the following would have not been stripped but works: `echo -e '(\e[01;32mx\e[1;0033mx\e[m)'`.
- Remove PKG-INFO.
- README.md instead of README.rst.
- ... unit tests, INSTALL ...

---

termcolor changes
=================

1.9.1 (2021-12-15)
------------------

- python 2 and 3 compatibility, avoid KeyError
- make pylint happy
- fix character escapes
- better .gitignore
- fix __ALL__ to __all__

1.1.0 (2011-01-13)
------------------

- Added cprint function.

1.0.1 (2011-01-13)
------------------

- Updated README.rst.

1.0.0 (2011-01-13)
------------------

- Changed license to MIT.
- Updated copyright.
- Refactored source code.

0.2 (2010-09-07)
------------------

- Added support for Python 3.x.

0.1.2 (2009-06-04)
------------------

- Fixed bold characters. (Thanks Tibor Fekete)

0.1.1 (2009-03-05)
------------------

- Some refactoring.
- Updated copyright.
- Fixed reset colors.
- Updated documentation.

0.1 (2008-06-09)
----------------

- Initial release.