cligen¶

cligen is is a utility to generate command-line parsing code, writing your __main__.py from a specification in YAML. The generated code requires Python 3.8+.

For a commandline utility direction that needs the subcommands left and right, and where the subcommand left can have the option --u-turn (assuming you drive on the right side of the road), and both subcommands could have a --verbose option would look like:

!Cli 0:
- !Instance driving.Direction
- !Option [verbose, v, !Help increase verbosity level, !Action count]
- left:
  - !Help turning to the left
  - !Option [u-turn, U, !Type bool, !Help make a U-turn]
- right:
  - !H turning to the right

with the result that direction left -h will show:

usage: direction left [-h] [--u-turn] [--verbose]

optional arguments:
  -h, --help     show this help message and exit
  --u-turn, -U   make a U-turn
  --verbose, -v  increase verbosity level

When direction left is called from the command-line, the code in __main__.py will create an instance of the class Direction imported from driving.py, providing the result of the parsing as argument to the intialisation, and then call the method left_subcommand or method left (trying in that order) of that class. cligen can alternatively generate code that calls functions imported from a Python file, or call code inserted from the YAML specification in __main__.py itself (in this case the ..._subcommand is not tried, and the results of parsing passed in to the function).

The YAML document can either be in a file cli.yaml on its own, or, if you want to diminish file clutter in your project root, it can be stored in the variable _cligen_data in __init__.py, this means between the following two lines in that file:

_cligen_data = """\
"""

The YAML document uses various tags, many of which have a short version (e.g. !H is equivalent to using !Help).

Having the commandline options and argument data in a programmatically modifiable format like YAML, makes it more easy to check or manipulate all your utilities. E.g. if you want to make sure that all utilities that have a --verbose option also have a --quiet option that decreases the verbosity level.

Feature list¶

• multiple long (--date) and short options (-D) can be associated with one target.

• additional smart types/actions. E.g. an option with type 'date' defaults to datetime.date.today() and you can specify an argument like yesterday or -w-2 (two weeks ago)

• default values, with optionally some of the defaults defaults updated from a configuration file (YAML/INI/PON)

• nested parsers for subcommands, and subcommands inheriting options from their parent. This allows you to insert parent options before or after the subcommand, without the cligen code needing to re-arrange the commandline.

• an optional default subcommand/parser, which is used if unknown options/arguments are found.

• Optional shorthands in the form of alternative executable names for often used subcommand and/or options strings.

• no dependencies on anything but the Python standard library, unless your config file is in a format that requires some installed library ( YAML -> ruamel.yaml )

• allow YAML aliases for tagged scalars to be used by other tags:

  - !Help &xhelp text1 text2 text3  # this is the same as: "&xhelp !Help text1 text2 text3"
  - !Prolog [*xhelp]                # xhelp is a tagged scalar, "!Prolog *xhelp" would error
                                    # the value for !Prolog is automatically un-sequenced
  

Using !Config¶

In its most explicit form the tag !Config can takes a two element sequence as value. The first element indicates the type (pon, yaml, ini, TBI: json), the second the path to the file. A path starting with a tilde (~) will be expanded. A path not starting with tilde, or (forward-)slash (/), will be appended to your users config directory.

If !Config is followed by a scalar that looks like a path (i.e. the value starts with ~ or includes a /) the extension of the path is taken to be the type. In other cases !Config is assumed to be followed by a type and the basename is derived from the package name (_package_data['full_package_name']) in your users config directory.

A user config directory is based on XDG config locations (on Windows, the config information is expected under %APPDATA%)

When !Config is specified the inserted code will check for --config some_explicit_path on the commandline and load the config data from the path specified.

config file format¶

Config files are assumed to contain a dictionary at the root level (for formats like .ini the data is converted to a dictionary during loading). This dictionary contains keys that correspond to the various subparsers. A section global (or optionally glbl in PON to prevent use of a reserved keyword, renamed to global after loading), is used for defaults for options that come before the subparser as well as for global options. Each section consists of key-value pairs, where the key corresponds to a long option (--verbose) or if that is not available the short option (-v), either without the leading dashes.

Assuming you have the following configuration:

!Cli 0:
- !Opt [verbose, v, !H increase verbosity, !Action count]
- !Config [pon, /usr/local/etc/myutil.pon]
- subp1: []

your myutil.pon can use:

dict(glbl=dict(verbose=2))

to set the verbosity (you might want to format your PON somewhat nicer.

The same with a YAML file:

!Cli 0:
- !Opt [verbose, v, !H increase verbosity, !Action count]
- !Config YAML
- subp1: []

your ~/.config/your_util_name/your_util_name.yaml would be:

global:
  verbose: 2

argparse¶

An earlier version of cligen generated argparse commmands in the __main__.py file. The current python output doesn't use argparse anymore, resulting in code that is about twice as big, but also twice as fast.

The old, unmaintained, code generator can be invoked by providing --type argparse