cmd2 issues a configurable prompt before soliciting user input.
Customizing the Prompt¶
This prompt can be configured by setting the
attribute. This contains the string which should be printed as a prompt
for user input. See the Pirate example for the simple use case of statically
setting the prompt.
When a user types a
it may span more than one line of input. The prompt for the first line of input
is specified by the
cmd2.Cmd.prompt instance attribute. The prompt for
subsequent lines of input is defined by the
cmd2.Cmd.continuation_prompt attribute.See the Initialization example
for a demonstration of customizing the continuation prompt.
Updating the prompt¶
If you wish to update the prompt between commands, you can do so using one of the Application Lifecycle Hooks such as a Postcommand hook. See PythonScripting for an example of dynamically updating the prompt.
cmd2 provides two functions to provide asynchronous feedback to the user
without interfering with the command line. This means the feedback is provided
to the user when they are still entering text at the prompt. To use this
functionality, the application must be running in a terminal that supports
VT100 control characters and readline. Linux, Mac, and Windows 10 and greater
all support these.
async_alert(alert_msg: str, new_prompt: Optional[str] = None) → None
Display an important message to the user while they are at a command line prompt. To the user it appears as if an alert message is printed above the prompt and their current input text and cursor location is left alone.
- IMPORTANT: This function will not print an alert unless it can acquire self.terminal_lock to ensure
a prompt is onscreen. Therefore, it is best to acquire the lock before calling this function to guarantee the alert prints and to avoid raising a RuntimeError.
This function is only needed when you need to print an alert while the main thread is blocking at the prompt. Therefore, this should never be called from the main thread. Doing so will raise a RuntimeError.
- alert_msg – the message to display to the user
- new_prompt – If you also want to change the prompt that is displayed, then include it here. See async_update_prompt() docstring for guidance on updating a prompt.
async_update_prompt(new_prompt: str) → None
Update the command line prompt while the user is still typing at it. This is good for alerting the user to system changes dynamically in between commands. For instance you could alter the color of the prompt to indicate a system status or increase a counter to report an event. If you do alter the actual text of the prompt, it is best to keep the prompt the same width as what’s on screen. Otherwise the user’s input text will be shifted and the update will not be seamless.
- IMPORTANT: This function will not update the prompt unless it can acquire self.terminal_lock to ensure
a prompt is onscreen. Therefore, it is best to acquire the lock before calling this function to guarantee the prompt changes and to avoid raising a RuntimeError.
This function is only needed when you need to update the prompt while the main thread is blocking at the prompt. Therefore, this should never be called from the main thread. Doing so will raise a RuntimeError.
If user is at a continuation prompt while entering a multiline command, the onscreen prompt will not change. However, self.prompt will still be updated and display immediately after the multiline line command completes.
new_prompt – what to change the prompt to
cmd2 also provides a function to change the title of the terminal window.
This feature requires the application be running in a terminal that supports
VT100 control characters. Linux, Mac, and Windows 10 and greater all support
set_window_title(title: str) → None
Set the terminal window title.
- NOTE: This function writes to stderr. Therefore, if you call this during a command run by a pyscript,
- the string which updates the title will appear in that command’s CommandResult.stderr data.
Parameters: title – the new window title
The easiest way to understand these functions is to see the AsyncPrinting example for a demonstration.