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: - commands at invocation - transcript testing - intro banner
- Parameters
intro – str - 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 – ParsedString - subclass of string including the pyparsing ParseResults
- Returns
-
do_exit
(_)¶ Exits this application.
-
do_help
(arg)¶ List available commands with “help” or detailed help with “help cmd”.
-
precmd
(statement)¶ Hook method executed just before the command is processed by
onecmd()
and after adding it to the history.- Parameters
statement – ParsedString - subclass of str which also contains pyparsing ParseResults instance
- Returns
ParsedString - a potentially modified version of the input ParsedString statement
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
andShowOne
) should override this method to wraptake_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.
-
property
Formatting Output¶
Formatter¶
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
-
abstract
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
-
abstract