Merge pull request #261 from python-cmd2/automated_transcripts

Fixed issue with automated transcript generation via "history -t"

Author: tleonhardt

CHANGELOG.md

@@ -1,4 +1,4 @@
-## 0.8.0 (TBD, 2018)
+## 0.8.0 (February TBD, 2018)
 * Bug Fixes
     * Fixed unit tests on Python 3.7 due to changes in how re.escape() behaves in Python 3.7
     * Fixed a bug where unknown commands were getting saved in the history
@@ -21,7 +21,7 @@
     * The **set** command now has an additional **-a/--all** option to also display read-only settings
     * The **history** command can now run, edit, and save prior commands, in addition to displaying prior commands.
     * The **history** command can now automatically generate a transcript file for regression testing
-        * This feature works imperfectly at the moment, but it is still quite useful
+        * This makes creating regression tests for your ``cmd2`` application trivial
 * Commands Removed
     * The **cmdenvironment** has been removed and its functionality incorporated into the **-a/--all** argument to **set**
     * The **show** command has been removed.  Its functionality has always existing within **set** and continues to do so

README.md

@@ -36,7 +36,15 @@ Main Features
 - Windows, macOS, and Linux support
 - Trivial to provide built-in help for all commands
 - Built-in regression testing framework for your applications (transcript-based testing)
+- Transcripts for use with built-in regression can be automatically generated from `history -t`
 
+Plan for dropping Python 2.7 support
+------------------------------------
+Support for Python 2.7 will be discontinued on Aug 31, 2018.  After that date, new releases of `cmd2` will only support
+Python 3.  Older releases of `cmd2` will of course continue to support Python 2.7.
+
+Supporting Python 2 is an increasing burden on our limited resources.  Switching to support only Python 3 will allow
+us to clean up the codebase, remove some cruft, and focus on developing new features.
 
 Installation
 ------------

cmd2.py

@@ -1913,6 +1913,13 @@ def do_history(self, args):
             # Set echo back to its original state
             self.echo = saved_echo
 
+            # Post-process the file to escape un-escaped "/" regex escapes
+            with open(args.transcript, 'r') as fin:
+                data = fin.read()
+            post_processed_data = data.replace('/', '\/')
+            with open(args.transcript, 'w') as fout:
+                fout.write(post_processed_data)
+
             plural = 's' if len(history) > 1 else ''
             self.pfeedback('{} command{} and outputs saved to transcript file {!r}'.format(len(history), plural,
                                                                                            args.transcript))

docs/transcript.rst

@@ -13,6 +13,21 @@ from commands that produce dynamic or variable output.
 Creating a transcript
 =====================
 
+Automatically
+-------------
+A transcript can automatically generated based upon commands previously executed in the *history*::
+
+    (Cmd) help
+    ...
+    (Cmd) help history
+    ...
+    (Cmd) history 1:2 -t transcript.txt
+    2 commands and outputs saved to transcript file 'transcript.txt'
+
+This is by far the easiest way to generate a transcript.
+
+Manually
+--------
 Here's a transcript created from ``python examples/example.py``::
 
    (Cmd) say -r 3 Goodnight, Gracie
@@ -38,9 +53,9 @@ lines of the transcript as comments::
    # Lines at the beginning of the transcript that do not
    ; start with the prompt i.e. '(Cmd) ' are ignored.
    /* You can use them for comments. */
-   
+
    All six of these lines before the first prompt are treated as comments.
-   
+
    (Cmd) say -r 3 Goodnight, Gracie
    Goodnight, Gracie
    Goodnight, Gracie
@@ -105,21 +120,21 @@ the path instead of specifying it verbatim, or we can escape the slashes::
    trailing spaces which are impossible to see. Instead of leaving them
    invisible, you can add a regular expression to match them, so that you can
    see where they are when you look at the transcript::
-   
+
       (Cmd) set prompt
       prompt: (Cmd)/ /
-   
+
    Some terminal emulators strip trailing space when you copy text from them.
    This could make the actual data generated by your app different than the
    text you pasted into the transcript, and it might not be readily obvious why
    the transcript is not passing. Consider using :ref:`output_redirection` to
    the clipboard or to a file to ensure you accurately capture the output of
    your command.
-   
+
    If you aren't using regular expressions, make sure the newlines at the end
    of your transcript exactly match the output of your commands. A common cause
    of a failing transcript is an extra or missing newline.
-   
+
    If you are using regular expressions, be aware that depending on how you
    write your regex, the newlines after the regex may or may not matter.
    ``\Z`` matches *after* the newline at the end of the string, whereas