Utility Classes

class cmd2.utils.Settable(name: str, val_type: Callable, description: str, *, onchange_cb: Callable[[str, Any, Any], Any] = None, choices: Iterable[T_co] = None, choices_function: Optional[Callable] = None, choices_method: Optional[Callable] = None, completer_function: Optional[Callable] = None, completer_method: Optional[Callable] = None)

Used to configure a cmd2 instance member to be settable via the set command in the CLI

__init__(name: str, val_type: Callable, description: str, *, onchange_cb: Callable[[str, Any, Any], Any] = None, choices: Iterable[T_co] = None, choices_function: Optional[Callable] = None, choices_method: Optional[Callable] = None, completer_function: Optional[Callable] = None, completer_method: Optional[Callable] = None)

Settable Initializer

Parameters:
  • name – name of the instance attribute being made settable
  • val_type – callable used to cast the string value from the command line into its proper type and even validate its value. Setting this to bool provides tab completion for true/false and validation using str_to_bool(). The val_type function should raise an exception if it fails. This exception will be caught and printed by Cmd.do_set().
  • description – string describing this setting
  • onchange_cb –

    optional function or method to call when the value of this settable is altered by the set command. (e.g. onchange_cb=self.debug_changed)

    Cmd.do_set() passes the following 3 arguments to onchange_cb:
    param_name: str - name of the changed parameter old_value: Any - the value before being changed new_value: Any - the value after being changed

The following optional settings provide tab completion for a parameter’s values. They correspond to the same settings in argparse-based tab completion. A maximum of one of these should be provided.

Parameters:
  • choices – iterable of accepted values
  • choices_function – function that provides choices for this argument
  • choices_method – cmd2-app method that provides choices for this argument (See note below)
  • completer_function – tab-completion function that provides choices for this argument
  • completer_method – cmd2-app tab-completion method that provides choices for this argument (See note below)

Note: For choices_method and completer_method, do not set them to a bound method. This is because AutoCompleter passes the self argument explicitly to these functions.

Therefore instead of passing something like self.path_complete, pass cmd2.Cmd.path_complete.

class cmd2.utils.StdSim(inner_stream, echo: bool = False, encoding: str = 'utf-8', errors: str = 'replace')

Class to simulate behavior of sys.stdout or sys.stderr. Stores contents in internal buffer and optionally echos to the inner stream it is simulating.

class cmd2.utils.ByteBuf(std_sim_instance: cmd2.utils.StdSim)

Used by StdSim to write binary data and stores the actual bytes written

class cmd2.utils.ProcReader(proc: subprocess.Popen, stdout: Union[cmd2.utils.StdSim, TextIO], stderr: Union[cmd2.utils.StdSim, TextIO])

Used to capture stdout and stderr from a Popen process if any of those were set to subprocess.PIPE. If neither are pipes, then the process will run normally and no output will be captured.

class cmd2.utils.ContextFlag

A context manager which is also used as a boolean flag value within the default sigint handler.

Its main use is as a flag to prevent the SIGINT handler in cmd2 from raising a KeyboardInterrupt while a critical code section has set the flag to True. Because signal handling is always done on the main thread, this class is not thread-safe since there is no need.

class cmd2.utils.RedirectionSavedState(self_stdout: Union[cmd2.utils.StdSim, TextIO], sys_stdout: Union[cmd2.utils.StdSim, TextIO], pipe_proc_reader: Optional[cmd2.utils.ProcReader])

Created by each command to store information about their redirection.