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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
# Help
From our experience, end users rarely read documentation no matter how high-quality or useful that
documentation might be. So it is important that you provide good built-in help within your
application. Fortunately, `cmd2` makes this easy.
## Getting Help
`cmd2` makes it easy for end users of `cmd2` applications to get help via the built-in `help`
command. The `help` command by itself displays a list of the commands available:
```text
(Cmd) help
Documented Commands
───────────────────
alias help ipy py run_pyscript set shortcuts
edit history macro quit run_script shell
```
The `help` command can also be used to provide detailed help for a specific command:
```text
(Cmd) help quit
Usage: quit [-h]
Exit this application.
Optional Arguments:
-h, --help show this help message and exit
```
## Providing Help
`cmd2` makes it easy for developers of `cmd2` applications to provide this help. By default, the
help for a command is the docstring for the `do_*` method defining the command - e.g. for a command
**foo**, that command is implemented by defining the `do_foo` method and the docstring for that
method is the help.
For commands which use the [@with_argparser][cmd2.with_argparser] decorator to parse arguments, help
is provided by `argparse`. See [Help Messages](./argument_processing.md#help-messages) for more
information.
Occasionally there might be an unusual circumstance where providing static help text isn't good
enough and you want to provide dynamic information in the help text for a command. To meet this
need, if a `help_foo` method is defined to match the `do_foo` method, then that method will be used
to provide the help for command **foo**. This dynamic help is only supported for commands which do
not use an `argparse` decorator because we didn't want different output for `help cmd` than for
`cmd -h`.
## Categorizing Commands
By default, the `help` command displays:
Documented Commands
───────────────────
alias help ipy py run_pyscript set shortcuts
edit history macro quit run_script shell
If you have a large number of commands, you can optionally group your commands into categories.
Here's the output from the example
[help_categories.py](https://github.com/python-cmd2/cmd2/blob/main/examples/help_categories.py):
Application Management
──────────────────────
deploy findleakers redeploy sessions stop
expire list restart start undeploy
Command Management
──────────────────
disable_commands enable_commands
Connecting
──────────
connect which
Server Information
──────────────────
resources serverinfo sslconnectorciphers status thread_dump vminfo
Other
─────
alias edit history quit run_script shell version
config help macro run_pyscript set shortcuts
There are 2 methods of specifying command categories, using the [@with_category][cmd2.with_category]
decorator or with the [categorize()][cmd2.categorize] function. Once a single command category is
detected, the help output switches to a categorized mode of display. All commands without an
explicit category defined default to the category `Other`.
Using the `@with_category` decorator:
```py
@with_category(CMD_CAT_CONNECTING)
def do_which(self, _):
"""Which command"""
self.poutput('Which')
```
Using the `categorize()` function:
You can call with a single function:
```py
def do_connect(self, _):
"""Connect command"""
self.poutput('Connect')
# Tag the above command functions under the category Connecting
categorize(do_connect, CMD_CAT_CONNECTING)
```
Or with an Iterable container of functions:
```py
def do_undeploy(self, _):
"""Undeploy command"""
self.poutput('Undeploy')
def do_stop(self, _):
"""Stop command"""
self.poutput('Stop')
def do_findleakers(self, _):
"""Find Leakers command"""
self.poutput('Find Leakers')
# Tag the above command functions under the category Application Management
categorize((do_undeploy,
do_stop,
do_findleakers), CMD_CAT_APP_MGMT)
```
The `help` command also has a verbose option (`help -v` or `help --verbose`) that combines the help
categories with per-command help messages:
Application Management
─────────────────────────────────────
Name Description
─────────────────────────────────────
deploy Deploy command.
expire Expire command.
findleakers Find Leakers command.
list List command.
redeploy Redeploy command.
restart Restart command.
sessions Sessions command.
start Start command.
stop Stop command.
undeploy Undeploy command.
Command Management
─────────────────────────────────────────────────────────────────
Name Description
─────────────────────────────────────────────────────────────────
disable_commands Disable the Application Management commands.
enable_commands Enable the Application Management commands.
Connecting
────────────────────────────
Name Description
────────────────────────────
connect Connect command.
which Which command.
Server Information
─────────────────────────────────────────────────────────────────────────────────────────────────
Name Description
─────────────────────────────────────────────────────────────────────────────────────────────────
resources Resources command.
serverinfo Server Info command.
sslconnectorciphers SSL Connector Ciphers command is an example of a command that contains
multiple lines of help information for the user. Each line of help in a
contiguous set of lines will be printed and aligned in the verbose output
provided with 'help --verbose'.
status Status command.
thread_dump Thread Dump command.
vminfo VM Info command.
Other
─────────────────────────────────────────────────────────────────────────────────────────
Name Description
─────────────────────────────────────────────────────────────────────────────────────────
alias Manage aliases.
config Config command.
edit Run a text editor and optionally open a file with it.
help List available commands or provide detailed help for a specific command.
history View, run, edit, save, or clear previously entered commands.
macro Manage macros.
quit Exit this application.
run_pyscript Run Python script within this application's environment.
run_script Run text script.
set Set a settable parameter or show current settings of parameters.
shell Execute a command as if at the OS prompt.
shortcuts List available shortcuts.
version Version command.
When called with the `-v` flag for verbose help, the one-line description for each command is
provided by the first line of the docstring for that command's associated `do_*` method.
|
