Cliff Class Reference

Application

App

class cliff.app.App(description: str | None, version: str | None, command_manager: _commandmanager.CommandManager, stdin: TextIO | None = None, stdout: TextIO | None = None, stderr: TextIO | None = None, interactive_app_factory: type[_interactive.InteractiveApp] | None = None, deferred_help: bool = 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: str | None, version: str | None, argparse_kwargs: dict[str, Any] | None = None) → ArgumentParser

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: _command.Command, result: int, err: BaseException | None) → None

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() → None

Create logging handlers for any log output.

get_fuzzy_matches(cmd: str) → list[str]

return fuzzy matches of unknown command

initialize_app(argv: list[str]) → None

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: _command.Command) → None

Perform any preliminary work needed to run a command.

Parameters:

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

print_help_if_requested() → None

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: list[str]) → int

Equivalent to the main program for the application.

Parameters:

argv (list of str) – input arguments and options

InteractiveApp

class cliff.interactive.InteractiveApp(parent_app: _app.App, command_manager: _commandmanager.CommandManager, stdin: TextIO | None, stdout: TextIO | None, errexit: bool = False)

Provides “interactive mode” features.

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

Parameters:
cmdloop(intro: str | None = None) → None

Deal with extra features provided by cmd2, this is an outer wrapper around _cmdloop().

_cmdloop() provides the main loop. This provides 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: str, line: str, begidx: int, endidx: int) → list[str]

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: str, *ignored: Any) → list[str]

Tab-completion for command prefix without completer delimiter.

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

default(line: str) → bool | None

Execute when the command given isn’t a recognized command implemented by a do_* method.

Parameters:

statement – Statement object with parsed input

do_exit(_: Namespace) → bool | None

Exit this application.

do_help(arg: str | None) → None

List available commands or provide detailed help for a specific command.

get_names() → list[str]

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

precmd(statement: Statement | str) → 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: str | None = None, convert_underscores: bool = True, *, ignored_modules: Iterable[str] | None = None)

Discovers commands and handles lookup based on argv data.

Parameters:

  • namespace – String containing the entrypoint namespace for the plugins to be loaded. For example, 'cliff.formatter.list'. If provided, commands will be loaded from this namespace initially, though it remains possible to load from additional namespaces with CommandManager.load_commands().

  • convert_underscores – Whether cliff should convert underscores to spaces in entry_point commands.

  • ignored_modules – A list of module names to ignore when loading commands. This will be matched partial, so be as specific as needed.

add_command_group(group: str | None = None) → None

Adds another group of command entrypoints

add_legacy_command(old_name: str, new_name: str) → None

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: list[str]) → tuple[type[Command], str, list[str]]

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

get_command_groups() → list[str]

Returns a list of the loaded command groups

get_command_names(group: str | None = None) → list[str]

Returns a list of commands loaded for the specified group

load_commands(namespace: str) → None

Load all the commands from an entrypoint

Parameters:

namespace – The namespace to load commands from.

Returns:

None

Command

class cliff.command.Command(app: _app.App, app_args: Namespace | None, cmd_name: str | None = 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 – Application instance invoking the command.

  • app_args – Parsed arguments from options associated with the application instance..

  • cmd_name – The name of the command.

get_description() → str

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() → str

Return the command epilog.

get_parser(prog_name: str) → ArgumentParser

Return an argparse.ArgumentParser.

run(parsed_args: Namespace) → int

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: Namespace) → Any

Override to do something useful.

The returned value will be returned by the program.

CommandHook

class cliff.hooks.CommandHook(command: Command)

Base class for command hooks.

Hook methods are executed in the following order:

  1. get_epilog()

  2. get_parser()

  3. before()

  4. after()

Parameters:

command – Command instance being invoked

abstract after(parsed_args: Namespace, return_code: int) → int

Called after the command’s take_action() method.

Parameters:

  • parsed_args – The arguments to the command.

  • return_code (int) – The value returned from take_action().

Returns:

int

abstract before(parsed_args: Namespace) → Namespace

Called before the command’s take_action() method.

Parameters:

parsed_args – The arguments to the command.

Returns:

argparse.Namespace

abstract get_epilog() → str | None

Return text to add to the command help epilog.

Returns:

An epilog string or None.

abstract get_parser(parser: ArgumentParser) → ArgumentParser | None

Modify the command argparse.ArgumentParser.

The provided parser is modified in-place, and the return value is not used.

Parameters:

parser – An existing ArgumentParser instance to be modified.

Returns:

ArgumentParser or None

ShowOne

class cliff.show.ShowOne(app: App, app_args: Namespace | None, cmd_name: str | None = None)

Command base class for displaying data about a single object.

dict2columns(data: dict[str, Any]) → tuple[tuple[str, ...], tuple[Any, ...]]

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

property formatter_default: str

String specifying the name of the default formatter.

property formatter_namespace: str

Namespace to use for loading formatter plugins.

produce_output(parsed_args: Namespace, column_names: Sequence[str], data: Sequence[Any]) → int

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

Returns:

a status code

abstract take_action(parsed_args: Namespace) → tuple[Sequence[str], Iterable[Any]]

Run command.

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

Lister

class cliff.lister.Lister(app: App, app_args: Namespace | None, cmd_name: str | None = None)

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

property formatter_default: str

String specifying the name of the default formatter.

property formatter_namespace: str

Namespace to use for loading formatter plugins.

get_parser(prog_name: str) → ArgumentParser

Return an argparse.ArgumentParser.

property need_sort_by_cliff: bool

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: Namespace, column_names: Sequence[str], data: Iterable[Sequence[Any]]) → int

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

Returns:

a status code

abstract take_action(parsed_args: Namespace) → tuple[Sequence[str], Iterable[Any]]

Run command.

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: ArgumentParser) → None

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 many objects.

abstract emit_list(column_names: Sequence[str], data: Iterable[Sequence[Any]], stdout: TextIO, parsed_args: Namespace) → None

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: Sequence[str], data: Sequence[Any], stdout: TextIO, parsed_args: Namespace) → None

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