pycmdparse¶

pycmdparse is a small library to help developers of Python console utilities parse the command line and display usage instructions. It’s goal is to enable this with a minimum of programming. The Use Case for a console utility developer is:

Import this package and subclass the CmdLine class in your utility code
Initialize the yaml_def field (defined in the base class) with a yaml definition of options/params/usage
Call the parse function of the base class to parse the command line.

If successful, the parse function injects fields into your subclass - one for each option defined in the yaml spec. Your utility then accesses the injected fields to get the values provided by the user

If there is an error parsing the command line, or the user specifies -h or –help, your utility calls the base class display_info method to display the errors or display usage instructions - as specified in the yaml.

A simple example¶

This is an illustrative console utility called “os-info”:

class MyCmdLine(CmdLine):
    yaml_def = '''
    utility:
      name: os-info

    summary: >
      Gets operating system info, and saves it to
      the specified file.

    positional_params:
      params: FILE
      text: >
        Writes the information to FILE

    supported_options:
      - category:
        options:
        - name : verbose
          short: v
          long : verbose
          opt  : bool
          help: >
            Provides additional (more verbose) information

    examples:
      - example: os-info -v my-outfile
        explanation: >
          Gets verbose operating system info and writes
          it to 'my-outfile' in the current working directory
    '''

    # Fields will be injected if not defined. If defined, their
    # values will be set by the parser. The 'name' key in the
    # yaml above specifies the Python field name to inject into
    # the subclass for each option your utility supports

    verbose = None

if __name__ == "__main__":
    parse_result = MyCmdLine.parse(sys.argv)
    if parse_result.value != ParseResultEnum.SUCCESS.value:
        MyCmdLine.display_info(parse_result)
        exit(1)
    import platform
    with open(MyCmdLine.positional_params[0], "w") as f:
        f.write("sys info: %s\n" % str(platform.uname()))
        if MyCmdLine.verbose:
            f.write("python version: %s\n" %
                platform.python_version())

If the user entered the following on the command line:

os-info --help

They would see the following displayed on the console:

os-info
=======
Gets the operating system version, and saves it to the
specified file.

Usage:

os-info [-v,--verbose] FILE

Writes the information to FILE.

Options and parameters:

-v,--verbose Optional. Provides additional (more verbose)
             information

Examples:

os-info -v my-outfile

Gets verbose operating system info and writes it
to 'my-outfile' in the current working directory

If the user entered the following on the command line:

os-info --purple

They would see the following displayed on the console:

Error:

Unsupported option: '--purple'

For usage instructions, try: os-info -h (or os-info --help)

Obviously with such a simple example, you wouldn’t need pycmdparse. The library is intended to help with complex command lines.

Terms¶

arg: An arg is a token on the command line. The first arg is the command name
option: An option is an argument used by the command. E.g.: –verbose. Options begin with a dash or a double dash
parameter: A parameter is a value that is used by an option or by the command. In this expression: --max-threads=100, –max-threads is the option and 100 is the parameter. Positional parameters are parameters used by the command that are not paired with an option. In this expression: my-command FOO, FOO is a positional param.

Features¶

Uses yaml to define command-line requirements and usage instructions
Supports two types of options:
- A bool option is true or false. Sometimes referred to as a switch. E.g.: -v, or –verbose. The value is false if omitted from the command line, and true if present on the command line
- A param option takes one or more parameters. The default is a single param option. E.g.: –threads=100. A param option can be defined to accept an exact number of parameters, up to a specified number of parameters, or can accept no limit to the number of parameters
Supports short-form options (-v) and long-form options (–verbose). The yaml can specify both or either.
Supports required and non-required options. Non-required options can have a default specified in the yaml. If a required option is omitted from the command line, then it is a parse error. If a non-required option with a default is not specified on the command line, then the option value is the default in the yaml
parameters can be expressed as follows on the command line: --max-threads=100. --max-threads 100. -t=100. -t 100. All are equivalent.
Supports concatenation of short-form options. E.g.: -v -t -c and -vtc are handled identically. In addition, if a short-form option takes a value, it can also be concatenated. These are the same: -v -t -c=100 and -vtc=100 -vtc 100 -v -t -c 100
Provides basic data typing of parameters: int, bool, float, date. If you specify a data type then the parser validates the parameter so you don’t have to
For options taking multiple params, these can be provided on the command line this way: --takes-three X Y Z or this way: --takes-three X --takes-three Y --takes-three Z
Supports the double dash (“–”) option to indicate the beginning of positional parameters
Parses positional parameters and provides them in a list
Enables a custom validation call-back for you to perform any parameter validations not provided out of the box
Displays usage instructions in a generally consistent form - fitted to the width of the console window so you don’t have to spend time on formatting help text in your utility
Enables you to categorize your supported options. These categories are displayed in the usage instructions. So if you have groups or related sets of options, you can categorize them for readability,
Enables you to explicitly define a brief usage scenario - like “my-utility [options] FILE”. If you don’t explicitly define a brief usage scenario, pycmdparse builds one for you from the defined supported options and positional params.
Injects fields into your subclass based on the defined options so you have an intuitive way of accessing the command line values. Boolean options are python bool fields. Single-value param options are scalars. Multi-valued param options and positional params are lists.