Package: cligen
cligencligen is is a utility to generate command-line parsing code, writing
your__main__.pyfrom a specification in YAML. The generated
code requires Python 3.8+.For a commandline utilitydirectionthat needs the subcommandsleftandright, and where the subcommandleftcan have the option--u-turn(assuming you drive on the right side of the road), and both
subcommands could have a--verboseoption 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 rightwith the result thatdirection left -hwill 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 levelWhendirection leftis called from the command-line, the code in__main__.pywill create an instance of the classDirectionimported fromdriving.py, providing
the result of the parsing as argument to the intialisation,
and then call the methodleft_subcommandor methodleft(trying in that order) of that class.cligencan alternatively generate code that calls functions
imported from a Python file, or call code inserted from the
YAML specification in__main__.pyitself (in this case the..._subcommandis not tried, and the results of parsing passed in to the function).The YAML document can either be in a filecli.yamlon its own, or, if you
want to diminish file clutter in your project root, it can be stored in
the variable_cligen_datain__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.!His 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--verboseoption also have a--quietoption that
decreases the verbosity level.Feature listmultiple long (--date) and short options (-D) can be associated with
one target.additional smart types/actions. E.g. an option with type 'date' defaults todatetime.date.today()and you can specify an argument likeyesterdayor-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-sequencedUsing !ConfigIn its most explicit form the tag!Configcan takes a two element
sequence as value. The first element indicates thetype(pon,yaml,ini, TBI:json), the second thepathto 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!Configis 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 thetype. In other cases!Configis assumed to be
followed by atypeand 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!Configis specified the inserted code will check for--config some_explicit_pathon the commandline and load the config
data from the path specified.config file formatConfig files are assumed to contain a dictionary at the root level (for
formats like.inithe data is converted to a dictionary during
loading). This dictionary contains keys that correspond to the various
subparsers. A sectionglobal(or optionallyglblin PON to prevent
use of a reserved keyword, renamed toglobalafter 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: []yourmyutil.poncan 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.yamlwould be:global:
  verbose: 2argparseAn earlier version of cligen generatedargparsecommmands
in the__main__.pyfile. The current python output doesn't
useargparseanymore, 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