diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/freefeatures.rst | 61 | ||||
| -rw-r--r-- | docs/settingchanges.rst | 2 |
2 files changed, 48 insertions, 15 deletions
diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst index b3f038b0..156b003e 100644 --- a/docs/freefeatures.rst +++ b/docs/freefeatures.rst @@ -142,35 +142,68 @@ app's value of ``self.redirector`` to use a different string for output redirect Python ====== -The ``py`` command will run its arguments as a Python -command. Entered without arguments, it enters an -interactive Python session. That session can call -"back" to your application with ``cmd("")``. Through -``self``, it also has access to your application -instance itself which can be extremely useful for debugging. -(If giving end-users this level of introspection is inappropriate, -the ``locals_in_py`` parameter can be set to ``False`` and removed -from the settable dictionary. See see :ref:`parameters`) +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. +That session can call + +The ``app`` object (or your custom name) provides access to application commands +through either raw commands or through a python API wrapper. For example, any +application command call be called with ``app("<command>")``. All application +commands are accessible as python objects and functions matching the command +name. For example, the following are equivalent: + +:: + + >>> app('say --piglatin Blah') + lahBay + >>> app.say("Blah", piglatin=True) + lahBay + + +Sub-commands are also supported. The following pairs are equivalent: + +:: + + >>> app('command subcmd1 subcmd2 param1 --myflag --otherflag 3') + >>> app.command.subcmd1.subcmd2('param1', myflag=True, otherflag=3) + + >>> app('command subcmd1 param1 subcmd2 param2 --myflag --otherflag 3') + >>> app.command.subcmd1('param1').subcmd2('param2', myflag=True, otherflag=3) + + +More Python examples: :: (Cmd) py print("-".join("spelling")) s-p-e-l-l-i-n-g (Cmd) py - Python 2.6.4 (r264:75706, Dec 7 2009, 18:45:15) - [GCC 4.4.1] on linux2 + 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) + Invoke python command, shell, or script + py <command>: Executes a Python command. py: Enters interactive Python mode. - End with `Ctrl-D` (Unix) / `Ctrl-Z` (Windows), `quit()`, 'exit()`. - Non-python commands can be issued with `cmd("your command")`. + 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') - >>> cmd("say --piglatin {os}".format(os=os.uname()[0])) + >>> app("say --piglatin {os}".format(os=os.uname()[0])) inuxLay >>> self.prompt '(Cmd) ' diff --git a/docs/settingchanges.rst b/docs/settingchanges.rst index f005fb49..02955273 100644 --- a/docs/settingchanges.rst +++ b/docs/settingchanges.rst @@ -143,7 +143,7 @@ with:: echo: False # Echo command issued into output editor: vim # Program used by ``edit`` feedback_to_output: False # include nonessentials in `|`, `>` results - locals_in_py: True # Allow access to your application in py via self + locals_in_py: False # Allow access to your application in py via self prompt: (Cmd) # The prompt issued to solicit input quiet: False # Don't print nonessential feedback timing: False # Report execution times |