A positional parameter is a command-line argument whose meaning comes from its position rather than an option name such as -n or --name. With argparse, positional parameters are usually required and appear without leading dashes. section 1.13 section 1.8
Define positional parameters with argparse and shape their behavior explicitly:
- Give the parameter a descriptive name, such as word, text, letter, or file, instead of leaving the template name positional. section 2.3.1 section 4.4.1
- Declare the parameter with parser.add_argument('word', metavar='word', help='Word'); argparse then exposes the value as args.word. section 2.3.1 section 2.1.4
- Define multiple positional parameters in order: the first declaration receives the first positional value, while options may be declared anywhere relative to them. section 5.5.1
- Use nargs='+' for one or more values and nargs='*' for zero or more; the parsed result is a list when multiple values are accepted. section 3.1 section 6.1.1
- Combine positional parameters with optional flags when a command needs both required input and configurable behavior. section 3.2 section 8.3.1
A word argument
A parser can require one word and use it in the program: parser.add_argument('word', metavar='word', help='A word'). Running ./crowsnest.py narwhal supplies args.word with "narwhal"; running the program without it produces usage documentation and an error. A command such as ./crowsnest.py narwhal --file alternate.txt still works because positional arguments need not precede options. section 2.1.4 section 5.5.1
Several values
For a picnic command, parser.add_argument('item', nargs='+', help='Item(s) to bring') collects ./picnic.py salad chips cupcakes as ['salad', 'chips', 'cupcakes']. The program can count, sort, and format those values as one, two, or three-or-more items. section 3.1 section 3.3 section 3.2
Browse the argparse overview to see how positional arguments, options, flags, validation, and generated help fit together. section 1.13
