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, errexit=False)

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

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: - transcript testing - intro banner - exit code

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) → Optional[bool]

Exit this application

do_help(arg)

List available commands or provide detailed help for a specific command

get_names()

Return an alphabetized list of names comprising the attributes of the cmd2 class instance.

precmd(statement)

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

Parameters

statement – subclass of str which also contains the parsed input

Returns

a potentially modified version of the input Statement object

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_command_group(group=None)

Adds another group of command entrypoints

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.

get_command_groups()

Returns a list of the loaded command groups

get_command_names(group=None)

Returns a list of commands loaded for the specified group

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.

abstract 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

abstract 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

abstract before(parsed_args)

Called before the command’s take_action() method.

Parameters

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

Returns

argparse.Namespace

abstract get_epilog()

Return text to add to the command help epilog.

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

property formatter_default

String specifying the name of the default formatter.

property 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

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

property formatter_default

String specifying the name of the default formatter.

property formatter_namespace

String specifying the namespace to use for loading formatter plugins.

get_parser(prog_name)

Return an argparse.ArgumentParser.

property 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

abstract 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

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

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

abstract 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