xonsh.cli_utils

helper functions and classes to create argparse CLI from functions.

Examples

please see xonsh.completers.completer.CompleterAlias class

class xonsh.cli_utils.ArgParser(**kwargs)

Sub-class of ArgumentParser with special methods to nest commands

add_argument(dest, ..., name=value, ...) add_argument(option_string, option_string, ..., name=value, ...)

add_argument(option_string, option_string, ..., name=value, ...)

add_argument_group(*args, **kwargs)

add_command(func: Callable, default=False, args: tuple[str, ...] | None = None, **kwargs)

create a sub-parser and call this function during dispatch

Parameters:

func

a type-annotated function that will be used to create ArgumentParser instance. All parameters that start with _ will not be added to parser arguments. Use _stdout, _stack … to receive them from callable-alias/commands. Use _parser to get the generated parser instance. Use _args to get what is passed from sys.argv Use _parsed to get result of parser.parse_args

default

Marks this sub-command as the default command for this parser.

args

if given only add these arguments to the parser. Otherwise all parameters to the function without _ prefixed in their name gets added to the parser.

kwargs

passed to subparser.add_parser call

Returns:

result from subparser.add_parser

add_mutually_exclusive_group(**kwargs)

add_subparsers(**kwargs)

convert_arg_line_to_args(arg_line)

error(message: string)

Prints a usage message incorporating the message to stderr and exits.

If you override this in a subclass, it should not return – it should either exit or raise an exception.

exit(status=0, message=None)

format_help()

format_usage()

get_default(dest)

parse_args(args=None, namespace=None)

parse_intermixed_args(args=None, namespace=None)

parse_known_args(args=None, namespace=None)

parse_known_intermixed_args(args=None, namespace=None)

print_help(file=None)

print_usage(file=None)

register(registry_name, value, object)

set_defaults(**kwargs)

class xonsh.cli_utils.ArgParserAlias(threadable=True, **kwargs)

Provides a structure to the Alias. The parser is lazily loaded.

can help create argparse.ArgumentParser parser from function signature and dispatch the functions.

Examples

For usage please check xonsh.completers.completer

exception Error(message: str, errno=1)

Special case, when raised, the traceback will not be shown. Instead the process with exit with error code and message

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

build() → ArgParser

Sub-classes should return constructed ArgumentParser

create_parser(func=None, has_args=False, allowed_params=None, **kwargs) → ArgParser

create root parser

err(*args, **kwargs)

Write text to error stream

out(*args, **kwargs)

Write text to output stream

write_to(stream: str, *args, **kwargs)

xonsh_complete(command, **kwargs)

property parser

class xonsh.cli_utils.ArgparseCompleter(parser: ArgumentParser, command, **kwargs)

A completer function for ArgParserAlias commands

static get_parser(parser, args) → tuple[ArgumentParser, tuple[str, ...]]

Check for sub-parsers

complete()

filled(act: Action) → int

Consume remaining_args for the given action

class xonsh.cli_utils.NumpyDoc(func, prefix_chars='-', follow_wraps=True)

Represent parsed function docstring

Parse the function docstring and return its help content

Parameters:

func

a callable/object that holds docstring

static get_func_doc(doc)

static get_param_doc(lines: list[str])

static join(lines)

xonsh.cli_utils.Arg(*args: str, completer: ArgCompleter | Callable[[...], Iterator[str]] | None = None, **kwargs)

xonsh.cli_utils.add_args(parser: ArgumentParser, func: Callable, allowed_params=None, doc=None) → None

Using the function’s annotation add arguments to the parser

basically converts def fn(param : Arg(*args, **kw), ...): ...

-> into equivalent parser.add_argument(*args, *kw) call.

xonsh.cli_utils.dispatch(parser: ArgumentParser, args=None, lenient=False, **ns)

Call the underlying function with arguments parsed from sys.argv

Parameters:

parser

root parser

args

sys.argv as parsed by Alias

lenient

if True, then use parser_know_args and pass the extra arguments as _unparsed

ns

a dict that will be passed to underlying function

xonsh.cli_utils.make_parser(func: Callable | str, empty_help=False, **kwargs) → ArgParser

A bare-bones argparse builder from functions