Merge branch 'master' into instance_variables

Author: tleonhardt

cmd2.py

@@ -30,6 +30,7 @@
 import codecs
 import collections
 import datetime
+import functools
 import glob
 import io
 import optparse
@@ -271,6 +272,7 @@ def with_argument_list(func):
     method. Default passes a string of whatever the user typed.
     With this decorator, the decorated method will receive a list
     of arguments parsed from user input using shlex.split()."""
+    @functools.wraps(func)
     def cmd_wrapper(self, cmdline):
         lexed_arglist = parse_quoted_string(cmdline)
         func(self, lexed_arglist)
@@ -288,6 +290,7 @@ def with_argparser_and_unknown_args(argparser, subcommand_names=None):
     :return: function that gets passed parsed args and a list of unknown args
     """
     def arg_decorator(func):
+        @functools.wraps(func)
         def cmd_wrapper(instance, cmdline):
             lexed_arglist = parse_quoted_string(cmdline)
             args, unknown = argparser.parse_known_args(lexed_arglist)
@@ -324,6 +327,7 @@ def with_argparser(argparser, subcommand_names=None):
     :return: function that gets passed parsed args
     """
     def arg_decorator(func):
+        @functools.wraps(func)
         def cmd_wrapper(instance, cmdline):
             lexed_arglist = parse_quoted_string(cmdline)
             args = argparser.parse_args(lexed_arglist)
@@ -387,6 +391,7 @@ def option_setup(func):
             option_parser.set_usage("%s %s" % (func.__name__[3:], arg_desc))
         option_parser._func = func
 
+        @functools.wraps(func)
         def new_func(instance, arg):
             """For @options commands this replaces the actual do_* methods in the instance __dict__.
 

docs/transcript.rst

@@ -26,6 +26,12 @@ A transcript can automatically generated based upon commands previously executed
 
 This is by far the easiest way to generate a transcript.
 
+.. warning::
+
+   Make sure you use the **poutput()** method in your ``cmd2`` application for generating command output.  This method
+   of the ``cmd2.Cmd`` class ensure that output is properly redirected when redirecting to a file, piping to a shell
+   command, and when generating a transcript.
+
 Manually
 --------
 Here's a transcript created from ``python examples/example.py``::

docs/unfreefeatures.rst

@@ -155,9 +155,14 @@ but ``print`` decreases output flexibility).  ``cmd2`` applications can use
 ``self.poutput('output')``, ``self.pfeedback('message')``, and ``self.perror('errmsg')``
 instead.  These methods have these advantages:
 
+- Handle output redirection to file and/or pipe appropriately
 - More concise
     - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter.
 
+.. automethod:: cmd2.Cmd.poutput
+.. automethod:: cmd2.Cmd.perror
+.. automethod:: cmd2.Cmd.pfeedback
+
 
 color
 =====