Skip to content
Back to top
View this page
Edit this page

# 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(note, /)

      Add a note to the 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