1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
Embedded Python Shells
======================
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
``self_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.
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("<command>")``.
::
>>> 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.9.0 (default, Nov 11 2020, 21:21:51)
[Clang 12.0.0 (clang-1200.0.32.21)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
End with `Ctrl-D` (Unix) / `Ctrl-Z` (Windows), `quit()`, `exit()`.
Non-Python commands can be issued with: app("your command")
(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:`features/scripting:Scripting`. 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
* Good built-in ipdb_ debugger
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
.. _ipdb: https://pypi.org/project/ipdb/
|
