Settings

Settings provide a mechanism for a user to control the behavior of a cmd2 based application. A setting is stored in an instance attribute on your subclass of cmd2.cmd2.Cmd and must also appear in the cmd2.cmd2.Cmd.settable dictionary. Developers may set default values for these settings and users can modify them at runtime using the set command. Developers can Create New Settings and can also Hide Builtin Settings from the user.

Builtin Settings

cmd2 has a number of builtin settings. These settings control the behavior of certain application features and Builtin Commands. Users can use the set command to show all settings and to modify the value of any setting.

allow_style

Output generated by cmd2 programs may contain ANSI escape seqences which instruct the terminal to apply colors or text styling (i.e. bold) to the output. The allow_style setting controls the behavior of these escape sequences in output generated with any of the following methods:

• cmd2.Cmd.poutput()
• cmd2.Cmd.perror()
• cmd2.Cmd.pwarning()
• cmd2.Cmd.pexcept()
• cmd2.Cmd.pfeedback()
• cmd2.Cmd.ppaged()

This setting can be one of three values:

• Never - all ANSI escape sequences which instruct the terminal to style output are stripped from the output.
• Terminal - (the default value) pass through ANSI escape sequences when the output is being sent to the terminal, but if the output is redirected to a pipe or a file the escape sequences are stripped.
• Always - ANSI escape sequences are always passed through to the output

continuation_prompt

When a user types a Multiline Command it may span more than one line of input. The prompt for the first line of input is specified by the prompt setting. The prompt for subsequent lines of input is defined by this setting.

debug

The default value of this setting is False, which causes the pexcept() method to only display the message from an exception. However, if the debug setting is True, then the entire stack trace will be printed.

echo

If True, each command the user issues will be repeated to the screen before it is executed. This is particularly useful when running scripts. This behavior does not occur when a running command at the prompt.

editor

Similar to the EDITOR shell variable, this setting contains the name of the program which should be run by the edit command.

feedback_to_output

Controls whether feedback generated with the pfeedback() method is sent to sys.stdout or sys.stderr. If False the output will be sent to sys.stderr

If True the output is sent to stdout (which is often the screen but may be redirected). The feedback output will be mixed in with and indistinguishable from output generated with poutput().

locals_in_py

Allow access to your application in one of the Embedded Python Shells via self.

max_completion_items

Maximum number of CompletionItems to display during tab completion. A CompletionItem is a special kind of tab-completion hint which displays both a value and description and uses one line for each hint. Tab complete the set command for an example.

If the number of tab-completion hints exceeds max_completion_items, then they will be displayed in the typical columnized format and will not include the description text of the CompletionItem.

prompt

This setting contains the string which should be printed as a prompt for user input.

quiet

If True, output generated by calling pfeedback() is suppressed. If False, the feedback_to_output setting controls where the output is sent.

timing

If True, the elapsed time is reported for each command executed.

Create New Settings

Your application can define user-settable parameters which your code can reference. First create a class attribute with the default value. Then update the settable dictionary with your setting name and a short description before you initialize the superclass. Here’s an example, from examples/environment.py:

#!/usr/bin/env python
# coding=utf-8
"""
A sample application for cmd2 demonstrating customized environment parameters
"""
import cmd2


class EnvironmentApp(cmd2.Cmd):
    """ Example cmd2 application. """

    degrees_c = 22
    sunny = False

    def __init__(self):
        super().__init__()
        self.settable.update({'degrees_c': 'Temperature in Celsius'})
        self.settable.update({'sunny': 'Is it sunny outside?'})

    def do_sunbathe(self, arg):
        if self.degrees_c < 20:
            result = "It's {} C - are you a penguin?".format(self.degrees_c)
        elif not self.sunny:
            result = 'Too dim.'
        else:
            result = 'UV is bad for your skin.'
        self.poutput(result)

    def _onchange_degrees_c(self, old, new):
        # if it's over 40C, it's gotta be sunny, right?
        if new > 40:
            self.sunny = True


if __name__ == '__main__':
    import sys
    c = EnvironmentApp()
    sys.exit(c.cmdloop())

If you want to be notified when a setting changes (as we do above), then define a method _onchange_{setting}(). This method will be called after the user changes a setting, and will receive both the old value and the new value.

(Cmd) set --long | grep sunny
sunny: False                # Is it sunny outside?
(Cmd) set --long | grep degrees
degrees_c: 22               # Temperature in Celsius
(Cmd) sunbathe
Too dim.
(Cmd) set degrees_c 41
degrees_c - was: 22
now: 41
(Cmd) set sunny
sunny: True
(Cmd) sunbathe
UV is bad for your skin.
(Cmd) set degrees_c 13
degrees_c - was: 41
now: 13
(Cmd) sunbathe
It's 13 C - are you a penguin?

Hide Builtin Settings

You may want to prevent a user from modifying a builtin setting. A setting must appear in the cmd2.cmd2.Cmd.settable dictionary in order for it to be available to the set command.

Let’s say your program does not have any Multiline Commands. You might want to hide the continuation_prompt setting from your users since it is only applicable to multiline commands. To do so, remove it from the cmd2.cmd2.Cmd.settable dictionary after you initialize your object:

class MyApp(cmd2.Cmd):

  def __init__(self):
      super().__init__()
      self.settable.pop('continuation_prompt')