From 83f62cd6767810382e5a70ec6d0974ef661fc26b Mon Sep 17 00:00:00 2001 From: kotfu Date: Sun, 14 Jul 2019 00:06:20 -0600 Subject: Lots of work on the migrating documentation for #719 --- docs/features/clipboard.rst | 5 ++ docs/features/embedded_python_shells.rst | 133 ++++++++++++++++++++++++++++++- docs/features/generating_output.rst | 33 ++++++++ docs/features/index.rst | 1 + docs/features/misc.rst | 10 +++ 5 files changed, 181 insertions(+), 1 deletion(-) create mode 100644 docs/features/misc.rst (limited to 'docs/features') diff --git a/docs/features/clipboard.rst b/docs/features/clipboard.rst index d5048cc0..6df655f7 100644 --- a/docs/features/clipboard.rst +++ b/docs/features/clipboard.rst @@ -1,5 +1,10 @@ Clipboard Integration ===================== + - sent to the operating system paste buffer, by ending with a bare ``>``, as + in ``mycommand args >``. You can even append output to the current contents + of the paste buffer by ending your command with ``>>``. + + .. automodule:: cmd2.clipboard :members: diff --git a/docs/features/embedded_python_shells.rst b/docs/features/embedded_python_shells.rst index ace68877..7e8c027b 100644 --- a/docs/features/embedded_python_shells.rst +++ b/docs/features/embedded_python_shells.rst @@ -1,4 +1,135 @@ Embedded Python Shells ====================== -Describe ``py`` and optional ``ipy`` commands +The ``py`` command will run its arguments as a Python command. Entered without +arguments, it enters an interactive Python session. The session can call +"back" to your application through the name defined in ``self.pyscript_name`` +(defaults to ``app``). This wrapper provides access to execute commands in +your cmd2 application while maintaining isolation. + +You may optionally enable full access to to your application by setting +``locals_in_py`` to ``True``. Enabling this flag adds ``self`` to the python +session, which is a reference to your Cmd2 application. This can be useful for +debugging your application. To prevent users from enabling this ability +manually you'll need to remove ``locals_in_py`` from the ``settable`` +dictionary. + +The ``app`` object (or your custom name) provides access to application +commands through raw commands. For example, any application command call be +called with ``app("")``. + +:: + + >>> app('say --piglatin Blah') + lahBay + +More Python examples: + +:: + + (Cmd) py print("-".join("spelling")) + s-p-e-l-l-i-n-g + (Cmd) py + Python 3.5.3 (default, Jan 19 2017, 14:11:04) + [GCC 6.3.0 20170118] on linux + Type "help", "copyright", "credits" or "license" for more information. + (CmdLineApp) + + End with `Ctrl-D` (Unix) / `Ctrl-Z` (Windows), `quit()`, `exit()`. + Non-python commands can be issued with: app("your command") + Run python code from external script files with: run("script.py") + + >>> import os + >>> os.uname() + ('Linux', 'eee', '2.6.31-19-generic', '#56-Ubuntu SMP Thu Jan 28 01:26:53 UTC 2010', 'i686') + >>> app("say --piglatin {os}".format(os=os.uname()[0])) + inuxLay + >>> self.prompt + '(Cmd) ' + >>> self.prompt = 'Python was here > ' + >>> quit() + Python was here > + +Using the ``py`` command is tightly integrated with your main ``cmd2`` +application and any variables created or changed will persist for the life of +the application:: + + (Cmd) py x = 5 + (Cmd) py print(x) + 5 + +The ``py`` command also allows you to run Python scripts via ``py +run('myscript.py')``. This provides a more complicated and more powerful +scripting capability than that provided by the simple text file scripts +discussed in :ref:`scripts`. Python scripts can include conditional control +flow logic. See the **python_scripting.py** ``cmd2`` application and 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 +``run_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 ``run_pyscript`` as opposed to ``py +run()``. A simple example of using ``run_pyscript`` is shown below along with +the arg_printer_ script:: + + (Cmd) run_pyscript examples/scripts/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 commands, then we + strongly recommend using one of the decorators, such as + ``with_argument_list``. ``cmd2`` will pass your **do_*** methods a list of + arguments in this case. + + When using this decorator, you can then put arguments in quotes like so:: + + $ examples/arg_print.py + (Cmd) lprint foo "bar baz" + lprint was called with the following list of arguments: ['foo', 'bar baz'] + +.. _arg_printer: + https://github.com/python-cmd2/cmd2/blob/master/examples/scripts/arg_printer.py + + +IPython (optional) +------------------ + +**If** IPython_ is installed on the system **and** the ``cmd2.Cmd`` class is +instantiated with ``use_ipython=True``, then the optional ``ipy`` command will +be present:: + + from cmd2 import Cmd + class App(Cmd): + def __init__(self): + Cmd.__init__(self, use_ipython=True) + +The ``ipy`` command enters an interactive IPython_ session. Similar to an +interactive Python session, this shell can access your application instance via +``self`` and any changes to your application made via ``self`` will persist. +However, any local or global variable created within the ``ipy`` shell will not +persist. Within the ``ipy`` shell, you cannot call "back" to your application +with ``cmd("")``, however you can run commands directly like so:: + + self.onecmd_plus_hooks('help') + +IPython_ provides many advantages, including: + + * Comprehensive object introspection + * Get help on objects with ``?`` + * Extensible tab completion, with support by default for completion of + python variables and keywords + +The object introspection and tab completion make IPython particularly efficient +for debugging as well as for interactive experimentation and data analysis. + +.. _IPython: http://ipython.readthedocs.io + + diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst index 1dab6f64..5813322b 100644 --- a/docs/features/generating_output.rst +++ b/docs/features/generating_output.rst @@ -9,4 +9,37 @@ how to generate output - exceptions - color support +Output Redirection +------------------ + +As in a Unix shell, output of a command can be redirected: + + - sent to a file with ``>``, as in ``mycommand args > filename.txt`` + - appended to a file with ``>>``, as in ``mycommand args >> filename.txt`` + - piped (``|``) as input to operating-system commands, as in + ``mycommand args | wc`` + + + +.. note:: + + If you wish to disable cmd2's output redirection and pipes features, you can + do so by setting the ``allow_redirection`` attribute of your ``cmd2.Cmd`` + class instance to ``False``. This would be useful, for example, if you want + to restrict the ability for an end user to write to disk or interact with + shell commands for security reasons:: + + from cmd2 import Cmd + class App(Cmd): + def __init__(self): + self.allow_redirection = False + + cmd2's parser will still treat the ``>``, ``>>``, and `|` symbols as output + redirection and pipe symbols and will strip arguments after them from the + command line arguments accordingly. But output from a command will not be + redirected to a file or piped to a shell command. + +If you need to include any of these redirection characters in your command, you +can enclose them in quotation marks, ``mycommand 'with > in the argument'``. + diff --git a/docs/features/index.rst b/docs/features/index.rst index 3087031f..a793efbd 100644 --- a/docs/features/index.rst +++ b/docs/features/index.rst @@ -15,6 +15,7 @@ Features history hooks initialization + misc multiline_commands os plugins diff --git a/docs/features/misc.rst b/docs/features/misc.rst new file mode 100644 index 00000000..7165cb85 --- /dev/null +++ b/docs/features/misc.rst @@ -0,0 +1,10 @@ +Miscellaneous Features +====================== + + +Timer +----- + +Turn the timer setting on, and ``cmd2`` will show the wall time it takes for +each command to execute. + -- cgit v1.2.1 From 9325989ae5c7aa463b34bdc6997445a9603030d4 Mon Sep 17 00:00:00 2001 From: kotfu Date: Sun, 14 Jul 2019 21:31:23 -0600 Subject: Finish migration documentation for #719 --- docs/features/argument_processing.rst | 7 +++++-- docs/features/misc.rst | 5 +++++ 2 files changed, 10 insertions(+), 2 deletions(-) (limited to 'docs/features') diff --git a/docs/features/argument_processing.rst b/docs/features/argument_processing.rst index 5efc83ef..d0f2c137 100644 --- a/docs/features/argument_processing.rst +++ b/docs/features/argument_processing.rst @@ -4,8 +4,9 @@ Argument Processing =================== ``cmd2`` makes it easy to add sophisticated argument processing to your -commands using the ``argparse`` python module. ``cmd2`` handles the following -for you: +commands using the `argparse +`_ python module. ``cmd2`` +handles the following for you: 1. Parsing input and quoted strings like the Unix shell @@ -16,7 +17,9 @@ for you: The ``Namespace`` includes the ``Statement`` object that was created when parsing the command line. It is stored in the ``__statement__`` attribute of the ``Namespace``. + 4. Adds the usage message from the argument parser to your command. + 5. Checks if the ``-h/--help`` option is present, and if so, display the help message for the command diff --git a/docs/features/misc.rst b/docs/features/misc.rst index 7165cb85..4db9f682 100644 --- a/docs/features/misc.rst +++ b/docs/features/misc.rst @@ -8,3 +8,8 @@ Timer Turn the timer setting on, and ``cmd2`` will show the wall time it takes for each command to execute. + +Exiting +------- + +Mention quit, exit, and EOF handling built into ``cmd2``. -- cgit v1.2.1 From 901acfefffbc1efce28d0ea7adcc059098e97cd0 Mon Sep 17 00:00:00 2001 From: kotfu Date: Mon, 15 Jul 2019 22:04:01 -0600 Subject: Write clipboard feature page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It used to have a weak-sauce paste from the old documentation. Now it’s a real page. Addresses feedback in the PR. --- docs/features/clipboard.rst | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) (limited to 'docs/features') diff --git a/docs/features/clipboard.rst b/docs/features/clipboard.rst index 6df655f7..73e206c2 100644 --- a/docs/features/clipboard.rst +++ b/docs/features/clipboard.rst @@ -1,10 +1,33 @@ Clipboard Integration ===================== - - sent to the operating system paste buffer, by ending with a bare ``>``, as - in ``mycommand args >``. You can even append output to the current contents - of the paste buffer by ending your command with ``>>``. +Nearly every operating system has some notion of a short-term storage area +which can be accessed by any program. Usually this is called the clipboard, but +sometimes people refer to it as the paste buffer. +``cmd2`` integrates with the operating system clipboard using the `pyperclip +`_ module. Command output can be sent +to the clipboard by ending the command with a greater than symbol: + +.. code-block:: text + + mycommand args > + +Think of it as though you are redirecting output to an unnamed, ephemeral +place, you know, like the clipboard. You can also append output to the current +contents of the clipboard by ending the command with two greater than symbols: + +.. code-block:: text + + mycommand arg1 arg2 >> + + +Developers +---------- + +If you would like your ``cmd2`` based application to be able to use the +clipboard in additional or alternative ways, you can use the following methods +(which work uniformly on Windows, macOS, and Linux). .. automodule:: cmd2.clipboard :members: -- cgit v1.2.1