This python argparse tutorial builds a sensor-reading script with –pin, –interval and –output flags. Create an ArgumentParser, add each flag with a type and default, then read the parsed values instead of touching sys.argv yourself.
Our linux command line tutorials cover the shell side of running scripts like this. When the script lives on a headless board, how to find ip address of raspberry pi helps you reach it from another machine.
Before you start
- A working script: any Python script that reads a sensor and prints or saves a value. The example here uses three settings: the pin to read, the delay between readings and the file to write to.
- A terminal: you run the script by typing its name followed by flags, so you need a shell prompt on the machine that runs it.
- No install: argparse is part of the Python standard library, according to the Galaxy Training Network’s argparse tutorial. The Python documentation names it the recommended choice for new command line applications, ahead of getopt and optparse.
- The result: a script that runs with sensible defaults, accepts overrides, rejects bad input with a clear message and prints its own help.
Build the command line step by step
Step 1: See what the script receives
Python hands your script the words typed after its name in the list sys.argv. The Python documentation explains that sys.argv[0] is the name of the program being executed, so your own arguments start at sys.argv[1:]. Every one of them arrives as a string, as the Galaxy tutorial points out, so a pin typed as a number is still text until you convert it.
You could split and convert that list by hand, but you would then write every check and every help message yourself. argparse parses the arguments collected in the sys.argv list for you, which is why it is the better starting point for anything with more than one setting.
Step 2: Create the parser and add the pin flag
Import argparse, create an ArgumentParser with a short description of the script, then call add_argument once per setting. Start with –pin. Because argparse treats options as strings unless you say otherwise, as the argparse HOWTO notes, set the type to int. The PyMOTW argparse guide describes the effect: when a type is provided, the value is converted to that type before it is stored.
That conversion doubles as validation. The Galaxy tutorial describes argparse checking that input values are of the type int, so a typo such as a word in place of a pin number stops the run before any hardware is touched.
Step 3: Make interval and output optional with defaults
To make an argument optional with a default value, give the flag a leading double dash and pass the default parameter. The NashTech argparse guide shows that you can assign a default value to an argument in add_argument(), and that value is used when the flag is left off.
Apply this to –interval (type float or int, with a default delay you are happy to run unattended) and –output (a file name string). Without a default, an absent optional flag is given None as its value, per the argparse HOWTO. That is useful for –output: leaving it as None can mean “print to the screen” rather than “write a file”.
Decide which settings deserve defaults by asking whether the script can sensibly run without them. A sampling delay and an output destination usually can. A pin usually cannot, which leads to the next step.
Step 4: Make the pin required and limit its values
Mark –pin as required. If a required argument is missing from the command line, argparse reports an error instead of running, which the PyMOTW guide describes. This is the right behaviour for a hardware script, because guessing a pin could read the wrong input.
If only certain pins are wired up, add the choices parameter. NashTech’s guide describes it as limiting an argument to values from a defined list. Anything outside the list is rejected with a usage message before your sensor code starts, so a mistyped number cannot reach the hardware.
Step 5: Write help text for every flag
Add a help string to each add_argument call. The same NashTech guide notes that you can provide the help message there, and argparse shows it when someone runs the script with –help. The Galaxy tutorial points out that this works without writing any special code to handle that case.
Write each help line to say what the value means, not just what the flag is called. “Pin the sensor is connected to” tells a reader more than “pin”. When you return to the script after a few months, the help output is the quickest reminder of how it is run.
Step 6: Parse and use the values
Call parse_args() once, then read the results as attributes: the pin, the interval and the output path. Pass those into your reading loop in place of constants typed into the code. Run the script with –help to confirm every flag appears with its description, run it with no arguments to confirm the missing-pin error, and run it with a bad pin type to confirm the rejection.
When you later send readings to a web service, the parsed values slot straight in. The python requests post json example shows what to do with a reading once the script has collected it.
Parameter checkpoint for add_argument
These are the parameters used above, mapped to the sensor script.
| Parameter | What it does | Planning use |
|---|---|---|
| type | Converts the incoming string before it is stored | Use for the pin and the interval so text never reaches the reading loop |
| default | Supplies the fallback when the flag is absent | Use for interval and output so the script runs with no flags |
| required | Triggers an error if the argument is missing | Use for the pin, where guessing is unsafe |
| choices | Limits the value to a defined list | Use when only certain pins or modes are valid |
| help | Adds the description shown by –help | Use on every flag so the script documents itself |
The type and required behaviour are described in the PyMOTW argparse guide, and default, choices and help in the NashTech argparse guide.
When a config file beats flags
Flags suit settings that change from run to run, such as a one-off output file or a different interval while testing. A config file suits settings that stay put: the pin a sensor is permanently wired to, a file location, or a value you would otherwise retype every time. If you start a script from a scheduler or at boot, the command line you wrote once is hard to review, while a config file sits beside the code and can be read and edited.
An INI file read with configparser is a natural fit for a sensor script, with one section per device and one line per setting. A practical pattern is to read the file first and use its values as the defaults you pass to add_argument, so a flag still overrides the file for a single run. Keep the flags for what you change often and the file for what you set once.
argparse or click
The Python documentation lists three argument parsing libraries in the standard library: getopt, optparse and argparse. It describes click as a third party argument processing library. The same page says click allows command line applications to be developed as a set of decorated command implementation functions, so you write functions and attach options to them with decorators, where argparse has you build a parser object and read its results.
- Choose argparse for a single script that needs a few flags. It ships with Python, so a fresh board needs no extra install, and the HOWTO notes it is based on optparse, which helps if you have met that library. PyMOTW records that argparse was added in Python 2.7 and later as a replacement for optparse.
- Choose click when the tool grows into several commands, each with its own options, and you prefer the decorator style. Because it is third party, you must add it as a dependency on every machine that runs the script.
For a sensor script with a pin, an interval and an output file, argparse covers everything with no added dependency.
Frequently asked questions
Is argparse part of the Python standard library?
Yes. The Galaxy Training Network describes it as an argument parsing library for Python, and the Python documentation lists it among the standard library’s argument parsers.
Can I skip argparse and read sys.argv directly?
You can, since sys.argv holds the arguments after the script name. You then do the conversion, error messages and help text yourself, so it only suits tiny scripts with a single value.
How do I add an on/off switch that takes no value?
Use the store_true action. As PyMOTW explains, it saves the appropriate boolean value, so the flag is true when present and false when absent.
Should I keep optparse in an older script?
Leave it if it works, but write new scripts with argparse. The Python documentation names argparse the recommended choice for implementing command line applications.
