Interoperability with arbitrary callables

Clize operates as a callable that takes each item from sys.argv or something supposed to replace it. It is therefore easy to substitute it with another callable that has such parameters.

Avoiding automatic CLI inference

When an object is passed to run, either as sole command, one in many subcommands or as an alternative action, it attempts to make a CLI object out of it if it isn’t one already. It simply checks if there is a cli attribute and uses it, or it wraps it with Clize.

To insert an arbitrary callable, you must therefore place it as the cli attribute of whatever object you pass to run.

clize.Clize.as_is does exactly that. You can use it as a decorator or when passing it to run:

import argparse

from clize import Clize, parameters, run


@Clize.as_is
def echo_argv(*args):
    print(*args, sep=' | ')


def using_argparse(name: parameters.pass_name, *args):
    parser = argparse.ArgumentParser(prog=name)
    parser.add_argument('--ham')
    ns = parser.parse_args(args=args)
    print(ns.ham)


run(echo_argv, Clize.as_is(using_argparse))
$ python interop.py echo-argv ab cd ef
interop.py echo-argv | ab | cd | ef
$ python interop.py using-argparse --help
usage: interop.py using-argparse [-h] [--ham HAM]

optional arguments:
  -h, --help  show this help message and exit
  --ham HAM
$ python interop.py using-argparse spam
usage: interop.py using-argparse [-h] [--ham HAM]
interop.py using-argparse: error: unrecognized arguments: spam
$ python interop.py using-argparse --ham spam
spam

Providing a description in the parent command’s help

If you try to access the above program’s help screen, Clize will just leave the description for each external command empty:

: .tox/docs/bin/python interop.py --help
Usage: interop.py command [args...]

Commands:
  echo-argv
  using-argparse

Clize expects to find a description as cli.helper.description. You can either create an object there or let Clize.as_is do it for you:

@Clize.as_is(description="Prints argv separated by pipes")
def echo_argv(*args):
    print(*args, sep=' | ')

...

run(echo_argv,
    Clize.as_is(using_argparse,
                description="Prints the value of the --ham option"))
$ python interop.py --help
Usage: interop.py command [args...]

Commands:
  echo-argv        Prints argv separated by pipes
  using-argparse   Prints the value of the --ham option

Advertising command usage

To produce the --help --usage output, Clize uses cli.helper.usages() to produce an iterable of (command, usage) pairs. When it can’t determine it, it shows a generic usage signature instead.

You can use Clize.as_is’s usages= parameter to provide it:

run(echo_argv,
    Clize.as_is(using_argparse,
                description="Prints the value of the --ham option"),
                usages=['--help', '[--ham HAM]'])
$ python interop.py --help --usage
interop.py --help [--usage]
interop.py echo-argv [args...]
interop.py using-argparse --help
interop.py using-argparse [--ham HAM]

The example is available as examples/interop.py.