Improve documentation.

[pyutils.git] / src / pyutils / ansi.py

diff --git a/src/pyutils/ansi.py b/src/pyutils/ansi.py
index 1d45d3b944c7babeaf4c91eca199747af5726d60..6850513813bf7dba36830fd4a80f67730b10b0c4 100755 (executable)
--- a/src/pyutils/ansi.py
+++ b/src/pyutils/ansi.py
@@ -4,7 +4,7 @@
 
 """A bunch of color names mapped into RGB tuples and some methods for
 setting the text color, background, etc... using ANSI escape
-sequences.
+sequences.  See: https://en.wikipedia.org/wiki/ANSI_escape_code.
 """
 
 import contextlib
@@ -22,8 +22,6 @@ from pyutils import logging_utils, string_utils
 
 logger = logging.getLogger(__name__)
 
-# https://en.wikipedia.org/wiki/ANSI_escape_code
-
 
 COLOR_NAMES_TO_RGB: Dict[str, Tuple[int, int, int]] = {
     "abbey": (0x4C, 0x4F, 0x56),
@@ -539,7 +537,7 @@ COLOR_NAMES_TO_RGB: Dict[str, Tuple[int, int, int]] = {
     "electric lime": (0xCC, 0xFF, 0x00),
     "electric violet": (0x8B, 0x00, 0xFF),
     "elephant": (0x12, 0x34, 0x47),
-    "elf green": (0x08, 0x83, 0x70),
+    "elf green": (0x1B, 0x8A, 0x6B),
     "elm": (0x1C, 0x7C, 0x7D),
     "emerald": (0x50, 0xC8, 0x78),
     "eminence": (0x6C, 0x30, 0x82),
@@ -1342,6 +1340,8 @@ COLOR_NAMES_TO_RGB: Dict[str, Tuple[int, int, int]] = {
     "scorpion": (0x69, 0x5F, 0x62),
     "scotch mist": (0xFF, 0xFB, 0xDC),
     "screamin' green": (0x66, 0xFF, 0x66),
+    "screamin green": (0x66, 0xFF, 0x66),
+    "screaming green": (0x66, 0xFF, 0x66),
     "sea buckthorn": (0xFB, 0xA1, 0x29),
     "sea green": (0x2E, 0x8B, 0x57),
     "sea mist": (0xC5, 0xDB, 0xCA),
@@ -1673,37 +1673,37 @@ COLOR_NAMES_TO_RGB: Dict[str, Tuple[int, int, int]] = {
 
 def clear() -> str:
     """Clear screen ANSI escape sequence"""
-    return "\e[H\e[2J"
+    return "\x1B[H\x1B[2J"
 
 
 def clear_screen() -> str:
     """Clear screen ANSI escape sequence"""
-    return "\e[H\e[2J"
+    return "\x1B[H\x1B[2J"
 
 
 def clear_line() -> str:
     """Clear the current line ANSI escape sequence"""
-    return "\e[2K\r"
+    return "\x1B[2K\r"
 
 
 def reset() -> str:
     """Reset text attributes to 'normal'"""
-    return "\e[m"
+    return "\x1B[m"
 
 
 def normal() -> str:
     """Reset text attributes to 'normal'"""
-    return "\e[m"
+    return "\x1B[m"
 
 
 def bold() -> str:
     """Set text to bold"""
-    return "\e[1m"
+    return "\x1B[1m"
 
 
 def italic() -> str:
     """Set text to italic"""
-    return "\e[3m"
+    return "\x1B[3m"
 
 
 def italics() -> str:
@@ -1713,12 +1713,12 @@ def italics() -> str:
 
 def underline() -> str:
     """Set text to underline"""
-    return "\e[4m"
+    return "\x1B[4m"
 
 
 def strikethrough() -> str:
     """Set text to strikethrough"""
-    return "\e[9m"
+    return "\x1B[9m"
 
 
 def strike_through() -> str:
@@ -1756,7 +1756,7 @@ def fg_16color(red: int, green: int, blue: int) -> str:
         bright_count += 1
     if bright_count > 1:
         code += 60
-    return f"\e[{code}m"
+    return f"\x1B[{code}m"
 
 
 def bg_16color(red: int, green: int, blue: int) -> str:
@@ -1771,7 +1771,7 @@ def bg_16color(red: int, green: int, blue: int) -> str:
         bright_count += 1
     if bright_count > 1:
         code += 60
-    return f"\e[{code}m"
+    return f"\x1B[{code}m"
 
 
 def _pixel_to_216color(n: int) -> int:
@@ -1794,7 +1794,7 @@ def fg_216color(red: int, green: int, blue: int) -> str:
     g = _pixel_to_216color(green)
     b = _pixel_to_216color(blue)
     code = 16 + r * 36 + g * 6 + b
-    return f"\e[38;5;{code}m"
+    return f"\x1B[38;5;{code}m"
 
 
 def bg_216color(red: int, green: int, blue: int) -> str:
@@ -1803,17 +1803,17 @@ def bg_216color(red: int, green: int, blue: int) -> str:
     g = _pixel_to_216color(green)
     b = _pixel_to_216color(blue)
     code = 16 + r * 36 + g * 6 + b
-    return f"\e[48;5;{code}m"
+    return f"\x1B[48;5;{code}m"
 
 
 def fg_24bit(red: int, green: int, blue: int) -> str:
     """Set foreground using 24bit color mode"""
-    return f"\e[38;2;{red};{green};{blue}m"
+    return f"\x1B[38;2;{red};{green};{blue}m"
 
 
 def bg_24bit(red: int, green: int, blue: int) -> str:
     """Set background using 24bit color mode"""
-    return f"\e[48;2;{red};{green};{blue}m"
+    return f"\x1B[48;2;{red};{green};{blue}m"
 
 
 def _find_color_by_name(name: str) -> Tuple[int, int, int]:
@@ -1889,6 +1889,8 @@ def fg(
 
 
 def reset_fg():
+    """Returns: an ANSI escape code to reset just the foreground color while
+    preserving the background color and any other formatting (bold, italics, etc...)"""
     return '\033[39m'
 
 
@@ -1974,6 +1976,9 @@ def bg(
         force_16color: force bg to use 16 color mode
         force_216color: force bg to use 216 color mode
 
+    Returns:
+        A string containing the requested escape sequence
+
     >>> import string_utils as su
     >>> su.to_base64(bg("red"))    # b'\x1b[48;5;196m'
     b'G1s0ODs1OzE5Nm0=\\n'
@@ -2010,6 +2015,11 @@ def bg(
 
 
 def reset_bg():
+    """Returns an ANSI escape sequence that resets text background
+    color to the default but preserves foreground coloring and text
+    attributes like bold, italics, underlines, etc...
+
+    """
     return '\033[49m'