argparse¶

Command-line parsing library

This module is an optparse-inspired command-line parsing library that:

• handles both optional and positional arguments
• produces highly informative usage messages
• supports parsers that dispatch to sub-parsers

The following is a simple usage example that sums integers from the command-line and writes the result to a file:

parser = argparse.ArgumentParser(
    description='sum the integers at the command line')
parser.add_argument(
    'integers', metavar='int', nargs='+', type=int,
    help='an integer to be summed')
parser.add_argument(
    '--log', default=sys.stdout, type=argparse.FileType('w'),
    help='the file where the sum should be written')
args = parser.parse_args()
args.log.write('%s' % sum(args.integers))
args.log.close()

The module contains the following public classes:

• ArgumentParser – The main entry point for command-line parsing. As the

  example above shows, the add_argument() method is used to populate the parser with actions for optional and positional arguments. Then the parse_args() method is invoked to convert the args at the command-line into an object with attributes.

• ArgumentError – The exception raised by ArgumentParser objects when

  there are errors with the parser’s actions. Errors raised while parsing the command-line are caught by ArgumentParser and emitted as command-line messages.

• FileType – A factory for defining types of files to be created. As the

  example above shows, instances of FileType are typically passed as the type= argument of add_argument() calls.

• Action – The base class for parser actions. Typically actions are

  selected by passing strings like ‘store_true’ or ‘append_const’ to the action= argument of add_argument(). However, for greater customization of ArgumentParser actions, subclasses of Action may be defined and passed as the action= argument.

• HelpFormatter, RawDescriptionHelpFormatter, RawTextHelpFormatter,

  ArgumentDefaultsHelpFormatter – Formatter classes which may be passed as the formatter_class= argument to the ArgumentParser constructor. HelpFormatter is the default, RawDescriptionHelpFormatter and RawTextHelpFormatter tell the parser not to change the formatting for help text, and ArgumentDefaultsHelpFormatter adds information about argument defaults to the help.

All other classes in this module are considered implementation details. (Also note that HelpFormatter and RawDescriptionHelpFormatter are only considered public as object names – the API of the formatter objects is still considered an implementation detail.)