Improve docs in ANSI.py

[python_utils.git] / ansi.py

diff --git a/ansi.py b/ansi.py
index dee52424fefa6bd80daccc3d8830c0a707e12b6a..a8b84fc0c2dd0acce18e96d21d86eb2b2da409b7 100755 (executable)
--- a/ansi.py
+++ b/ansi.py
@@ -5,7 +5,6 @@
 """A bunch of color names mapped into RGB tuples and some methods for
 setting the text color, background, etc... using ANSI escape
 sequences.
 """A bunch of color names mapped into RGB tuples and some methods for
 setting the text color, background, etc... using ANSI escape
 sequences.

-

 """
 
 import contextlib
 """
 
 import contextlib


@@ -1611,54 +1610,67 @@ 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"
 
 
 def reset() -> str:
     return "\e[H\e[2J"
 
 
 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


@@ -1666,6 +1678,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:


@@ -1680,6 +1693,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:


@@ -1708,6 +1722,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)


@@ -1716,6 +1731,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)


@@ -1724,10 +1740,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"
 
 


@@ -1756,10 +1774,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'


@@ -1811,6 +1839,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)
 


@@ -1830,6 +1867,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:


@@ -1855,10 +1893,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'