Renamed ansi_safe_wcswidth() to style_aware_wcswidth()

Renamed ansi_aware_write() to style_aware_write()

9 files changed, 35 insertions, 32 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 20427976..72dedb06 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,11 @@
 ## 0.9.23 (TBD, 2019)
 * Bug Fixes
     * Fixed bug where startup script containing a single quote in its file name was incorrectly quoted
+* Breaking changes
+    * Renamed the following `ansi` members for accuracy in what types of ANSI escape sequences are handled
+        * `ansi.allow_ansi` -> `ansi.allow_style`
+        * `ansi.ansi_safe_wcswidth()` -> `ansi.style_aware_wcswidth()`
+        * `ansi.ansi_aware_write()` -> `ansi.style_aware_write()`
 
 ## 0.9.22 (December 9, 2019)
 * Bug Fixes
diff --git a/cmd2/ansi.py b/cmd2/ansi.py
index 57b204ca..b5b78164 100644
--- a/cmd2/ansi.py
+++ b/cmd2/ansi.py
@@ -90,20 +90,18 @@ def strip_style(text: str) -> str:
     return ANSI_STYLE_RE.sub('', text)
 
 
-def ansi_safe_wcswidth(text: str) -> int:
+def style_aware_wcswidth(text: str) -> int:
     """
     Wrap wcswidth to make it compatible with strings that contains ANSI style sequences
-
     :param text: the string being measured
     """
     # Strip ANSI style sequences since they cause wcswidth to return -1
     return wcswidth(strip_style(text))
 
 
-def ansi_aware_write(fileobj: IO, msg: str) -> None:
+def style_aware_write(fileobj: IO, msg: str) -> None:
     """
     Write a string to a fileobject and strip its ANSI style sequences if required by allow_style setting
-
     :param fileobj: the file object being written to
     :param msg: the string being written
     """
@@ -114,8 +112,8 @@ def ansi_aware_write(fileobj: IO, msg: str) -> None:
 
 
 def fg_lookup(fg_name: str) -> str:
-    """Look up ANSI escape codes based on foreground color name.
-
+    """
+    Look up ANSI escape codes based on foreground color name.
     :param fg_name: foreground color name to look up ANSI escape code(s) for
     :return: ANSI escape code(s) associated with this color
     :raises ValueError if the color cannot be found
@@ -128,8 +126,8 @@ def fg_lookup(fg_name: str) -> str:
 
 
 def bg_lookup(bg_name: str) -> str:
-    """Look up ANSI escape codes based on background color name.
-
+    """
+    Look up ANSI escape codes based on background color name.
     :param bg_name: background color name to look up ANSI escape code(s) for
     :return: ANSI escape code(s) associated with this color
     :raises ValueError if the color cannot be found
@@ -142,8 +140,8 @@ def bg_lookup(bg_name: str) -> str:
 
 
 def style(text: Any, *, fg: str = '', bg: str = '', bold: bool = False, underline: bool = False) -> str:
-    """Styles a string with ANSI colors and/or styles and returns the new string.
-
+    """
+    Apply ANSI colors and/or styles to a string and return it.
     The styling is self contained which means that at the end of the string reset code(s) are issued
     to undo whatever styling was done at the beginning.
 
@@ -210,14 +208,14 @@ def async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_off
     # That will be included in the input lines calculations since that is where the cursor is.
     num_prompt_terminal_lines = 0
     for line in prompt_lines[:-1]:
-        line_width = ansi_safe_wcswidth(line)
+        line_width = style_aware_wcswidth(line)
         num_prompt_terminal_lines += int(line_width / terminal_columns) + 1
 
     # Now calculate how many terminal lines are take up by the input
     last_prompt_line = prompt_lines[-1]
-    last_prompt_line_width = ansi_safe_wcswidth(last_prompt_line)
+    last_prompt_line_width = style_aware_wcswidth(last_prompt_line)
 
-    input_width = last_prompt_line_width + ansi_safe_wcswidth(line)
+    input_width = last_prompt_line_width + style_aware_wcswidth(line)
 
     num_input_terminal_lines = int(input_width / terminal_columns) + 1
 
diff --git a/cmd2/argparse_completer.py b/cmd2/argparse_completer.py
index a2690dd0..23fd930e 100644
--- a/cmd2/argparse_completer.py
+++ b/cmd2/argparse_completer.py
@@ -444,11 +444,11 @@ class AutoCompleter(object):
                 completions.sort(key=self._cmd2_app.default_sort_key)
                 self._cmd2_app.matches_sorted = True
 
-            token_width = ansi.ansi_safe_wcswidth(action.dest)
+            token_width = ansi.style_aware_wcswidth(action.dest)
             completions_with_desc = []
 
             for item in completions:
-                item_width = ansi.ansi_safe_wcswidth(item)
+                item_width = ansi.style_aware_wcswidth(item)
                 if item_width > token_width:
                     token_width = item_width
 
@@ -585,7 +585,7 @@ class AutoCompleter(object):
     def _print_message(msg: str) -> None:
         """Print a message instead of tab completions and redraw the prompt and input line"""
         import sys
-        ansi.ansi_aware_write(sys.stdout, msg + '\n')
+        ansi.style_aware_write(sys.stdout, msg + '\n')
         rl_force_redisplay()
 
     def _print_arg_hint(self, arg_action: argparse.Action) -> None:
diff --git a/cmd2/argparse_custom.py b/cmd2/argparse_custom.py
index 51c3375e..f735498d 100644
--- a/cmd2/argparse_custom.py
+++ b/cmd2/argparse_custom.py
@@ -802,11 +802,11 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         return formatter.format_help() + '\n'
 
     def _print_message(self, message, file=None):
-        # Override _print_message to use ansi_aware_write() since we use ANSI escape characters to support color
+        # Override _print_message to use style_aware_write() since we use ANSI escape characters to support color
         if message:
             if file is None:
                 file = sys.stderr
-            ansi.ansi_aware_write(file, message)
+            ansi.style_aware_write(file, message)
 
 
 # The default ArgumentParser class for a cmd2 app
diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py
index 8a97761d..f133381b 100644
--- a/cmd2/cmd2.py
+++ b/cmd2/cmd2.py
@@ -439,7 +439,7 @@ class Cmd(cmd.Cmd):
         :param end: string appended after the end of the message, default a newline
         """
         try:
-            ansi.ansi_aware_write(self.stdout, "{}{}".format(msg, end))
+            ansi.style_aware_write(self.stdout, "{}{}".format(msg, end))
         except BrokenPipeError:
             # This occurs if a command's output is being piped to another
             # process and that process closes before the command is
@@ -462,7 +462,7 @@ class Cmd(cmd.Cmd):
             final_msg = ansi.style_error(msg)
         else:
             final_msg = "{}".format(msg)
-        ansi.ansi_aware_write(sys.stderr, final_msg + end)
+        ansi.style_aware_write(sys.stderr, final_msg + end)
 
     def pwarning(self, msg: Any = '', *, end: str = '\n', apply_style: bool = True) -> None:
         """Wraps perror, but applies ansi.style_warning by default
@@ -1096,7 +1096,7 @@ class Cmd(cmd.Cmd):
                 longest_match_length = 0
 
                 for cur_match in matches_to_display:
-                    cur_length = ansi.ansi_safe_wcswidth(cur_match)
+                    cur_length = ansi.style_aware_wcswidth(cur_match)
                     if cur_length > longest_match_length:
                         longest_match_length = cur_length
             else:
@@ -2653,7 +2653,7 @@ class Cmd(cmd.Cmd):
                 widest = 0
                 # measure the commands
                 for command in cmds:
-                    width = ansi.ansi_safe_wcswidth(command)
+                    width = ansi.style_aware_wcswidth(command)
                     if width > widest:
                         widest = width
                 # add a 4-space pad
@@ -3737,7 +3737,7 @@ class Cmd(cmd.Cmd):
         test_results = runner.run(testcase)
         execution_time = time.time() - start_time
         if test_results.wasSuccessful():
-            ansi.ansi_aware_write(sys.stderr, stream.read())
+            ansi.style_aware_write(sys.stderr, stream.read())
             finish_msg = ' {0} transcript{1} passed in {2:.3f} seconds '.format(num_transcripts, plural, execution_time)
             finish_msg = ansi.style_success(utils.align_center(finish_msg, fill_char='='))
             self.poutput(finish_msg)
diff --git a/cmd2/rl_utils.py b/cmd2/rl_utils.py
index 9a23cbcd..4df733db 100644
--- a/cmd2/rl_utils.py
+++ b/cmd2/rl_utils.py
@@ -193,7 +193,7 @@ def rl_set_prompt(prompt: str) -> None:  # pragma: no cover
 
 
 def rl_make_safe_prompt(prompt: str) -> str:  # pragma: no cover
-    """Overcome bug in GNU Readline in relation to calculation of prompt length in presence of ANSI escape codes.
+    """Overcome bug in GNU Readline in relation to calculation of prompt length in presence of ANSI escape codes
 
     :param prompt: original prompt
     :return: prompt safe to pass to GNU Readline
diff --git a/cmd2/utils.py b/cmd2/utils.py
index ddb9f3b5..ffbe5a64 100644
--- a/cmd2/utils.py
+++ b/cmd2/utils.py
@@ -669,7 +669,7 @@ def align_text(text: str, alignment: TextAlignment, *, fill_char: str = ' ',
     if len(fill_char) != 1:
         raise TypeError("Fill character must be exactly one character long")
 
-    fill_char_width = ansi.ansi_safe_wcswidth(fill_char)
+    fill_char_width = ansi.style_aware_wcswidth(fill_char)
     if fill_char_width == -1:
         raise (ValueError("Fill character is an unprintable character"))
 
@@ -687,9 +687,9 @@ def align_text(text: str, alignment: TextAlignment, *, fill_char: str = ' ',
         if index > 0:
             text_buf.write('\n')
 
-        # Use ansi_safe_wcswidth to support characters with display widths
+        # Use style_aware_wcswidth to support characters with display widths
         # greater than 1 as well as ANSI style sequences
-        line_width = ansi.ansi_safe_wcswidth(line)
+        line_width = ansi.style_aware_wcswidth(line)
         if line_width == -1:
             raise(ValueError("Text to align contains an unprintable character"))
 
@@ -717,8 +717,8 @@ def align_text(text: str, alignment: TextAlignment, *, fill_char: str = ' ',
 
         # In cases where the fill character display width didn't divide evenly into
         # the gaps being filled, pad the remainder with spaces.
-        left_fill += ' ' * (left_fill_width - ansi.ansi_safe_wcswidth(left_fill))
-        right_fill += ' ' * (right_fill_width - ansi.ansi_safe_wcswidth(right_fill))
+        left_fill += ' ' * (left_fill_width - ansi.style_aware_wcswidth(left_fill))
+        right_fill += ' ' * (right_fill_width - ansi.style_aware_wcswidth(right_fill))
 
         text_buf.write(left_fill + line + right_fill)
 
diff --git a/tests/test_ansi.py b/tests/test_ansi.py
index 4f7ab652..2382c333 100644
--- a/tests/test_ansi.py
+++ b/tests/test_ansi.py
@@ -17,10 +17,10 @@ def test_strip_style():
     assert base_str == ansi.strip_style(ansi_str)
 
 
-def test_ansi_safe_wcswidth():
+def test_style_aware_wcswidth():
     base_str = HELLO_WORLD
     ansi_str = ansi.style(base_str, fg='green')
-    assert ansi.ansi_safe_wcswidth(ansi_str) != len(ansi_str)
+    assert ansi.style_aware_wcswidth(ansi_str) != len(ansi_str)
 
 
 def test_style_none():
diff --git a/tests/test_utils.py b/tests/test_utils.py
index 27b0e3bb..b5231172 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -349,7 +349,7 @@ def test_align_text_term_width():
     fill_char = ' '
 
     term_width = shutil.get_terminal_size().columns
-    expected_fill = (term_width - ansi.ansi_safe_wcswidth(text)) * fill_char
+    expected_fill = (term_width - ansi.style_aware_wcswidth(text)) * fill_char
 
     aligned = cu.align_text(text, fill_char=fill_char, alignment=cu.TextAlignment.LEFT)
     assert aligned == text + expected_fill