argparser module

Command-line argument parser (argparse extension) that adds an option repository.

Module author: Michael S. Chapman <chapmami@ohsu.edu>

Authors:

Michael S. Chapman <chapmami@ohsu.edu>,

Oregon Health & Science University

Version:

0.5, March 23, 2016

Main programs should import this module, subclass ArgumentParser to add support for arguments defined by the main program and/or imported modules, then call parse_args(). The default behaviour of parse_args() is changed to use module global option as the repository into which argument values are put as attributes. If this module is imported into other modules, the sharing of option values is supported.

Changed in version 0.3.9: 05/04/13 - converted from optparse to aargparse.

Changed in version 0.1.0: 8/13/10 Started.

class argparser.ArgumentParser(main=True, dot_file=True, verbose=True, *args, **kwargs)

Bases: argparse.ArgumentParser

Local extensions to argparse used by multiple programs.

Should be subclassed to add program-specific command-line options.

“+<file>” will read options from <file>, one option per line.

..error:: (from argparse.ArgumentParser?) - on ‘help’, mutually exclusive

groups from sub-parsers included in parents are listed as general options and not within the group within which they are defined. Individual sub-parser.print_help() groups correctly.

Parameters:

• main (bool) – Parser for main program (not to be used as parent for another parser). Adds default program information.
• dot_file (bool) – insert commands from ./prog.arg or ~/.prog.arg if present, one per line.
• verbose (bool) – echo command line (if stdout is not a terminal).

dotfile()

Reads command-line-like options from .$PROGNAME.arg in $CWD or $HOME.

finalize()

Completion of the parser after program sub-class initialized.

parse_args(*args, **kwargs)

Parse options on command line (or str args), defaulting namespace to option.

Parameters:namespace – destination of argument-derived attributes. Returns:object containing argument-derived attributes. Return type:argparse.Namespace or user-defined

Changed in version ?: uses __main__.option as default-only namespace if available, else continues to argparse default.

Changed in version ?: now always returns the namespace (never None).

static remaining(namespace)

Remaining tokens reparsed (protecting quoted, bracketed white-space).

Needed for compatibility between cmd2 (which supports trailing commands on command line) with argparse, which tokenizes without regard to the quotes that cmd2 uses for multi-word commands.

After completing argparse, might want to continue program execution with the unused arguments with the following: sys.argv = [sys.argv[0],] + Arguments.remaining(option)

Parameters:namespace (obj) – where argparse has put assigned variables. Returns:reparsed unused tokens Return type:list

class argparser.Arguments(imports=[], main=True, *args, **kwargs)

Bases: argparser.ArgumentParser

Example sub-classing, adding program-specific command-line options.

Parameters:

• imports ((list of) ArgumentParser method(s)) – method(s) adding arguments to ArgumentParser instance. (Alternative to ArgumentParser parents w/ better maintained groups.)
• main (bool) – Parser for main program (i.e. not listed within an ArgumentParser parents argument). Adds default program information.

static export()

Adding options used in both stand-alone and imported modes.

class argparser.CommonOptions

Bases: object

Maintains object option whose attributes are program options.

Should be sub-classed for program-specific options.

asdict()

Dictionary of options, values.

Excludes private attributes, methods and class instances.

Returns:option key and value pairs. Return type:dictionary

class argparser.Options

Bases: argparser.CommonOptions

Repository for all user-controllable parameters.

Minimalist class into which argparser and importing modules will place attributes and properties related to command-line arguments. (option needs to be instantiated before dependent modules are imported.)

argparser.protectedSplit(text, separator=None)

Divide into words w/ separator not protected by quotes, brackets.

Parameters:

• text (str) – to be parsed
• separator (str) – token separator, if None - any whitespace.

argparser.quoted(text)

argparser.token(text, separator=None)

1st token before a separator not protected by quotes, brackets.

Parameters:

• text (str) – to be parsed
• separator (str) – token separator, if None - any whitespace.