Using Command-Line Flags in Infra.git

Processing command-line arguments (aka flags) is done using the standard Python argparse module, with a very thin convenience layer on top of it.

One design principle is that flags are defined per-package. To be consistent across the codebase, it is recommended that each package defines the top-level functions add_argparse_options and process_argparse_options. The first is supposed to define flags by calling methods like ArgumentParser.add_argument(), plus do some minor processing without any side-effect. The second function does some package-level processing based on the result of the parsed command-line.

Example usage from a top-level script, with the infra_libs.logs package:

import argparse
import infra_libs.logs

parser = argparse.ArgumentParser()

options = parser.parse_args()

As more packages add their own flags, the output of --help can quickly become unreadable. To help with that, it is recommended that

  • each package defines an option group
  • each option for a given package starts with the same prefix

Example (from the infra_libs.ts_mon package):

def add_argparse_options(parser):
  parser = parser.add_argument_group('Timeseries Monitoring Options')
    help='url (including file://) to post monitoring metrics to.'
         ' (default: %(default)s)')
    help=('automatically push metrics on this interval if '
 # ... other arguments below ...