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.

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).

Discovers commands and handles lookup based on argv data.

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.

Any return value is ignored.

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

before(parsed_args)¶

Called before the command’s take_action() method.

Any return value is ignored.

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

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.

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.

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