Cliff Classes



class, version, command_manager, stdin=None, stdout=None, stderr=None, interactive_app_factory=None, deferred_help=False)

Application base class.

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

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

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

Create logging handlers for any log output.


return fuzzy matches of unknown command


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.

Perform any preliminary work needed to run a command.

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

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.

Equivalent to the main program for the application.

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


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.

  • 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, *ignored)

Tab-completion for command prefix without completer delimiter.

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


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

Discovers commands and handles lookup based on argv data.

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

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


Load all the commands from an entrypoint


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

Base class for command plugins.

Parameters:app ( – Application instance invoking the command.

Return the command description.


Return an argparse.ArgumentParser.


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


Override to do something useful.


class, app_args, cmd_name=None)

Command base class for displaying data about a single object.


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


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


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

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


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

Formatting Output


class cliff.formatters.base.Formatter

Add any options to the argument parser.

Should use our own argument group.


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.

  • 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


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.

  • 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