diff options
| -rwxr-xr-x | README.md | 1 | ||||
| -rw-r--r-- | docs/freefeatures.rst | 29 | ||||
| -rw-r--r-- | docs/unfreefeatures.rst | 2 | ||||
| -rwxr-xr-x | examples/arg_printer.py | 4 | ||||
| -rwxr-xr-x | examples/python_scripting.py | 4 | ||||
| -rw-r--r-- | examples/script_conditional.py | 35 |
6 files changed, 58 insertions, 17 deletions
@@ -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. diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst index 5e354549..40243ce9 100644 --- a/docs/freefeatures.rst +++ b/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) ================== diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst index 84314689..5a504628 100644 --- a/docs/unfreefeatures.rst +++ b/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 diff --git a/examples/arg_printer.py b/examples/arg_printer.py index 42084d4e..848dcf99 100755 --- a/examples/arg_printer.py +++ b/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)) diff --git a/examples/python_scripting.py b/examples/python_scripting.py index baa15f3f..6c64dd9f 100755 --- a/examples/python_scripting.py +++ b/examples/python_scripting.py @@ -9,8 +9,8 @@ learn to create scripts. 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. """ diff --git a/examples/script_conditional.py b/examples/script_conditional.py index f0ded920..c26bd5fe 100644 --- a/examples/script_conditional.py +++ b/examples/script_conditional.py @@ -4,27 +4,36 @@ This is a Python script intended to be used with the "python_scripting.py" cmd2 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)) |