Renamed colors setting to allow_ansi

Author: kmvanbrunt

cmd2/ansi.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-"""Support for ANSI escape codes 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"""
 import functools
 import re
 from typing import Any
@@ -8,7 +8,7 @@
 from colorama import Fore, Back, Style
 from wcwidth import wcswidth
 
-# Regular expression to match ANSI escape codes
+# Regular expression to match ANSI escape sequences
 ANSI_ESCAPE_RE = re.compile(r'\x1b[^m]*m')
 
 # Foreground color presets
@@ -55,10 +55,10 @@
 
 
 def strip_ansi(text: str) -> str:
-    """Strip ANSI escape codes from a string.
+    """Strip ANSI escape sequences from a string.
 
-    :param text: string which may contain ANSI escape codes
-    :return: the same string with any ANSI escape codes removed
+    :param text: string which may contain ANSI escape sequences
+    :return: the same string with any ANSI escape sequences removed
     """
     return ANSI_ESCAPE_RE.sub('', text)
 
@@ -69,11 +69,11 @@ def ansi_safe_wcswidth(text: str) -> int:
 
     :param text: the string being measured
     """
-    # Strip ANSI escape codes since they cause wcswidth to return -1
+    # Strip ANSI escape sequences since they cause wcswidth to return -1
     return wcswidth(strip_ansi(text))
 
 
-# ANSI escape strings not provided by colorama
+# ANSI escape sequences not provided by colorama
 UNDERLINE_ENABLE = colorama.ansi.code_to_chars(4)
 UNDERLINE_DISABLE = colorama.ansi.code_to_chars(24)
 
@@ -122,7 +122,7 @@ def style(text: Any, *, fg: str = '', bg: str = '', bold: bool = False, underlin
         additions.append(UNDERLINE_ENABLE)
         removals.append(UNDERLINE_DISABLE)
 
-    # Combine the ANSI escape strings with the text
+    # Combine the ANSI escape sequences with the text
     return "".join(additions) + text + "".join(removals)
 
 

cmd2/cmd2.py

@@ -374,7 +374,7 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
         self.quit_on_sigint = False  # Quit the loop on interrupt instead of just resetting prompt
 
         # Attributes which ARE dynamically settable at runtime
-        self.colors = constants.ANSI_TERMINAL
+        self.allow_ansi = constants.ANSI_TERMINAL
         self.continuation_prompt = '> '
         self.debug = False
         self.echo = False
@@ -385,7 +385,7 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
         self.timing = False  # Prints elapsed time for each command
 
         # To make an attribute settable with the "do_set" command, add it to this ...
-        self.settable = {'colors': 'Allow colorized output (valid values: Terminal, Always, Never)',
+        self.settable = {'allow_ansi': 'Allow ANSI escape sequences in output (valid values: Terminal, Always, Never)',
                          'continuation_prompt': 'On 2nd+ line of input',
                          'debug': 'Show full error stack on error',
                          'echo': 'Echo command issued into output',
@@ -581,8 +581,8 @@ def _decolorized_write(self, fileobj: IO, msg: str) -> None:
 
         Honor the current colors setting, which requires us to check whether the fileobject is a tty.
         """
-        if self.colors.lower() == constants.ANSI_NEVER.lower() or \
-                (self.colors.lower() == constants.ANSI_TERMINAL.lower() and not fileobj.isatty()):
+        if self.allow_ansi.lower() == constants.ANSI_NEVER.lower() or \
+                (self.allow_ansi.lower() == constants.ANSI_TERMINAL.lower() and not fileobj.isatty()):
             msg = ansi.strip_ansi(msg)
         fileobj.write(msg)
 
@@ -691,7 +691,7 @@ def ppaged(self, msg: str, 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_py and not self._script_dir:
-                    if self.colors.lower() == constants.ANSI_NEVER.lower():
+                    if self.allow_ansi.lower() == constants.ANSI_NEVER.lower():
                         msg_str = ansi.strip_ansi(msg_str)
 
                     pager = self.pager

cmd2/constants.py

@@ -17,7 +17,7 @@
 
 DEFAULT_SHORTCUTS = {'?': 'help', '!': 'shell', '@': 'run_script', '@@': '_relative_run_script'}
 
-# Values for cmd2 setting that determines when to allow ANSI escape codes
+# Values for cmd2's allow_ansi setting
 ANSI_NEVER = 'Never'
 ANSI_TERMINAL = 'Terminal'
 ANSI_ALWAYS = 'Always'

tests/conftest.py

@@ -88,7 +88,7 @@ def verify_help_text(cmd2_app: cmd2.Cmd, help_output: Union[str, List[str]]) ->
 """
 
 # Output from the show command with default settings
-SHOW_TXT = """colors: Terminal
+SHOW_TXT = """allow_ansi: Terminal
 continuation_prompt: >
 debug: False
 echo: False
@@ -101,7 +101,7 @@ def verify_help_text(cmd2_app: cmd2.Cmd, help_output: Union[str, List[str]]) ->
 """
 
 SHOW_LONG = """
-colors: Terminal          # Allow colorized output (valid values: Terminal, Always, Never)
+allow_ansi: Terminal      # Allow ANSI escape sequences in output (valid values: Terminal, Always, Never)
 continuation_prompt: >    # On 2nd+ line of input
 debug: False              # Show full error stack on error
 echo: False               # Echo command issued into output

tests/test_cmd2.py

@@ -1356,15 +1356,15 @@ def test_pseudo_raw_input_piped_rawinput_true_echo_true(capsys):
     app, out = piped_rawinput_true(capsys, True, command)
     out = out.splitlines()
     assert out[0] == '{}{}'.format(app.prompt, command)
-    assert out[1].startswith('colors:')
+    assert out[1].startswith('allow_ansi:')
 
 # using the decorator puts the original input function back when this unit test returns
 @mock.patch('builtins.input', mock.MagicMock(name='input', side_effect=['set', EOFError]))
 def test_pseudo_raw_input_piped_rawinput_true_echo_false(capsys):
     command = 'set'
     app, out = piped_rawinput_true(capsys, False, command)
     firstline = out.splitlines()[0]
-    assert firstline.startswith('colors:')
+    assert firstline.startswith('allow_ansi:')
     assert not '{}{}'.format(app.prompt, command) in out
 
 # the next helper function and two tests check for piped
@@ -1383,13 +1383,13 @@ def test_pseudo_raw_input_piped_rawinput_false_echo_true(capsys):
     app, out = piped_rawinput_false(capsys, True, command)
     out = out.splitlines()
     assert out[0] == '{}{}'.format(app.prompt, command)
-    assert out[1].startswith('colors:')
+    assert out[1].startswith('allow_ansi:')
 
 def test_pseudo_raw_input_piped_rawinput_false_echo_false(capsys):
     command = 'set'
     app, out = piped_rawinput_false(capsys, False, command)
     firstline = out.splitlines()[0]
-    assert firstline.startswith('colors:')
+    assert firstline.startswith('allow_ansi:')
     assert not '{}{}'.format(app.prompt, command) in out
 
 
@@ -1459,15 +1459,15 @@ def test_poutput_none(outsim_app):
 
 def test_poutput_color_always(outsim_app):
     msg = 'Hello World'
-    outsim_app.colors = 'Always'
+    outsim_app.allow_ansi = 'Always'
     outsim_app.poutput(ansi.style(msg, fg='cyan'))
     out = outsim_app.stdout.getvalue()
     expected = Fore.CYAN + msg + Fore.RESET + '\n'
     assert out == expected
 
 def test_poutput_color_never(outsim_app):
     msg = 'Hello World'
-    outsim_app.colors = 'Never'
+    outsim_app.allow_ansi = 'Never'
     outsim_app.poutput(ansi.style(msg, fg='cyan'))
     out = outsim_app.stdout.getvalue()
     expected = msg + '\n'
@@ -1764,19 +1764,19 @@ def test_ppaged(outsim_app):
     out = outsim_app.stdout.getvalue()
     assert out == msg + end
 
-def test_ppaged_strips_color_when_redirecting(outsim_app):
+def test_ppaged_strips_ansi_when_redirecting(outsim_app):
     msg = 'testing...'
     end = '\n'
-    outsim_app.colors = cmd2.constants.ANSI_TERMINAL
+    outsim_app.allow_ansi = cmd2.constants.ANSI_TERMINAL
     outsim_app._redirecting = True
     outsim_app.ppaged(Fore.RED + msg)
     out = outsim_app.stdout.getvalue()
     assert out == msg + end
 
-def test_ppaged_strips_color_when_redirecting_if_always(outsim_app):
+def test_ppaged_strips_ansi_when_redirecting_if_always(outsim_app):
     msg = 'testing...'
     end = '\n'
-    outsim_app.colors = cmd2.constants.ANSI_ALWAYS
+    outsim_app.allow_ansi = cmd2.constants.ANSI_ALWAYS
     outsim_app._redirecting = True
     outsim_app.ppaged(Fore.RED + msg)
     out = outsim_app.stdout.getvalue()
@@ -1895,7 +1895,7 @@ def test_exit_code_nonzero(exit_code_repl):
     assert out == expected
 
 
-class ColorsApp(cmd2.Cmd):
+class AnsiApp(cmd2.Cmd):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
@@ -1910,13 +1910,13 @@ def do_echo_error(self, args):
         # perror uses colors by default
         self.perror(args)
 
-def test_colors_default():
-    app = ColorsApp()
-    assert app.colors == cmd2.constants.ANSI_TERMINAL
+def test_ansi_default():
+    app = AnsiApp()
+    assert app.allow_ansi == cmd2.constants.ANSI_TERMINAL
 
-def test_colors_pouterr_always_tty(mocker, capsys):
-    app = ColorsApp()
-    app.colors = cmd2.constants.ANSI_ALWAYS
+def test_ansi_pouterr_always_tty(mocker, capsys):
+    app = AnsiApp()
+    app.allow_ansi = cmd2.constants.ANSI_ALWAYS
     mocker.patch.object(app.stdout, 'isatty', return_value=True)
     mocker.patch.object(sys.stderr, 'isatty', return_value=True)
 
@@ -1936,9 +1936,9 @@ def test_colors_pouterr_always_tty(mocker, capsys):
     assert len(err) > len('oopsie\n')
     assert 'oopsie' in err
 
-def test_colors_pouterr_always_notty(mocker, capsys):
-    app = ColorsApp()
-    app.colors = cmd2.constants.ANSI_ALWAYS
+def test_ansi_pouterr_always_notty(mocker, capsys):
+    app = AnsiApp()
+    app.allow_ansi = cmd2.constants.ANSI_ALWAYS
     mocker.patch.object(app.stdout, 'isatty', return_value=False)
     mocker.patch.object(sys.stderr, 'isatty', return_value=False)
 
@@ -1958,9 +1958,9 @@ def test_colors_pouterr_always_notty(mocker, capsys):
     assert len(err) > len('oopsie\n')
     assert 'oopsie' in err
 
-def test_colors_terminal_tty(mocker, capsys):
-    app = ColorsApp()
-    app.colors = cmd2.constants.ANSI_TERMINAL
+def test_ansi_terminal_tty(mocker, capsys):
+    app = AnsiApp()
+    app.allow_ansi = cmd2.constants.ANSI_TERMINAL
     mocker.patch.object(app.stdout, 'isatty', return_value=True)
     mocker.patch.object(sys.stderr, 'isatty', return_value=True)
 
@@ -1979,9 +1979,9 @@ def test_colors_terminal_tty(mocker, capsys):
     assert len(err) > len('oopsie\n')
     assert 'oopsie' in err
 
-def test_colors_terminal_notty(mocker, capsys):
-    app = ColorsApp()
-    app.colors = cmd2.constants.ANSI_TERMINAL
+def test_ansi_terminal_notty(mocker, capsys):
+    app = AnsiApp()
+    app.allow_ansi = cmd2.constants.ANSI_TERMINAL
     mocker.patch.object(app.stdout, 'isatty', return_value=False)
     mocker.patch.object(sys.stderr, 'isatty', return_value=False)
 
@@ -1993,9 +1993,9 @@ def test_colors_terminal_notty(mocker, capsys):
     out, err = capsys.readouterr()
     assert out == err == 'oopsie\n'
 
-def test_colors_never_tty(mocker, capsys):
-    app = ColorsApp()
-    app.colors = cmd2.constants.ANSI_NEVER
+def test_ansi_never_tty(mocker, capsys):
+    app = AnsiApp()
+    app.allow_ansi = cmd2.constants.ANSI_NEVER
     mocker.patch.object(app.stdout, 'isatty', return_value=True)
     mocker.patch.object(sys.stderr, 'isatty', return_value=True)
 
@@ -2007,9 +2007,9 @@ def test_colors_never_tty(mocker, capsys):
     out, err = capsys.readouterr()
     assert out == err == 'oopsie\n'
 
-def test_colors_never_notty(mocker, capsys):
-    app = ColorsApp()
-    app.colors = cmd2.constants.ANSI_NEVER
+def test_ansi_never_notty(mocker, capsys):
+    app = AnsiApp()
+    app.allow_ansi = cmd2.constants.ANSI_NEVER
     mocker.patch.object(app.stdout, 'isatty', return_value=False)
     mocker.patch.object(sys.stderr, 'isatty', return_value=False)
 

tests/transcripts/regex_set.txt

@@ -4,7 +4,7 @@
 # Regexes on prompts just make the trailing space obvious
 
 (Cmd) set
-colors: /(Terminal|Always|Never)/
+allow_ansi: /(Terminal|Always|Never)/
 continuation_prompt: >/ /
 debug: False
 echo: False