Best practices of writing a good usage output for a program

Question

I've been looking online a lot for guidelines that explains how to write a good usage output of a program.

Lets say I have some little program written in Python:

import sys

def main():
    if len(sys.argv < 5):
        print("Wrong usage")
    else:
        #Do something with the 4 parameters
        #First two looks like this: -s1 SOMETHING1
        #Second two looks like this: -s2 SOMETHING2

if __name__ == "__main__":
    main()

And lets say I'm calling this program like this:

py someProgram.py -s1 SOMETHING1 -s2 SOMETHING2

first 2 arguments are required, and the other 2 parameters aren't.

What would be a good practice of a usage message ?

I thought of something like this :

Usage: py program.py -p1 param1 [-p2 param2]

Is this right ? I feel like the -p1 param1 part is wrong, it just doesn't look right.

EDIT: Ok, I'm getting super lost at the argparse documentation. Can someone please provide a simple example of my need ? Is it possible to connect 2 parameters together ? lets say if I'm trying to access args.u it will give me the param1 value ?

@DeepSpace This looks interesting, never knew this module existed, I will look into it. But this is more of a general question of what are the guidelines of writing a usage message. I tried reading this [guideline](http://courses.cms.caltech.edu/cs11/material/general/usage.html) but it really isn't clear when I want 2 parameters to be in the same group, for example `-p1 param1`. — Wahalez, Sep 22 '21 at 14:26
Notice that *most* programs today use a single hyphen for one-letter options, and two hypens for multi-letter options. Thus `-p1 param1` would be the single-letter option `-p` with argument `1`, followed by the non-option argument `param1`. This is confusing. If you intend `param1` to be a parameter to the option `-p1`, then the syntax should probably be `--p1 param1` or `--p1=param1`. argparse will handle this. If you write Python, I *strongly* recommend that you use argparse. Also, check out the GNU Coding Standards. I do not completely agree with either, but they give some uniformity — Ture Pålsson, Sep 22 '21 at 14:56
@TurePålsson There's no standard for this or some conventions ? Also why the double "-" ? And I'm asking it not just for python language. — Wahalez, Sep 22 '21 at 15:07

score 0 · Answer 1 · answered Sep 22 '21 at 17:01

0

If you do

import argparse
ap = argparse.ArgumentParser()
ap.add_argument('-p', type=str)
ap.add_argument('-q', type=int)
ap.add_argument('-x', action='store_true')
ap.add_argument('infile', type=str)
args = ap.parse_args()

and the user says

python3 your_program.py -p foo -q 17 -x hello.txt

then args.p will contain the string foo, args.q will contain the integer 17, args.x will be True, and args.infile will contain the string hello.txt.

answered Sep 22 '21 at 17:01

Ture Pålsson

6,088
2
12
15

How will it output the correct usage if I'm not providing any argument ? What will be the name of the variable after `-p` ? – Wahalez Sep 22 '21 at 18:07
Why don't you just try it? As it happens, the argument to the -p option will be called P (i.e, the name converted to uppercase) but that can be changed using the metavar parameter, [as described in the documentation](https://docs.python.org/3/library/argparse.html#metavar). – Ture Pålsson Sep 22 '21 at 18:17

Best practices of writing a good usage output for a program

1 Answers1