X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=ansi.py;h=628fed7144442cd5b7d13b7d136ac0fc66532d7f;hb=a1d5f347e978bdb62666a90f55c36047e82ed5cf;hp=a49760037e31c6c01e84a225e7147d588f8f5934;hpb=2f5b47c8b30d1b7d86443391332be2f3805cdafd;p=python_utils.git

diff --git a/ansi.py b/ansi.py
index a497600..628fed7 100755
--- a/ansi.py
+++ b/ansi.py
@@ -1,8 +1,11 @@
 #!/usr/bin/env python3
 
+# © Copyright 2021-2022, Scott Gasch
+
 """A bunch of color names mapped into RGB tuples and some methods for
 setting the text color, background, etc... using ANSI escape
-sequences."""
+sequences.
+"""
 
 import contextlib
 import difflib
@@ -1607,54 +1610,72 @@ COLOR_NAMES_TO_RGB: Dict[str, Tuple[int, int, int]] = {
 
 
 def clear() -> str:
+    """Clear screen ANSI escape sequence"""
     return ""
 
 
 def clear_screen() -> str:
+    """Clear screen ANSI escape sequence"""
     return ""
 
 
+def clear_line() -> str:
+    """Clear the current line ANSI escape sequence"""
+    return "\r"
+
+
 def reset() -> str:
+    """Reset text attributes to 'normal'"""
     return ""
 
 
 def normal() -> str:
+    """Reset text attributes to 'normal'"""
     return ""
 
 
 def bold() -> str:
+    """Set text to bold"""
     return ""
 
 
 def italic() -> str:
+    """Set text to italic"""
     return ""
 
 
 def italics() -> str:
+    """Set text to italic"""
     return italic()
 
 
 def underline() -> str:
+    """Set text to underline"""
     return ""
 
 
 def strikethrough() -> str:
+    """Set text to strikethrough"""
     return ""
 
 
 def strike_through() -> str:
+    """Set text to strikethrough"""
     return strikethrough()
 
 
 def is_16color(num: int) -> bool:
+    """Is num a valid 16 color number?"""
     return num in (255, 128)
 
 
 def is_216color(num: int) -> bool:
+    """Is num a valid 256 color number?"""
     return num in set([0, 95, 135, 175, 223, 255])
 
 
 def _simple_color_number(red: int, green: int, blue: int) -> int:
+    """Construct a simple color number"""
     r = red > 0
     g = green > 0
     b = blue > 0
@@ -1662,6 +1683,7 @@ def _simple_color_number(red: int, green: int, blue: int) -> int:
 
 
 def fg_16color(red: int, green: int, blue: int) -> str:
+    """Set foreground color using 16 color mode"""
     code = _simple_color_number(red, green, blue) + 30
     bright_count = 0
     if red > 128:
@@ -1676,6 +1698,7 @@ def fg_16color(red: int, green: int, blue: int) -> str:
 
 
 def bg_16color(red: int, green: int, blue: int) -> str:
+    """Set background using 16 color mode"""
     code = _simple_color_number(red, green, blue) + 40
     bright_count = 0
     if red > 128:
@@ -1704,6 +1727,7 @@ def _pixel_to_216color(n: int) -> int:
 
 
 def fg_216color(red: int, green: int, blue: int) -> str:
+    """Set foreground using 216 color mode"""
     r = _pixel_to_216color(red)
     g = _pixel_to_216color(green)
     b = _pixel_to_216color(blue)
@@ -1712,6 +1736,7 @@ def fg_216color(red: int, green: int, blue: int) -> str:
 
 
 def bg_216color(red: int, green: int, blue: int) -> str:
+    """Set background using 216 color mode"""
     r = _pixel_to_216color(red)
     g = _pixel_to_216color(green)
     b = _pixel_to_216color(blue)
@@ -1720,10 +1745,12 @@ def bg_216color(red: int, green: int, blue: int) -> str:
 
 
 def fg_24bit(red: int, green: int, blue: int) -> str:
+    """Set foreground using 24bit color mode"""
     return f"[38;2;{red};{green};{blue}m"
 
 
 def bg_24bit(red: int, green: int, blue: int) -> str:
+    """Set background using 24bit color mode"""
     return f"[48;2;{red};{green};{blue}m"
 
 
@@ -1752,10 +1779,20 @@ def fg(
     force_216color are passed (respectively).  Otherwise the code will
     do what it thinks best.
 
+    Args:
+        name: the name of the color to set
+        red: the color to set's red component value
+        green: the color to set's green component value
+        blue: the color to set's blue component value
+        force_16color: force fg to use 16 color mode
+        force_216color: force fg to use 216 color mode
+
+    Returns:
+        String containing the ANSI escape sequence to set desired foreground
+
     >>> import string_utils as su
     >>> su.to_base64(fg('blue'))
     b'G1szODs1OzIxbQ==\\n'
-
     """
     if name is not None and name == 'reset':
         return '\033[39m'
@@ -1807,6 +1844,15 @@ def pick_contrasting_color(
     contrasting color given the red, green, blue of a background
     color or a color name of the background color.
 
+    Args:
+        name: the name of the color to contrast
+        red: the color to contrast's red component value
+        green: the color to contrast's green component value
+        blue: the color to contrast's blue component value
+
+    Returns:
+        An RGB tuple containing a contrasting color
+
     >>> pick_contrasting_color(None, 20, 20, 20)
     (255, 255, 255)
 
@@ -1826,6 +1872,7 @@ def pick_contrasting_color(
 
 
 def guess_name(name: str) -> str:
+    """Try to guess what color the user is talking about"""
     best_guess = None
     max_ratio = None
     for possibility in COLOR_NAMES_TO_RGB:
@@ -1851,10 +1898,17 @@ def bg(
     """Returns an ANSI color code for changing the current background
     color.
 
+    Args:
+        name: the name of the color to set
+        red: the color to set's red component value
+        green: the color to set's green component value
+        blue: the color to set's blue component value
+        force_16color: force bg to use 16 color mode
+        force_216color: force bg to use 216 color mode
+
     >>> import string_utils as su
     >>> su.to_base64(bg("red"))    # b'\x1b[48;5;196m'
     b'G1s0ODs1OzE5Nm0=\\n'
-
     """
     if name is not None and name == 'reset':
         return '\033[49m'