Updated documentation and examples

Added information related to the new pyscript command.

The old way of running Python scripts via "py run()" should be considered deprecated.  The new "pyscript" command
is superior in two significant ways:
1) It supports tab-completion of file system paths
2) It allows the user to pass command-line arguments to scripts

Author: tleonhardt

README.md

@@ -36,6 +36,7 @@ cmd2 provides the following features, in addition to those already existing in c
 - Simple transcript-based application testing
 - Unicode character support (*Python 3 only*)
 - Path completion for ``edit``, ``load``, ``save``, and ``shell`` commands
+- Integrated Python scripting capability via ``pyscript`` and ``py``
 
 Instructions for implementing each feature follow.
 

docs/freefeatures.rst

@@ -176,6 +176,35 @@ conditional control flow logic.  See the **python_scripting.py** ``cmd2`` applic
 the **script_conditional.py** script in the ``examples`` source code directory for an
 example of how to achieve this in your own applications.
 
+Using ``py`` to run scripts directly is considered deprecated.  The newer ``pyscript`` command
+is superior for doing this in two primary ways:
+
+- it supports tab-completion of file system paths
+- it has the ability to pass command-line arguments to the scripts invoked
+
+There are no disadvantages to using ``pyscript`` as opposed to ``py run()``.  A simple example
+of using ``pyscript`` is shown below  along with the **examples/arg_printer.py** script::
+
+    (Cmd) pyscript examples/arg_printer.py foo bar baz
+    Running Python script 'arg_printer.py' which was called with 3 arguments
+    arg 1: 'foo'
+    arg 2: 'bar'
+    arg 3: 'baz'
+
+.. note::
+
+    If you want to be able to pass arguments with spaces to scripts, then we strongly recommend setting the
+    cmd2 global variable ``USE_ARG_LIST`` to ``True`` in your application using the ``set_use_arg_list`` function.
+    This passes all arguments to ``@options`` commands as a list of strings instead of a single string.
+
+    Once this option is set, you can then put arguments in quotes like so::
+
+        (Cmd) pyscript examples/arg_printer.py hello '23 fnord'
+        Running Python script 'arg_printer.py' which was called with 2 arguments
+        arg 1: 'hello'
+        arg 2: '23 fnord'
+
+
 IPython (optional)
 ==================
 

docs/unfreefeatures.rst

@@ -204,7 +204,7 @@ There are three functions which can globally effect how arguments are parsed for
 .. note::
 
    Since optparse_ has been deprecated since Python 3.2, the ``cmd2`` developers plan to replace optparse_ with
-   argparse_ in the next version of ``cmd2``.  We will endeavor to keep the API as identical as possible when this
+   argparse_ at some point in the future.  We will endeavor to keep the API as identical as possible when this
    change occurs.
 
 .. _optparse: https://docs.python.org/3/library/optparse.html

examples/arg_printer.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python
 # coding=utf-8
+import os
 import sys
-print("Running Python script {!r} which was called with {} arguments".format(sys.argv[0], len(sys.argv) - 1))
+print("Running Python script {!r} which was called with {} arguments".format(os.path.basename(sys.argv[0]),
+                                                                             len(sys.argv) - 1))
 for i, arg in enumerate(sys.argv[1:]):
     print("arg {}: {!r}".format(i+1, arg))

examples/python_scripting.py

@@ -9,8 +9,8 @@
 
 However, there comes a time when technical end users want more capability and power.  In particular it is common that
 users will want to create a script with conditional control flow - where the next command run will depend on the results
-from the previous command.  This is where the ability to run Python scripts inside a cmd2 application via the py command
-and the "py run('myscript.py')" syntax comes into play.
+from the previous command.  This is where the ability to run Python scripts inside a cmd2 application via the pyscript
+command and the "pyscript <script> [arguments]" syntax comes into play.
 
 This application and the "script_conditional.py" script serve as an example for one way in which this can be done.
 """

examples/script_conditional.py

@@ -4,27 +4,36 @@
 
 To run it you should do the following:
     ./python_scripting.py
-    py run('script_conditional.py')
+    pyscript script_conditional.py directory_path
 
 Note: The "cmd" function is defined within the cmd2 embedded Python environment and in there "self" is your cmd2
 application instance.
 """
+import os
+import sys
 
-# Try to change to a non-existent directory
-cmd('cd foobar')
+
+if len(sys.argv) > 1:
+    directory = sys.argv[1]
+    print('Using specified directory: {!r}'.format(directory))
+else:
+    directory = 'foobar'
+    print('Using default directory: {!r}'.format(directory))
+
+# Keep track of where we stared
+original_dir = os.getcwd()
+
+# Try to change to the specified directory
+cmd('cd {}'.format(directory))
 
 # Conditionally do something based on the results of the last command
 if self._last_result:
-    print('Contents of foobar directory:')
-    cmd('dir')
+    print('\nContents of directory {!r}:'.format(directory))
+    cmd('dir -l')
 
     # Change back to where we were
-    cmd('cd ..')
+    print('Changing back to original directory: {!r}'.format(original_dir))
+    cmd('cd {}'.format(original_dir))
 else:
-    # Change to parent directory
-    cmd('cd ..')
-    print('Contents of parent directory:')
-    cmd('dir')
-
-    # Change back to where we were
-    cmd('cd examples')
+    # cd command failed, print a warning
+    print('Failed to change directory to {!r}'.format(directory))