pycmdparse

Python command line parser, and usage instructions generator

This is a command-line parser that uses yaml to define the set of supported options and params, and associated usage instructions. It supports parsing args, detecting errors, validating param data types, and printing usage instructions.

The goals of pycmdparse are:

1. Require the least amount of programming possible on the part of utility programmers using the package to easily and quickly get good, solid command-line parsing
2. Provide a structure for usage instructions that presents them to the user in a form generally consistent with other console utilities (given that there is variety in the approaches taken by various utility authors)

The usage scenario is: You're writing a console utility in Python, and you have complex args that need to be parsed. You want to parse the args and display usage instructions in a way that is generally consistent with other console utils. So you do the following:

1. Import this package and subclass the CmdLine class in your utility code
2. Initialize the yaml_def field in the base class with a yaml definition of options/params/usage (see below)
3. Call the parse function of the subclass to parse the command line.
4. 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
5. If there is an error parsing the command line, your utility uses the base class to display errors or display usage instructions - as specified in the yaml.

There is a basic example in the example directory in github with extensive documentation of the yaml, and how the yaml is structured and used. Briefly, though, the yaml schema that the package expects is:

    utility:
        name: your utility name
        require_args: true or false based on whether your utility requires options/params

    summary: >
        free form text summmarizing the utility
    
    # If there is no usage section, then it is generated by pycmdparse, otherwise explicit
    # usage is defined here.
    #usage: >
    #  free form text with abbreviated usage

    positional_params:
      params: a list of the positional params supported, e.g. "FROMFILE TOFILE"
      text: >
        free form text describing that the positional params are
        
    supported_options:
      - category: if empty, then no categorization, else displays an option category
        options:
        - name      : a valid python identifier (if not provided, use short
                      key or long key)
          short     : single letter option key (e.g. -v)
          long      : long option key (e.g. --verbose)
          hint      : optional hint to tell the user what parameter to provide
          required  : true or false - if omitted, option is not required
          opt       : option type. One of: bool, param - if omitted, it's a param
                      A param option takes one or more params
          internal  : optional true or false - if internal, does not show in help
          datatype  : optional for basic type validation: int, float, date, bool
          multi-type: optional: exactly n, at most n, no limit
          count     : used if multi-type is exactly or at-most
          default   : optional default value or array of values
          help: >
            free form text describing the option
        - name    : repeats...
          ...
      - category: repeats
        options:
        - name    : repeats
          ...

    details: >
      More detailed text if needed

    examples:
      - example: how you would run your utility from the command line
        explanation: >
          description of what the result would be in this case

      - example: multiple examples if helpful
        explanation: >
          ...

    addendum: >
      free-form text, for copyright, links, etc.

Regarding the 'supported_options', there are two option types: bool is for things like -v, or --verbose that are False by default, and are set to True by the presence of the option on the command line.

The second option type is param. A param option accepts one or more parameters from the command line. Examples: -f filename, or --filelist file1 file2 file3. The behavior is governed by the mult-type and count keys.