Custom Usage Message for Python

Spellcrafting in Python is approachable and enjoyable. The library argparse facilitates the parsing of arguments for code destined for wide distribution.

Below is an example of basic argparse usage

#!/usr/bin/env python3

"""
in this example get input from the user
and manlipulate it
"""

from argparse import RawTextHelpFormatter
import argparse,sys

def get_args():
    parser = argparse.ArgumentParser(formatter_class=RawTextHelpFormatter)
    arg_grp = parser.add_argument_group('arguments')

    # add an argument to take an int 
    # set the default to None to check for errors, required
    arg_grp.add_argument('-n',type=int,default=None)

    # add a required argument for a string
    # set the required option to True 
    # this argument has two flags, -s --string
    arg_grp.add_argument('-s','--string',type=str,required=True)

    # this command loads the args
    # object with user input
    args = parser.parse_args()

    return args

if __name__ == '__main__':
    args = get_args()
     
    # obtain user input from the 
    # args object returned from get_args
    my_int, my_str = args.n,args.string

    # check if the user supplied an int to -n
    # exit if not found
    if(my_int==None): 
        sys.stderr.write('FATAL ERROR: -n is required\n')
        sys.exit(1)
    print('\n{} + 5 IS {}\nYOUR STRING IS {}, KICKASS{}\n'.format(my_int,my_int+5,my_str,my_str))

Copy and paste it and try it out.

$ python basic_argparse.py -n 10 -s BioSigil


    10 + 5 IS 15
    YOUR STRING IS BioSigil, KICKASSBioSigil

Try not passing an argument to "-n" and see the failure.

Now type in this command and take heed of its magic.

$ python basic_argparse.py -h

usage: basic_argparse.py [-h] [-n N] -s STRING

optional arguments:
  -h, --help            show this help message and exit

arguments:
  -n N
  -s STRING, --string STRING

Argparse provides '-h, --help' as a default argument with a boilerplate usage message.

Customize Usage Message

Argparse is fantastic, but the usage message can get cluttered with a lot of arguments. Magi can create custom usage messages with argparse, below is an example.

#!/usr/bin/env python3

"""
custom usage message example
"""

from argparse import RawTextHelpFormatter
import argparse,sys

__version__='0.0.1'
# usage message below
__usage___="""

______ _       _____ _       _ _ 
| ___ (_)     /  ___(_)     (_) |
| |_/ /_  ___ \ `--. _  __ _ _| |
| ___ \ |/ _ \ `--. \ |/ _` | | |
| |_/ / | (_) /\__/ / | (_| | | |
\____/|_|\___/\____/|_|\__, |_|_|
                        __/ |    
                       |___/     

BioSigil Blog Custom Usage Example
Version {}    Author: BioSigil <biosigil.blog at gmail dot com>   

  Usage: custom_usage   -n INT  -s,--string  STR

arguments: 

  -n              INT        integer input, required
  -s, --string    STR        string input, required

""".format(__version__)

def get_args():
    # pass the custom usage string 
    parser = argparse.ArgumentParser(formatter_class=RawTextHelpFormatter,usage=__usage___,add_help=False)
    arg_grp = parser.add_argument_group('arguments')
    arg_grp.add_argument('-n',type=int,default=None)
    arg_grp.add_argument('-s','--string',type=str,required=True)
    args = parser.parse_args()

    return args

if __name__ == '__main__':
    args = get_args()
    my_int, my_str = args.n,args.string
    if(my_int==None): 
        sys.stderr.write('FATAL ERROR: -n is required\n')
        sys.exit(1)
    print('\n{} + 5 IS {}\nYOUR STRING IS {}, KICKASS{}\n'.format(my_int,my_int+5,my_str,my_str))

Now pass the "-h" argument

$ python custom_usage.py -h
usage: 

______ _       _____ _       _ _ 
| ___ (_)     /  ___(_)     (_) |
| |_/ /_  ___ \ `--. _  __ _ _| |
| ___ \ |/ _ \ `--. \ |/ _` | | |
| |_/ / | (_) /\__/ / | (_| | | |
\____/|_|\___/\____/|_|\__, |_|_|
                        __/ |    
                       |___/     

BioSigil Blog Custom Usage Example
Version 0.0.1    Author: BioSigil <biosigil.blog at gmail dot com>   

  Usage: custom_usage   -n INT  -s,--string  STR

arguments: 

  -n              INT        integer input, required
  -s, --string    STR        string input, required
custom_usage.py: error: the following arguments are required: -s/--string