diff options
| -rwxr-xr-x | cmd2/cmd2.py | 6 | ||||
| -rw-r--r-- | docs/freefeatures.rst | 61 | ||||
| -rw-r--r-- | docs/settingchanges.rst | 2 |
3 files changed, 51 insertions, 18 deletions
diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index eb80351b..98adc01f 100755 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -2871,7 +2871,7 @@ Usage: Usage: unalias [-a] name [name ...] 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")``. + Non-python commands can be issued with ``pyscript_name("your command")``. Run python code from external script files with ``run("script.py")`` """ from .pyscript_bridge import PyscriptBridge @@ -2909,7 +2909,6 @@ Usage: Usage: unalias [-a] name [name ...] if self.locals_in_py: self.pystate['self'] = self - self.pystate['cmd'] = onecmd_plus_hooks localvars = self.pystate interp = InteractiveConsole(locals=localvars) @@ -2932,9 +2931,10 @@ Usage: Usage: unalias [-a] name [name ...] keepstate = Statekeeper(sys, ('stdin', 'stdout')) sys.stdout = self.stdout sys.stdin = self.stdin + docstr = self.do_py.__doc__.replace('pyscript_name', self.pyscript_name) interp.interact(banner="Python %s on %s\n%s\n(%s)\n%s" % (sys.version, sys.platform, cprt, self.__class__.__name__, - self.do_py.__doc__)) + docstr)) except EmbeddedConsoleExit: pass if keepstate is not None: diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst index a7a112fc..419dc7d8 100644 --- a/docs/freefeatures.rst +++ b/docs/freefeatures.rst @@ -146,35 +146,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 539bbc9a..8e87d341 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 |