Cliff Classes

Application

App

class cliff.app.App(description, version, command_manager, stdin=None, stdout=None, stderr=None, interactive_app_factory=<class cliff.interactive.InteractiveApp at 0x1021be940>)

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

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.

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

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

CommandManager

class cliff.commandmanager.CommandManager(namespace)

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

find_command(argv)

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

Command

class cliff.command.Command(app, app_args)

Base class for command plugins.

Parameters:app (cliff.app.App) – Application instance invoking the command.

get_description()

Return the command description.

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

take_action(parsed_args)

Override to do something useful.

ShowOne

class cliff.show.ShowOne(app, app_args)

Command base class for displaying data about a single object.

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)

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.

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.

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.

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