From 3ca9b4d16433af8da5d2de7f4a2338b56b5428d5 Mon Sep 17 00:00:00 2001 From: Scott Gasch Date: Thu, 2 Jun 2022 21:56:40 -0700 Subject: [PATCH] Improve docs in ANSI.py --- ansi.py | 51 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/ansi.py b/ansi.py index dee5242..a8b84fc 100755 --- 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. - """ import contextlib @@ -1611,54 +1610,67 @@ 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 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 @@ -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: + """Set foreground color using 16 color mode""" 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: + """Set background using 16 color mode""" 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: + """Set foreground using 216 color mode""" 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: + """Set background using 216 color mode""" 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: + """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" @@ -1756,10 +1774,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' @@ -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. + 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) @@ -1830,6 +1867,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: @@ -1855,10 +1893,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' -- 2.47.1