diff -r d9c98730e2e8 Doc/library/argparse.rst --- a/Doc/library/argparse.rst Sat Jul 07 13:34:50 2012 +1000 +++ b/Doc/library/argparse.rst Sat Jul 07 12:10:48 2012 +0200 @@ -28,50 +28,62 @@ Example ------- -The following code is a Python program that takes a list of integers and -produces either the sum or the max:: +The following code is a Python program that demonstrates basic usage:: import argparse - - parser = argparse.ArgumentParser(description='Process some integers.') - parser.add_argument('integers', metavar='N', type=int, nargs='+', - help='an integer for the accumulator') - parser.add_argument('--sum', dest='accumulate', action='store_const', - const=sum, default=max, - help='sum the integers (default: find the max)') - + + + parser = argparse.ArgumentParser(description='Generate report from input file') + parser.add_argument("-i", "--infile", + help="load data from INFILE", + dest="in_filename", metavar="INFILE", required=True) + parser.add_argument("-o", "--outfile", + help="write report to OUTFILE", + dest="out_filename", metavar="OUTFILE", required=True) + parser.add_argument("-l", "--lines", + help="only process specific line numbers from INFILE", + dest="lines", nargs='*') + parser.add_argument("-q", "--quiet", + dest="quiet", action="store_true", + default=False, help="supress status messages") + args = parser.parse_args() - print(args.accumulate(args.integers)) + if not args.quiet: + print("Report will be written to: %s" % args.out_filename) + print("Loading data from: %s" % args.in_filename) + if args.lines: + print("The following lines will be processed: %s" + % ", ".join(args.lines)) Assuming the Python code above is saved into a file called ``prog.py``, it can be run at the command line and provides useful help messages:: - $ prog.py -h - usage: prog.py [-h] [--sum] N [N ...] + $python prog.py -h + usage: prog.py [-h] -i INFILE -o OUTFILE [-l [LINES [LINES ...]]] [-q] + + Generate report from input file + + optional arguments: + -h, --help show this help message and exit + -i INFILE, --infile INFILE + load data from INFILE + -o OUTFILE, --outfile OUTFILE + write report to OUTFILE + -l [LINES [LINES ...]], --lines [LINES [LINES ...]] + only process specific line numbers from INFILE + -q, --quiet supress status messages - Process some integers. +When run with the appropriate arguments, it prints out the expected output:: - positional arguments: - N an integer for the accumulator - - optional arguments: - -h, --help show this help message and exit - --sum sum the integers (default: find the max) - -When run with the appropriate arguments, it prints either the sum or the max of -the command-line integers:: - - $ prog.py 1 2 3 4 - 4 - - $ prog.py 1 2 3 4 --sum - 10 + $ python prog.py -i data.csv -o report.pdf + Report will be written to: report.pdf + Loading data from: data.csv If invalid arguments are passed in, it will issue an error:: - $ prog.py a b c - usage: prog.py [-h] [--sum] N [N ...] - prog.py: error: argument N: invalid int value: 'a' + $ python prog.py a b c + usage: prog.py [-h] -i INFILE -o OUTFILE [-l [LINES [LINES ...]]] [-q] + prog.py: error: argument -i/--infile is required The following sections walk you through this example. @@ -82,7 +94,8 @@ The first step in using the :mod:`argparse` is creating an :class:`ArgumentParser` object:: - >>> parser = argparse.ArgumentParser(description='Process some integers.') + >>> import argparse + >>> parser = argparse.ArgumentParser(description='Generate report from input file') The :class:`ArgumentParser` object will hold all the information necessary to parse the command line into Python data types. @@ -97,17 +110,21 @@ on the command line and turn them into objects. This information is stored and used when :meth:`~ArgumentParser.parse_args` is called. For example:: - >>> parser.add_argument('integers', metavar='N', type=int, nargs='+', - ... help='an integer for the accumulator') - >>> parser.add_argument('--sum', dest='accumulate', action='store_const', - ... const=sum, default=max, - ... help='sum the integers (default: find the max)') + >>> parser.add_argument("-i", "--infile", + ... help="load data from INFILE", + ... dest="in_filename", metavar="INFILE", required=True) + >>> parser.add_argument("-o", "--outfile", + ... help="write report to OUTFILE", + ... dest="out_filename", metavar="OUTFILE", required=True) + >>> parser.add_argument("-l", "--lines", + ... help="only process specific line numbers from INFILE", + ... dest="lines", nargs='*') + >>> parser.add_argument("-q", "--quiet", + ... dest="quiet", action="store_true", + ... default=False, + ... help="supress status messages") -Later, calling :meth:`~ArgumentParser.parse_args` will return an object with -two attributes, ``integers`` and ``accumulate``. The ``integers`` attribute -will be a list of one or more ints, and the ``accumulate`` attribute will be -either the :func:`sum` function, if ``--sum`` was specified at the command line, -or the :func:`max` function if it was not. +Later, calling :meth:`~ArgumentParser.parse_args` will return an object with the attributes, ``in_filename``, ``out_filename``, ``lines`` and ``quiet``. Parsing arguments @@ -119,8 +136,8 @@ In most cases, this means a simple :class:`Namespace` object will be built up from attributes parsed out of the command line:: - >>> parser.parse_args(['--sum', '7', '-1', '42']) - Namespace(accumulate=, integers=[7, -1, 42]) + >>> parser.parse_args(['-i', 'data.csv', '-o', 'report.pdf', '-l', '1', '2', '3']) + Namespace(in_filename='data.csv', lines=['1', '2', '3'], out_filename='report.pdf', quiet=False) In a script, :meth:`~ArgumentParser.parse_args` will typically be called with no arguments, and the :class:`ArgumentParser` will automatically determine the