recline.commands.cli_command module

Original © NetApp 2024

This module contains the definition of a CLICommand object. This is the main driver of the recline library. Essentially, a CLICommand takes as input a wrapped function and parses the args and docstring so that when called from the REPL, the command can be used as prescribed or the help information can be queried.

class recline.commands.cli_command.CLICommand(func, name=None, group=None, is_alias=False, hidden=False, is_async=False, is_background=False)

Bases: object

This is the implementation of a @recline.command. It sets up all of the parameter validation, help text generation, and return output formatting for commands defined in the application.

get_arg_action(arg)

By default, arguments will be verified as unique. However, if a custom type defines an action that should be taken when parsing the command line, that action will be used instead.

get_arg_description(arg, indent=0)

Get the description of the arg from the parsed docstring if we can find one. Otherwise, the description will be blank.

get_arg_help(arg, indent=True)

Get a line of help text for an argument including the name, metavar, and description of the argument.

get_arg_metavar(arg)

By default, the metavar for an argument is the same as the name of that argument (and enclosed in <>). But there are many situations with custom types where the metavar will be defined by the type and should be taken from the type.

get_command_help()

Get a block of help text for the command including all of its arguments as well as a short description of the command.

get_command_usage()

Get the short usage spec for the command

property hidden

A command is hidden if it is either statically declared to be or it was provided with a function to determine if it should currently be hidden

print_help()

If the -help argument is passed to the command, then this method will print out the help for that command instead of the builtin argparse help printer.

recline.commands.cli_command.command(func=None, name: str | None = None, group: str | None = None, aliases: List[str] | None = None, atstart: bool = False, atexit: bool = False, hidden: Callable[[], bool] | bool = False, background: bool = False)

Wrapping a function with this registers it with the recline library and exposes it as a command the user of the application can call.

The name of the command will match the name of the function that is being wrapped. The arguments of the command will match the arguments that the function accepts. Any arguments that are required by the function will be required arguments for the command. Any arguments that are optional (listed as keyword arguments) will be optional for the command.

Args:

name: If the command name shouldn’t inherit the function name, it can be

defined here. This can be especially useful if the command name has spaces in it.

group: If certain commands should be logically grouped together, they

should share the same group name.

aliases: An optional list of other names that will map back to the same

function. For example, if the function was called ‘exit’, a list of aliases might be [‘quit’, ‘q’].

atstart: If set to True, this command will run before the main REPL is

available for processing other commands. If this command fails, the REPL won’t become available.

atexit: Before exiting the program, this command will be run and can be

used to clean up any resources. This command should always take 0 arguments.

hidden: If the command is hidden, then it will not be shown in the help

output or available for autocompletion. It will still be executable by the user if they type it out. This can be either a function which evaluates to True or False, or just a constant True or False.

background: If the command is async and long running, then setting

background to True may be advisable so that other commands can be run in the foreground in the meantime.

recline.commands.cli_command.get_annotation_type(arg)

Python 3.7 explicitly broke the issubclass checking on the typing module https://bugs.python.org/issue34568