Add --all and cleanup clear_line().

[python_utils.git] / ansi.py

diff --git a/ansi.py b/ansi.py
index a49760037e31c6c01e84a225e7147d588f8f5934..628fed7144442cd5b7d13b7d136ac0fc66532d7f 100755 (executable)
--- a/ansi.py
+++ b/ansi.py
@@ -1,8 +1,11 @@
 #!/usr/bin/env python3
 
 #!/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
 """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
 
 import contextlib
 import difflib


@@ -1607,54 +1610,72 @@ COLOR_NAMES_TO_RGB: Dict[str, Tuple[int, int, int]] = {
 
 
 def clear() -> str:
 
 
 def clear() -> str:

+    """Clear screen ANSI escape sequence"""

     return "\e[H\e[2J"
 
 
 def clear_screen() -> str:
     return "\e[H\e[2J"
 
 
 def clear_screen() -> str:

+    """Clear screen ANSI escape sequence"""

     return "\e[H\e[2J"
 
 
     return "\e[H\e[2J"
 
 

+def clear_line() -> str:
+    """Clear the current line ANSI escape sequence"""
+    return "\e[2K\r"
+
+

 def reset() -> str:
 def reset() -> str:

+    """Reset text attributes to 'normal'"""

     return "\e[m"
 
 
 def normal() -> str:
     return "\e[m"
 
 
 def normal() -> str:

+    """Reset text attributes to 'normal'"""

     return "\e[m"
 
 
 def bold() -> str:
     return "\e[m"
 
 
 def bold() -> str:

+    """Set text to bold"""

     return "\e[1m"
 
 
 def italic() -> str:
     return "\e[1m"
 
 
 def italic() -> str:

+    """Set text to italic"""

     return "\e[3m"
 
 
 def italics() -> str:
     return "\e[3m"
 
 
 def italics() -> str:

+    """Set text to italic"""

     return italic()
 
 
 def underline() -> str:
     return italic()
 
 
 def underline() -> str:

+    """Set text to underline"""

     return "\e[4m"
 
 
 def strikethrough() -> str:
     return "\e[4m"
 
 
 def strikethrough() -> str:

+    """Set text to strikethrough"""

     return "\e[9m"
 
 
 def strike_through() -> str:
     return "\e[9m"
 
 
 def strike_through() -> str:

+    """Set text to strikethrough"""

     return strikethrough()
 
 
 def is_16color(num: int) -> bool:
     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:
     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:
     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
     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:
 
 
 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:
     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:
 
 
 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:
     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:
 
 
 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)
     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:
 
 
 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)
     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:
 
 
 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"
 
 
 def bg_24bit(red: int, green: int, blue: int) -> str:
     return f"\e[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"\e[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.
 
     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'
     >>> import string_utils as su
     >>> su.to_base64(fg('blue'))
     b'G1szODs1OzIxbQ==\\n'

-

     """
     if name is not None and name == 'reset':
         return '\033[39m'
     """
     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.
 
     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)
 
     >>> pick_contrasting_color(None, 20, 20, 20)
     (255, 255, 255)
 


@@ -1826,6 +1872,7 @@ def pick_contrasting_color(
 
 
 def guess_name(name: str) -> str:
 
 
 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:
     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.
 
     """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'
     >>> 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'
     """
     if name is not None and name == 'reset':
         return '\033[49m'