Improve docs.

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

diff --git a/src/pyutils/ansi.py b/src/pyutils/ansi.py
index 1d45d3b944c7babeaf4c91eca199747af5726d60..b885a406648f7db63ab53e3fca9a85ccb78fb0c7 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
 
 """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
 """
 
 import contextlib


@@ -22,8 +22,6 @@ from pyutils import logging_utils, string_utils
 
 logger = logging.getLogger(__name__)
 
 
 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),
 
 COLOR_NAMES_TO_RGB: Dict[str, Tuple[int, int, int]] = {
     "abbey": (0x4C, 0x4F, 0x56),


@@ -1673,37 +1671,37 @@ COLOR_NAMES_TO_RGB: Dict[str, Tuple[int, int, int]] = {
 
 def clear() -> str:
     """Clear screen ANSI escape sequence"""
 
 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"""
 
 
 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"""
 
 
 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'"""
 
 
 def reset() -> str:
     """Reset text attributes to 'normal'"""

-    return "\e[m"
+    return "\x1B[m"

 
 
 def normal() -> str:
     """Reset text attributes to 'normal'"""
 
 
 def normal() -> str:
     """Reset text attributes to 'normal'"""

-    return "\e[m"
+    return "\x1B[m"

 
 
 def bold() -> str:
     """Set text to bold"""
 
 
 def bold() -> str:
     """Set text to bold"""

-    return "\e[1m"
+    return "\x1B[1m"

 
 
 def italic() -> str:
     """Set text to italic"""
 
 
 def italic() -> str:
     """Set text to italic"""

-    return "\e[3m"
+    return "\x1B[3m"

 
 
 def italics() -> str:
 
 
 def italics() -> str:


@@ -1713,12 +1711,12 @@ def italics() -> str:
 
 def underline() -> str:
     """Set text to underline"""
 
 def underline() -> str:
     """Set text to underline"""

-    return "\e[4m"
+    return "\x1B[4m"

 
 
 def strikethrough() -> str:
     """Set text to strikethrough"""
 
 
 def strikethrough() -> str:
     """Set text to strikethrough"""

-    return "\e[9m"
+    return "\x1B[9m"

 
 
 def strike_through() -> str:
 
 
 def strike_through() -> str:


@@ -1756,7 +1754,7 @@ def fg_16color(red: int, green: int, blue: int) -> str:
         bright_count += 1
     if bright_count > 1:
         code += 60
         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:
 
 
 def bg_16color(red: int, green: int, blue: int) -> str:


@@ -1771,7 +1769,7 @@ def bg_16color(red: int, green: int, blue: int) -> str:
         bright_count += 1
     if bright_count > 1:
         code += 60
         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:
 
 
 def _pixel_to_216color(n: int) -> int:


@@ -1794,7 +1792,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
     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:
 
 
 def bg_216color(red: int, green: int, blue: int) -> str:


@@ -1803,17 +1801,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
     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"""
 
 
 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"""
 
 
 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]:
 
 
 def _find_color_by_name(name: str) -> Tuple[int, int, int]:


@@ -1889,6 +1887,8 @@ def fg(
 
 
 def reset_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'
 
 
     return '\033[39m'
 
 


@@ -1974,6 +1974,9 @@ def bg(
         force_16color: force bg to use 16 color mode
         force_216color: force bg to use 216 color mode
 
         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'
     >>> import string_utils as su
     >>> su.to_base64(bg("red"))    # b'\x1b[48;5;196m'
     b'G1s0ODs1OzE5Nm0=\\n'