Building user interfaces with Pyokit

Pyokit contains an extension to the built-in python command-line parser. The pyokit.interface.cli.CLI class is used to instantiate user interfaces, and once you have one, you can parse a command line. Options for the user interface are described by objects created from the pyokit.interface.cli.Option class. Both classes are described below.

Here’s an example of creating a simple program with a command-line interface.

import os, sys
from pyokit.interface.cli import CLI, Option

def getUI():
  programName = os.path.basename(sys.argv[0])
  longDescription  =  "This script foos the biz baz and outputs a bar.\n" +\
                      "Usage: ./" + programName + " <biz.txt> <baz.txt>"
  shortDescription =  longDescription
  ui = CLI(programName, shortDescription, longDescription)
  ui.minArgs = 2
  ui.maxArgs = 2
  ui.addOption(Option(short = "v", long = "verbose",
                      description = "output status messages to stderr ",
                      required = False))
  ui.addOption(Option(short = "n", long = "num", argName = "fooNum",
                      description = "number of times to foo the biz baz",
                      required = False, type = int))
  ui.addOption(Option(short = "o", long = "output_fn", argName = "filename",
                      description = "output bar to this file, else stdout",
                      required = False, type = str))
  ui.addOption(Option(short="h", long="help",
                      description="show this help message ", special=True))
  ui.parseCommandLine(sys.argv[1:])
  return ui

def _main():
  ui = getUI()
  if ui.optionIsSet("help") :
    ui.usage()
    sys.exit()
  verbose = (ui.optionIsSet("verbose") == True)
  outfh = open(ui.getValue("output_fn")) \
          if ui.optionIsSet("output_fn") \
          else sys.stdout
  num = ui.getValue("num") if ui.optionIsSet("num") else 1
  biz = [l.strip() for l in open(ui.getArgument(0)) if l.strip() != ""]
  baz = [l.strip() for l in open(ui.getArgument(1)) if l.strip() != ""]
  for i in range(0, num) :
    if (verbose) : sys.stderr.write("fooing the biz baz\n")
    outfh.write("bar " + str(i+1) + ": " +\
                ",".join(biz) + " -- " + ",".join(baz) + "\n")

if __name__ == "__main__":
  _main()

The CLI class

class pyokit.interface.cli.CLI(progName, shortDesc, longDesc)

Represents a command line interface for a program, including the number of arguemnts and the options the program accepts. Provides methods for parsing a command line for the string and interogating the provided arguments and options.

Parameters:
  • progName – the name of the program that this UI is for.
  • shortDesc – a short description of what the program does.
  • longDesc – a long description of what the program does.
addOption(o)

Add a new Option to this CLI.

Parameters:o – the option to add
Raises InterfaceException:
 if an option with that name already exists.
getAllArguments()

Get a list of all the arguments.

Returns:a list of all the arguments, each as a string.
getArgument(num)

Get the num^th argument.

Parameters:num – Which argument to get; indexing here is from 0.
Returns:The num^th agument; arguments are always parsed as strings, so this will be a string.
Raises InterfaceException:
 if there are fewer than num + 1 arguments.
getOption(name)

Get the the Option object associated with the given name.

Parameters:name – the name of the option to retrieve; can be short or long name.
Raises InterfaceException:
 if the named option doesn’t exist.
getValue(name)

Get the value of the option matching the name given.

Parameters:name – the name of the option to retrieve; can be short or long name.
Raises InterfaceException:
 if the named option doesn’t exist.
hasArgument(num)

Check whether the user supplied a particular number of arguments.

Parameters:num – the argument number to check. Arguments are indexed from 0, so asking for the 0th arg will check to see if the user supplied 1 or more args.
Returns:true if the user has supplied at least <num> + 1 arguments.
hasOption(name)

Check whether this CLI has an option with a given name.

Parameters:name – the name of the option to check; can be short or long name.
Returns:true if an option exists in the UI for the given name
optionIsSet(name)

Check whether an option with a given name exists and has been set.

Parameters:name – the name of the option to check; can be short or long name.
Returns:true if an option matching the given name exists and it has had it’s value set by the user
parseCommandLine(line)

Parse the given command line and populate self with the values found.

If the command line doesn’t conform to the specification defined by this CLI object, this function prints a message to stdout indicating what was wrong, prints the program usage instructions and then exists the program

Parameters:line – list of tokens from the command line. Should have had program name removed - generally one would do this: sys.argv[1:]
usage()

Print usage description for this program. Output is to standard out.

The Option class

class pyokit.interface.cli.Option(short, long, description, argName=None, default=None, required=False, type=<type 'str'>, special=False)

Represents an option for a command line interface.

Parameters:
  • short – the short name for the option (should be 1 char long).
  • long – the long name for the option (arbitrary length).
  • description – text description of what the option does.
  • argName – name of the argument, if the option requires one.
  • default – if the option is not given, what default value is used?
  • required – will passing the cmd line fail if this option is missing?
  • type – data type for this option (e.g. int, str, float, etc.)
  • special – if True, disregard requirements for other options when this option is set. Useful for things like help options.
isRequired()

Check whether this is a required option.

Parsing command lines should fail when required options are missing

Returns:True if this option is required, else false.
isSet()

Check whether this option has been set by the user or not.

Returns:True if this option has been set by the user, else false.