Reading program’s command line and doing something with the arguments is the main purpose of most small (or bigger) utilities. Those are often written in Python – because of how easy and fast this is – so there should be a way to parse the command line in Python, too.
And in fact there are quite a few of them, all from the standard library. But the argparse module is most likely the best of them all, equally for its flexibility and power, as well as the sole fact of not being deprecated yet ;-)
For that matter, I have already used it several times, not only in Python. Today I want to present a summary of few useful techniques and solutions that I learned along the way, mostly by braving the not-so-friendly documentation of argparse. Given I’m not likely to do unusual stuff here, they should also address quite common, albeit less trivial use cases.
Following the convention of every operating system imaginable, argparse has positional arguments and flags. Flags are denoted by one or two dashes preceding the name or its one-letter abbreviation:
Normally in argparse, flags take arguments that are later stored in the result object. This would be helpful for parsing something like the
-m (message) flag in the
git commit example above.
Not every flag needs to behave like that, though. In the last
ln example, the
-s does not take any arguments. Instead, it alters the program behavior by its mere presence: with it,
ln creates a symbolic link instead of “hard” link. So in a sense, the flag is boolean. We would like to handle it as such.
Depending on what’s more logical for your program, you can reverse the logic to
default=True, of course.
If your program takes one entity as an argument and does something specific with it, users will often expect it to work with multiple entities too. You can observe it first hand with
or any version control application:
There is no reason to ignore this expectation and it’s pretty easy to satisfy in argparse. Again, there is an
action= for that:
and it’s sufficient for flags. Here the object returned by
parse_args will get
foo attribute with the list of arguments from all occurrences of
For positionals, it’s a little bit trickier because by default, they are meant to appear exactly once. This can be changed using
The value of
'+' is probably the most useful here, as it requires for the argument to be present at least once. Just like for flags, the result will be a list of all its occurrences, so you can iterate or
map over it easily.
Less typically, you may want to have a positional argument which can be supplied or not (an optional one). Although it is possible with the API outlined above, I wouldn’t recommend it: you will have to deal with unnecessary 0-or-1-element list and you won’t get proper error checking at the argparse level.
The correct solution involves
nargs=, too, but with a dedicated
As you may guess,
default= allows you to specify the value in
parse_args result should the argument be omitted.
Once you set up your
ArgumentParser, you will (hopefully) want to test it. Lucky for you, this can be done easily without every touching the actual command line. Simply pass your arguments (as a list) to
parse_args and it will use it instead of
With this you can easily write some nice unit tests for your parser – which you should do, obviously. What you should not do, however, is abusing this feature to call your program’s code from itself:
There are, of course, many other interesting features and applications of argparse that you will find useful. I can especially recommend that you get to know about:
--helpoutput, or for mutual exclusion (e.g.
Equipped with this knowledge, you should be able to write beautiful and easy to use command line tools. Please do so :)
Adding comments is disabled.Comments are disabled.