Cliff Class Reference

Cliff Class Reference

Application

App

class cliff.app.App(description, version, command_manager, stdin=None, stdout=None, stderr=None, interactive_app_factory=None, deferred_help=False)

Application base class.

Parameters:
  • description (str) – one-liner explaining the program purpose
  • version (str) – application version number
  • command_manager (cliff.commandmanager.CommandManager) – plugin loader
  • stdin (readable I/O stream) – Standard input stream
  • stdout (writable I/O stream) – Standard output stream
  • stderr (writable I/O stream) – Standard error output stream
  • interactive_app_factory (cliff.interactive.InteractiveApp) – callable to create an interactive application
  • deferred_help (bool) – True - Allow subcommands to accept –help with allowing to defer help print after initialize_app
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

InteractiveApp

class cliff.interactive.InteractiveApp(parent_app, command_manager, stdin, stdout)

Provides “interactive mode” features.

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

Parameters:
  • parent_app – The calling application (expected to be derived from cliff.main.App).
  • command_manager – A cliff.commandmanager.CommandManager instance.
  • stdin – Standard input stream
  • stdout – Standard output stream
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).

do_exit(_)

Exits this application.

CommandManager

class cliff.commandmanager.CommandManager(namespace, convert_underscores=True)

Discovers commands and handles lookup based on argv data.

Parameters:
  • namespace – String containing the setuptools entrypoint namespace for the plugins to be loaded. For example, 'cliff.formatter.list'.
  • convert_underscores – Whether cliff should convert underscores to spaces in entry_point commands.
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

Command

class cliff.command.Command(app, app_args, cmd_name=None)

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(' ', '_')
Parameters:app (cliff.app.App) – Application instance invoking the command.
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.

CommandHook

class cliff.hooks.CommandHook(command)

Base class for command hooks.

Parameters:app (cliff.command.Command) – Command instance being invoked
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

ShowOne

class cliff.show.ShowOne(app, app_args, cmd_name=None)

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.

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.

Lister

class cliff.lister.Lister(app, app_args, cmd_name=None)

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

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.

Formatting Output

Formatter

class cliff.formatters.base.Formatter
add_argument_group(parser)

Add any options to the argument parser.

Should use our own argument group.

ListFormatter

class cliff.formatters.base.ListFormatter

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

SingleFormatter

class cliff.formatters.base.SingleFormatter

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
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.