python gflags

overview

DEFINE_* creates a Flag object and registers it with a FlagValues object (typically the global FlagValues FLAGS).

The FlagValues object can scan the command line arguments and pass flag arguments to the corresponding Flag objects for value-checking and type conversion.

The flags are accessed through a FlagValues object, for instance gflags.FLAGS.myflag.

Typically, the __main__ module passes the command line arguments to gflags.FLAGS for parsing.

flags definition format

• use DEFINE_*
• take a name, default value, help-string, and optional short name (one-letter name)
• flag names must be unique, if conflict will throw an error.

DEFINE_string

takes any input, and interprets it as a string.

DEFINE_bool or DEFINE_boolean

typically does not take an argument: say –myflag to set FLAGS.myflag to true, or –nomyflag to set FLAGS.myflag to false. Alternately, you can say –myflag=true or –myflag=t or –myflag=1 or –myflag=false or –myflag=f or –myflag=0

DEFINE_float

takes an input and interprets it as a floating point number. Takes optional args lower_bound and upper_bound; if the number specified on the command line is out of range, it will raise a FlagError.

DEFINE_integer

takes an input and interprets it as an integer. Takes optional args lower_bound and upper_bound as for floats.

DEFINE_enum

takes a list of strings which represents legal values. If the command-line value is not in this list, raise a flag error. Otherwise, assign to FLAGS.flag as a string.

DEFINE_list

Takes a comma-separated list of strings on the commandline. Stores them in a python list object.

DEFINE_spaceseplist

Takes a space-separated list of strings on the commandline. Stores them in a python list object. Example: –myspacesepflag “foo bar baz”

DEFINE_multistring

The same as DEFINE_string, except the flag can be specified more than once on the commandline. The result is a python list object (list of strings), even if the flag is only on the command line once.

DEFINE_multi_int

The same as DEFINE_integer, except the flag can be specified more than once on the commandline. The result is a python list object (list of ints), even if the flag is only on the command line once.

validator

If you want to enforce a constraint over one flag, use

gflags.RegisterValidator(flag_name,
                        checker,
                        message='Flag validation failed',
                        flag_values=FLAGS)

gflags.MarkFlagAsRequired(flag_name)

use flags from file

Any flags you don’t feel like typing, throw them in a file, one flag per
line, for instance:

--myflag=myvalue
--nomyboolean_flag

You then specify your file with the special flag --flagfile=somefile.
You CAN recursively nest flagfile= tokens OR use multiple files on the
command line. Lines beginning with a single hash ‘#’ or a double slash
‘//’ are comments in your flagfile.

Any flagfile=<file> will be interpreted as having a relative path from
the current working directory rather than from the place the file was
included from.