Cliff Class Reference¶

Application base class.

build_option_parser(description, version, argparse_kwargs=None)¶

Return an argparse option parser for this application.

Subclasses may override this method to extend the parser with more global options.

Parameters:	description (str) – full description of the application version (str) – version number for the application argparse_kwargs – extra keyword argument passed to the ArgumentParser constructor

clean_up(cmd, result, err)¶

Hook run after a command is done to shutdown the app.

Parameters:	cmd (cliff.command.Command) – command processor being invoked result (int) – return value of cmd err (Exception) – exception or None

configure_logging()¶

Create logging handlers for any log output.

get_fuzzy_matches(cmd)¶

return fuzzy matches of unknown command

initialize_app(argv)¶

Hook for subclasses to take global initialization action after the arguments are parsed but before a command is run. Invoked only once, even in interactive mode.

Parameters:	argv – List of arguments, including the subcommand to run. Empty for interactive mode.

prepare_to_run_command(cmd)¶

Perform any preliminary work needed to run a command.

Parameters:	cmd (cliff.command.Command) – command processor being invoked

print_help_if_requested()¶

Print help and exits if deferred help is enabled and requested.

‘–help’ shows the help message and exits:

• without calling initialize_app if not self.deferred_help (default),
• after initialize_app call if self.deferred_help,
• during initialize_app call if self.deferred_help and subclass calls explicitly this method in initialize_app.

run(argv)¶

Equivalent to the main program for the application.

Parameters:	argv (list of str) – input arguments and options

Provides “interactive mode” features.

Refer to the cmd2 and cmd documentation for details about subclassing and configuring this class.

cmdloop()¶

This is an outer wrapper around _cmdloop() which deals with extra features provided by cmd2.

_cmdloop() provides the main loop equivalent to cmd.cmdloop(). This is a wrapper around that which deals with the following extra features provided by cmd2: - commands at invocation - transcript testing - intro banner

Parameters:	intro – if provided this overrides self.intro and serves as the intro banner printed once at start

completedefault(text, line, begidx, endidx)¶

Default tab-completion for command prefix with completer delimiter.

This method filters only cliff style commands matching provided command prefix (line) as cmd2 style commands cannot contain spaces. This method returns text + missing command part of matching commands. This method does not handle options in cmd2/cliff style commands, you must define complete_$method to handle them.

completenames(text, line, begidx, endidx)¶

Tab-completion for command prefix without completer delimiter.

This method returns cmd style and cliff style commands matching provided command prefix (text).

default(line)¶

Executed when the command given isn’t a recognized command implemented by a do_* method.

Parameters:	statement – Statement object with parsed input

do_exit(_: argparse.Namespace) → bool¶

Exit this application

do_help(arg)¶

List available commands or provide detailed help for a specific command

precmd(statement)¶

Hook method executed just before the command is processed by onecmd() and after adding it to the history.

Parameters:	statement – subclass of str which also contains the parsed input
Returns:	a potentially modified version of the input Statement object

Discovers commands and handles lookup based on argv data.

add_legacy_command(old_name, new_name)¶

Map an old command name to the new name.

Parameters:	old_name (str) – The old command name. new_name (str) – The new command name.

find_command(argv)¶

Given an argument list, find a command and return the processor and any remaining arguments.

load_commands(namespace)¶

Load all the commands from an entrypoint

Base class for command plugins.

When the command is instantiated, it loads extensions from a namespace based on the parent application namespace and the command name:

app.namespace + '.' + cmd_name.replace(' ', '_')

get_description()¶

Return the command description.

The default is to use the first line of the class’ docstring as the description. Set the _description class attribute to a one-line description of a command to use a different value. This is useful for enabling translations, for example, with _description set to a string wrapped with a gettext translation marker.

get_epilog()¶

Return the command epilog.

get_parser(prog_name)¶

Return an argparse.ArgumentParser.

run(parsed_args)¶

Invoked by the application when the command is run.

Developers implementing commands should override take_action().

Developers creating new command base classes (such as Lister and ShowOne) should override this method to wrap take_action().

Return the value returned by take_action() or 0.

take_action(parsed_args)¶

Override to do something useful.

The returned value will be returned by the program.

Base class for command hooks.

after(parsed_args, return_code)¶

Called after the command’s take_action() method.

Parameters:	parsed_args (argparse.Namespace) – The arguments to the command. return_code (int) – The value returned from take_action().
Returns:	int

before(parsed_args)¶

Called before the command’s take_action() method.

Parameters:	parsed_args (argparse.Namespace) – The arguments to the command.
Returns:	argparse.Namespace

get_epilog()¶

Return text to add to the command help epilog.

get_parser(parser)¶

Return an argparse.ArgumentParser.

Parameters:	parser (ArgumentParser) – An existing ArgumentParser instance to be modified.
Returns:	ArgumentParser

Command base class for displaying data about a single object.

dict2columns(data)¶

Implement the common task of converting a dict-based object to the two-column output that ShowOne expects.

formatter_default¶

String specifying the name of the default formatter.

formatter_namespace¶

String specifying the namespace to use for loading formatter plugins.

produce_output(parsed_args, column_names, data)¶

Use the formatter to generate the output.

Parameters:	parsed_args – argparse.Namespace instance with argument values column_names – sequence of strings containing names of output columns data – iterable with values matching the column names

take_action(parsed_args)¶

Return a two-part tuple with a tuple of column names and a tuple of values.

Command base class for providing a list of data as output.

formatter_default¶

String specifying the name of the default formatter.

formatter_namespace¶

String specifying the namespace to use for loading formatter plugins.

get_parser(prog_name)¶

Return an argparse.ArgumentParser.

need_sort_by_cliff¶

Whether sort procedure is performed by cliff itself.

Should be overridden (return False) when there is a need to implement custom sorting procedure or data is already sorted.

produce_output(parsed_args, column_names, data)¶

Use the formatter to generate the output.

Parameters:	parsed_args – argparse.Namespace instance with argument values column_names – sequence of strings containing names of output columns data – iterable with values matching the column names

take_action(parsed_args)¶

Return a tuple containing the column names and an iterable containing the data to be listed.

add_argument_group(parser)¶

Add any options to the argument parser.

Should use our own argument group.

Base class for formatters that know how to deal with multiple objects.

emit_list(column_names, data, stdout, parsed_args)¶

Format and print the list from the iterable data source.

Data values can be primitive types like ints and strings, or can be an instance of a FormattableColumn for situations where the value is complex, and may need to be handled differently for human readable output vs. machine readable output.

Parameters:	column_names – names of the columns data – iterable data source, one tuple per object with values in order of column names stdout – output stream where data should be written parsed_args – argparse namespace from our local options

Base class for formatters that work with single objects.

emit_one(column_names, data, stdout, parsed_args)¶

Format and print the values associated with the single object.

Data values can be primitive types like ints and strings, or can be an instance of a FormattableColumn for situations where the value is complex, and may need to be handled differently for human readable output vs. machine readable output.

Parameters:	column_names – names of the columns data – iterable data source with values in order of column names stdout – output stream where data should be written parsed_args – argparse namespace from our local options