Merge pull request #843 from python-cmd2/ansi_to_style

ansi to style

Author: kmvanbrunt

CHANGELOG.md

@@ -2,6 +2,16 @@
 * Bug Fixes
     * Fixed bug where startup script containing a single quote in its file name was incorrectly quoted
     * Added missing implicit dependency on `setuptools` due to build with `setuptools_scm`
+* Enhancements
+    * Added dim text style support via `style()` function and `ansi.INTENSITY_DIM` setting.
+* 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()`
+    * Renamed the following `ansi` members for clarification
+        * `ansi.BRIGHT` -> `ansi.INTENSITY_BRIGHT`
+        * `ansi.NORMAL` -> `ansi.INTENSITY_NORMAL`
 
 ## 0.9.22 (December 9, 2019)
 * Bug Fixes

README.md

@@ -317,7 +317,7 @@ example/transcript_regex.txt:
 # The regex for editor will match whatever program you use.
 # regexes on prompts just make the trailing space obvious
 (Cmd) set
-allow_ansi: Terminal
+allow_style: Terminal
 continuation_prompt: >/ /
 debug: False
 echo: False

cmd2/ansi.py

@@ -1,5 +1,8 @@
 # coding=utf-8
-"""Support for ANSI escape sequences which are used for things like applying style to text"""
+"""
+Support for ANSI escape sequences which are used for things like applying style to text,
+setting the window title, and asynchronous alerts.
+ """
 import functools
 import re
 from typing import Any, IO
@@ -11,16 +14,16 @@
 # On Windows, filter ANSI escape codes out of text sent to stdout/stderr, and replace them with equivalent Win32 calls
 colorama.init(strip=False)
 
-# Values for allow_ansi setting
-ANSI_NEVER = 'Never'
-ANSI_TERMINAL = 'Terminal'
-ANSI_ALWAYS = 'Always'
+# Values for allow_style setting
+STYLE_NEVER = 'Never'
+STYLE_TERMINAL = 'Terminal'
+STYLE_ALWAYS = 'Always'
 
-# Controls when ANSI escape sequences are allowed in output
-allow_ansi = ANSI_TERMINAL
+# Controls when ANSI style style sequences are allowed in output
+allow_style = STYLE_TERMINAL
 
-# Regular expression to match ANSI escape sequences
-ANSI_ESCAPE_RE = re.compile(r'\x1b[^m]*m')
+# Regular expression to match ANSI style sequences (including 8-bit and 24-bit colors)
+ANSI_STYLE_RE = re.compile(r'\x1b\[[^m]*m')
 
 # Foreground color presets
 FG_COLORS = {
@@ -68,50 +71,50 @@
 BG_RESET = BG_COLORS['reset']
 RESET_ALL = Style.RESET_ALL
 
-BRIGHT = Style.BRIGHT
-NORMAL = Style.NORMAL
+# Text intensities
+INTENSITY_BRIGHT = Style.BRIGHT
+INTENSITY_DIM = Style.DIM
+INTENSITY_NORMAL = Style.NORMAL
 
-# ANSI escape sequences not provided by colorama
+# ANSI style sequences not provided by colorama
 UNDERLINE_ENABLE = colorama.ansi.code_to_chars(4)
 UNDERLINE_DISABLE = colorama.ansi.code_to_chars(24)
 
 
-def strip_ansi(text: str) -> str:
+def strip_style(text: str) -> str:
     """
-    Strip ANSI escape sequences from a string.
+    Strip ANSI style sequences from a string.
 
-    :param text: string which may contain ANSI escape sequences
-    :return: the same string with any ANSI escape sequences removed
+    :param text: string which may contain ANSI style sequences
+    :return: the same string with any ANSI style sequences removed
     """
-    return ANSI_ESCAPE_RE.sub('', text)
+    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 escape sequences
-
+    Wrap wcswidth to make it compatible with strings that contains ANSI style sequences
     :param text: the string being measured
     """
-    # Strip ANSI escape sequences since they cause wcswidth to return -1
-    return wcswidth(strip_ansi(text))
+    # 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 escape sequences if required by allow_ansi setting
-
+    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
     """
-    if allow_ansi.lower() == ANSI_NEVER.lower() or \
-            (allow_ansi.lower() == ANSI_TERMINAL.lower() and not fileobj.isatty()):
-        msg = strip_ansi(msg)
+    if allow_style.lower() == STYLE_NEVER.lower() or \
+            (allow_style.lower() == STYLE_TERMINAL.lower() and not fileobj.isatty()):
+        msg = strip_style(msg)
     fileobj.write(msg)
 
 
 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
@@ -124,8 +127,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
@@ -137,16 +140,18 @@ def bg_lookup(bg_name: str) -> str:
     return ansi_escape
 
 
-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.
-
+def style(text: Any, *, fg: str = '', bg: str = '', bold: bool = False,
+          dim: bool = False, underline: bool = False) -> str:
+    """
+    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.
 
     :param text: Any object compatible with str.format()
     :param fg: foreground color. Relies on `fg_lookup()` to retrieve ANSI escape based on name. Defaults to no color.
     :param bg: background color. Relies on `bg_lookup()` to retrieve ANSI escape based on name. Defaults to no color.
-    :param bold: apply the bold style if True. Defaults to False.
+    :param bold: apply the bold style if True. Can be combined with dim. Defaults to False.
+    :param dim: apply the dim style if True. Can be combined with bold. Defaults to False.
     :param underline: apply the underline style if True. Defaults to False.
     :return: the stylized string
     """
@@ -169,14 +174,18 @@ def style(text: Any, *, fg: str = '', bg: str = '', bold: bool = False, underlin
         removals.append(BG_RESET)
 
     if bold:
-        additions.append(Style.BRIGHT)
-        removals.append(Style.NORMAL)
+        additions.append(INTENSITY_BRIGHT)
+        removals.append(INTENSITY_NORMAL)
+
+    if dim:
+        additions.append(INTENSITY_DIM)
+        removals.append(INTENSITY_NORMAL)
 
     if underline:
         additions.append(UNDERLINE_ENABLE)
         removals.append(UNDERLINE_DISABLE)
 
-    # Combine the ANSI escape sequences with the text
+    # Combine the ANSI style sequences with the text
     return "".join(additions) + text + "".join(removals)
 
 
@@ -206,14 +215,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
 

cmd2/argparse_completer.py

@@ -444,11 +444,11 @@ def _format_completions(self, action, completions: List[Union[str, CompletionIte
                 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 @@ def _complete_for_arg(self, arg_action: argparse.Action,
     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:

cmd2/argparse_custom.py

@@ -802,11 +802,11 @@ def format_help(self) -> str:
         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

cmd2/cmd2.py

@@ -206,11 +206,11 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
         # To make an attribute settable with the "do_set" command, add it to this ...
         self.settable = \
             {
-                # allow_ansi is a special case in which it's an application-wide setting defined in ansi.py
-                'allow_ansi': ('Allow ANSI escape sequences in output '
-                               '(valid values: {}, {}, {})'.format(ansi.ANSI_TERMINAL,
-                                                                   ansi.ANSI_ALWAYS,
-                                                                   ansi.ANSI_NEVER)),
+                # allow_style is a special case in which it's an application-wide setting defined in ansi.py
+                'allow_style': ('Allow ANSI text style sequences in output '
+                                '(valid values: {}, {}, {})'.format(ansi.STYLE_TERMINAL,
+                                                                    ansi.STYLE_ALWAYS,
+                                                                    ansi.STYLE_NEVER)),
                 'continuation_prompt': 'On 2nd+ line of input',
                 'debug': 'Show full error stack on error',
                 'echo': 'Echo command issued into output',
@@ -366,7 +366,7 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
         else:
             # Here is the meaning of the various flags we are using with the less command:
             # -S causes lines longer than the screen width to be chopped (truncated) rather than wrapped
-            # -R causes ANSI "color" escape sequences to be output in raw form (i.e. colors are displayed)
+            # -R causes ANSI "style" escape sequences to be output in raw form (i.e. colors are displayed)
             # -X disables sending the termcap initialization and deinitialization strings to the terminal
             # -F causes less to automatically exit if the entire file can be displayed on the first screen
             self.pager = 'less -RXF'
@@ -395,38 +395,38 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
     # -----  Methods related to presenting output to the user -----
 
     @property
-    def allow_ansi(self) -> str:
-        """Read-only property needed to support do_set when it reads allow_ansi"""
-        return ansi.allow_ansi
+    def allow_style(self) -> str:
+        """Read-only property needed to support do_set when it reads allow_style"""
+        return ansi.allow_style
 
-    @allow_ansi.setter
-    def allow_ansi(self, new_val: str) -> None:
-        """Setter property needed to support do_set when it updates allow_ansi"""
+    @allow_style.setter
+    def allow_style(self, new_val: str) -> None:
+        """Setter property needed to support do_set when it updates allow_style"""
         new_val = new_val.lower()
-        if new_val == ansi.ANSI_TERMINAL.lower():
-            ansi.allow_ansi = ansi.ANSI_TERMINAL
-        elif new_val == ansi.ANSI_ALWAYS.lower():
-            ansi.allow_ansi = ansi.ANSI_ALWAYS
-        elif new_val == ansi.ANSI_NEVER.lower():
-            ansi.allow_ansi = ansi.ANSI_NEVER
+        if new_val == ansi.STYLE_TERMINAL.lower():
+            ansi.allow_style = ansi.STYLE_TERMINAL
+        elif new_val == ansi.STYLE_ALWAYS.lower():
+            ansi.allow_style = ansi.STYLE_ALWAYS
+        elif new_val == ansi.STYLE_NEVER.lower():
+            ansi.allow_style = ansi.STYLE_NEVER
         else:
-            self.perror('Invalid value: {} (valid values: {}, {}, {})'.format(new_val, ansi.ANSI_TERMINAL,
-                                                                              ansi.ANSI_ALWAYS, ansi.ANSI_NEVER))
+            self.perror('Invalid value: {} (valid values: {}, {}, {})'.format(new_val, ansi.STYLE_TERMINAL,
+                                                                              ansi.STYLE_ALWAYS, ansi.STYLE_NEVER))
 
     def _completion_supported(self) -> bool:
         """Return whether tab completion is supported"""
         return self.use_rawinput and self.completekey and rl_type != RlType.NONE
 
     @property
     def visible_prompt(self) -> str:
-        """Read-only property to get the visible prompt with any ANSI escape codes stripped.
+        """Read-only property to get the visible prompt with any ANSI style escape codes stripped.
 
         Used by transcript testing to make it easier and more reliable when users are doing things like coloring the
         prompt using ANSI color codes.
 
         :return: prompt stripped of any ANSI escape codes
         """
-        return ansi.strip_ansi(self.prompt)
+        return ansi.strip_style(self.prompt)
 
     def poutput(self, msg: Any = '', *, end: str = '\n') -> None:
         """Print message to self.stdout and appends a newline by default
@@ -439,7 +439,7 @@ def poutput(self, msg: Any = '', *, end: str = '\n') -> None:
         :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 @@ def perror(self, msg: Any = '', *, end: str = '\n', apply_style: bool = True) ->
             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
@@ -551,8 +551,8 @@ def ppaged(self, msg: Any, *, end: str = '\n', chop: bool = False) -> None:
             # Don't attempt to use a pager that can block if redirecting or running a script (either text or Python)
             # Also only attempt to use a pager if actually running in a real fully functional terminal
             if functional_terminal and not self._redirecting and not self.in_pyscript() and not self.in_script():
-                if ansi.allow_ansi.lower() == ansi.ANSI_NEVER.lower():
-                    msg_str = ansi.strip_ansi(msg_str)
+                if ansi.allow_style.lower() == ansi.STYLE_NEVER.lower():
+                    msg_str = ansi.strip_style(msg_str)
                 msg_str += end
 
                 pager = self.pager
@@ -1096,7 +1096,7 @@ def _display_matches_gnu_readline(self, substitution: str, matches: List[str],
                 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 @@ def _print_topics(self, header: str, cmds: List[str], verbose: bool) -> None:
                 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 TestMyAppCase(Cmd2TestCase):
         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)

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