argparse add example usage

Question

I use argparse to deal with input parameters, and it outputs the following with parser.print_help():

optional arguments:
  -h, --help            show this help message and exit
  -t TEMPLATES, --templates TEMPLATES
                    template names to make, should be defined as section
                    name in conf, and have related file in templates/
                    folder
  -c CONFPATH, --confpath CONFPATH
                    configuration path for template detail info

my code looks like the following:

    import argparse
    parser = argparse.ArgumentParser(prog='base_maker', description='template maker')
    parser.add_argument('-t', '--templates', help='template names to make, should be defined as section name in conf, and have related file in templates/ folder', type=str)
    parser.add_argument('-c', '--confpath', help='configuration path for template detail info', type=str, default=os.path.join(basepath, 'conf/maker.conf'))

However, I want to add a detailed example about how to use -t/--template, like (added in the example part):

optional arguments:
  -h, --help            show this help message and exit
  -t TEMPLATES, --templates TEMPLATES
                    template names to make, should be defined as section
                    name in conf, and have related file in templates/
                    folder
  -c CONFPATH, --confpath CONFPATH
                    configuration path for template detail info

 example:

     python test.py -t template/test.py
     python test.py -t template/test -c conf/test.conf
     python test.py -t test.py

I don't know which attribute should be used to add "example" part, I check Print program usage example with argparse modulen, but it's unclear and without detailed example when I check epilog in the official doc.

Could anyone give me a example about how to achieve that? Thanks

Have you tried using the mentioned `epilog`? What's wrong with it? — DeepSpace, Nov 04 '16 at 09:32
yes, but how to change line inside it, I want to have multi-lines of explanation, and then I wonder whether there is a better way for it — linpingta, Nov 04 '16 at 09:36
Have you tried passing a `"""multiline string"""` to `epilog`? I'd guess that would do it, line breaks within that will be retained. You can keep it neat as I show [here](http://codereview.stackexchange.com/a/60369/32391). — jonrsharpe, Nov 04 '16 at 09:58

c3st7n · Accepted Answer · 2018-06-08T10:50:47.343

53

You need to use the epilog and the formatter_class arguments to ArgumentParser if you want to have the help the example printed at the end (epilog) and to preserve the whitespace/formatting (formatter_class set to RawDescriptionHelpFormatter).

Example by modifying your example above:

import argparse

example_text = '''example:

 python test.py -t template/test.py
 python test.py -t template/test -c conf/test.conf
 python test.py -t test.py'''

parser = argparse.ArgumentParser(prog='base_maker',
                                 description='template maker',
                                 epilog=example_text,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)

parser.add_argument('-t', '--templates', help='template names to make, should be defined as section name in conf, and have related file in templates/ folder', type=str)
parser.add_argument('-c', '--confpath', help='configuration path for template detail info', type=str, default=os.path.join(basepath, 'conf/maker.conf'))

edited Jun 08 '18 at 10:50

answered Nov 04 '16 at 10:22

c3st7n

1,891
13
15

1

Accurate, thanks, it needs formatter_class setting :) – linpingta Nov 05 '16 at 01:57
I"m already using the `ArgumentDefaultsHelpFormatter`. Guess I have to roll my own then? – Thomas Ahle Sep 09 '19 at 18:27
3

Instead of hard-coding the program name, you can use `$(prog)s` in the example text: `example_text = "$(prog)s -t template/test.py"`, for example. – famzah Jan 04 '21 at 21:16
3

@famzah the specifier is actually `%(prog)s` and not `$(prog)s` – pranavashok Apr 18 '21 at 00:41
3

@pranavashok, you are right! Thanks. The correct example is: ```example_text = "%(prog)s -t template/test.py"``` – famzah Apr 18 '21 at 07:24
@ThomasAhle You can create your own class that inherits from both: `class Formatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter): pass` – Mike Apr 18 '22 at 23:19

argparse add example usage

1 Answers1