Deprecated CmdResult helper class and promoted CommandResult

These classes are subtly different, particularly in terms of their truthiness.

CmdResult
- attributes:  out, err, war
- truthy:  if err is falsy

CommandResult
- attributes:  stdout, stderr, data
- truthy:  if err is falsy AND data is not None

So CmdResult was oriented to provide essentially info, error, and warning messages to the user (typically as stirngs), whereas CommandResult is geared towards providing info and error messages to the user as strings in addition to data to the user in a command-specific format which is arbitrary other than it should never be None if the command succeeds.

Author: tleonhardt

CHANGELOG.md

@@ -9,6 +9,11 @@
     * Added ``chop`` argument to ``cmd2.Cmd.ppaged()`` method for displaying output using a pager
         * If ``chop`` is ``False``, then ``self.pager`` is used as the pager
         * Otherwise ``self.pager_chop`` is used as the pager
+* Deprecations
+    * The ``CmdResult`` helper class is *deprecated* and replaced by the improved ``CommandResult`` class
+        * ``CommandResult`` has the following attributes: **stdout**, **stderr**, and **data**
+            * ``CmdResult`` had attributes of: **out**, **err**, **war**
+        * ``CmdResult`` will be deleted in the next release
 
 ## 0.8.8 (TBD, 2018)
 * Bug Fixes

cmd2/__init__.py

@@ -1,5 +1,6 @@
 #
 # -*- coding: utf-8 -*-
 """This simply imports certain things for backwards compatibility."""
-from .cmd2 import __version__, Cmd, CmdResult, Statement, EmptyStatement, categorize
+from .cmd2 import __version__, Cmd, Statement, EmptyStatement, categorize
 from .cmd2 import with_argument_list, with_argparser, with_argparser_and_unknown_args, with_category
+from .pyscript_bridge import CommandResult

cmd2/cmd2.py

@@ -3219,7 +3219,7 @@ def restore(self) -> None:
 
 
 class CmdResult(utils.namedtuple_with_two_defaults('CmdResult', ['out', 'err', 'war'])):
-    """Derive a class to store results from a named tuple so we can tweak dunder methods for convenience.
+    """DEPRECATED: Derive a class to store results from a named tuple so we can tweak dunder methods for convenience.
 
     This is provided as a convenience and an example for one possible way for end users to store results in
     the self._last_result attribute of cmd2.Cmd class instances.  See the "python_scripting.py" example for how it can

cmd2/pyscript_bridge.py

@@ -22,7 +22,7 @@
 from .utils import namedtuple_with_defaults
 
 
-class CommandResult(namedtuple_with_defaults('CmdResult', ['stdout', 'stderr', 'data'])):
+class CommandResult(namedtuple_with_defaults('CommandResult', ['stdout', 'stderr', 'data'])):
     """Encapsulates the results from a command.
 
     Named tuple attributes

docs/argument_processing.rst

@@ -333,7 +333,7 @@ Here's what it looks like::
         if unknown:
             self.perror("dir does not take any positional arguments:", traceback_war=False)
             self.do_help('dir')
-            self._last_result = CmdResult('', 'Bad arguments')
+            self._last_result = CommandResult('', 'Bad arguments')
             return
 
         # Get the contents as a list

examples/python_scripting.py

@@ -56,15 +56,16 @@ def do_cd(self, arglist):
         if not arglist or len(arglist) != 1:
             self.perror("cd requires exactly 1 argument:", traceback_war=False)
             self.do_help('cd')
-            self._last_result = cmd2.CmdResult('', 'Bad arguments')
+            self._last_result = cmd2.CommandResult('', 'Bad arguments')
             return
 
         # Convert relative paths to absolute paths
         path = os.path.abspath(os.path.expanduser(arglist[0]))
 
         # Make sure the directory exists, is a directory, and we have read access
         out = ''
-        err = ''
+        err = None
+        data = None
         if not os.path.isdir(path):
             err = '{!r} is not a directory'.format(path)
         elif not os.access(path, os.R_OK):
@@ -77,10 +78,11 @@ def do_cd(self, arglist):
             else:
                 out = 'Successfully changed directory to {!r}\n'.format(path)
                 self.stdout.write(out)
+                data = path
 
         if err:
             self.perror(err, traceback_war=False)
-        self._last_result = cmd2.CmdResult(out, err)
+        self._last_result = cmd2.CommandResult(out, err, data)
 
     # Enable tab completion for cd command
     def complete_cd(self, text, line, begidx, endidx):
@@ -96,7 +98,7 @@ def do_dir(self, args, unknown):
         if unknown:
             self.perror("dir does not take any positional arguments:", traceback_war=False)
             self.do_help('dir')
-            self._last_result = cmd2.CmdResult('', 'Bad arguments')
+            self._last_result = cmd2.CommandResult('', 'Bad arguments')
             return
 
         # Get the contents as a list
@@ -109,7 +111,7 @@ def do_dir(self, args, unknown):
             self.stdout.write(fmt.format(f))
         self.stdout.write('\n')
 
-        self._last_result = cmd2.CmdResult(contents)
+        self._last_result = cmd2.CommandResult(data=contents)
 
 
 if __name__ == '__main__':

examples/scripts/conditional.py

@@ -30,6 +30,7 @@
 if self._last_result:
     print('\nContents of directory {!r}:'.format(directory))
     app('dir -l')
+    print('{}\n'.format(self._last_result.data))
 
     # Change back to where we were
     print('Changing back to original directory: {!r}'.format(original_dir))

tests/test_cmd2.py

@@ -1468,32 +1468,33 @@ def test_clipboard_failure(base_app, capsys):
     assert "Cannot redirect to paste buffer; install 'pyperclip' and re-run to enable" in err
 
 
-class CmdResultApp(cmd2.Cmd):
+class CommandResultApp(cmd2.Cmd):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
     def do_affirmative(self, arg):
-        self._last_result = cmd2.CmdResult(arg)
+        self._last_result = cmd2.CommandResult(arg, data=True)
 
     def do_negative(self, arg):
-        self._last_result = cmd2.CmdResult('', arg)
+        self._last_result = cmd2.CommandResult(arg)
 
 @pytest.fixture
-def cmdresult_app():
-    app = CmdResultApp()
+def commandresult_app():
+    app = CommandResultApp()
     app.stdout = StdOut()
     return app
 
-def test_cmdresult(cmdresult_app):
+def test_commandresult_truthy(commandresult_app):
     arg = 'foo'
-    run_cmd(cmdresult_app, 'affirmative {}'.format(arg))
-    assert cmdresult_app._last_result
-    assert cmdresult_app._last_result == cmd2.CmdResult(arg)
+    run_cmd(commandresult_app, 'affirmative {}'.format(arg))
+    assert commandresult_app._last_result
+    assert commandresult_app._last_result == cmd2.CommandResult(arg, data=True)
 
+def test_commandresult_falsy(commandresult_app):
     arg = 'bar'
-    run_cmd(cmdresult_app, 'negative {}'.format(arg))
-    assert not cmdresult_app._last_result
-    assert cmdresult_app._last_result == cmd2.CmdResult('', arg)
+    run_cmd(commandresult_app, 'negative {}'.format(arg))
+    assert not commandresult_app._last_result
+    assert commandresult_app._last_result == cmd2.CommandResult(arg)
 
 
 def test_is_text_file_bad_input(base_app):