Joe Gregorio | 34044bc | 2011-03-07 16:58:33 -0500 | [diff] [blame] | 1 | #!/usr/bin/env python |
| 2 | |
| 3 | # Copyright (c) 2007, Google Inc. |
| 4 | # All rights reserved. |
| 5 | # |
| 6 | # Redistribution and use in source and binary forms, with or without |
| 7 | # modification, are permitted provided that the following conditions are |
| 8 | # met: |
| 9 | # |
| 10 | # * Redistributions of source code must retain the above copyright |
| 11 | # notice, this list of conditions and the following disclaimer. |
| 12 | # * Redistributions in binary form must reproduce the above |
| 13 | # copyright notice, this list of conditions and the following disclaimer |
| 14 | # in the documentation and/or other materials provided with the |
| 15 | # distribution. |
| 16 | # * Neither the name of Google Inc. nor the names of its |
| 17 | # contributors may be used to endorse or promote products derived from |
| 18 | # this software without specific prior written permission. |
| 19 | # |
| 20 | # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 21 | # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 22 | # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 23 | # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 24 | # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 25 | # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 26 | # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 27 | # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 28 | # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 29 | # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 30 | # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 31 | # |
| 32 | # --- |
| 33 | # Author: Chad Lester |
| 34 | # Design and style contributions by: |
| 35 | # Amit Patel, Bogdan Cocosel, Daniel Dulitz, Eric Tiedemann, |
| 36 | # Eric Veach, Laurence Gonsalves, Matthew Springer |
| 37 | # Code reorganized a bit by Craig Silverstein |
| 38 | |
| 39 | """This module is used to define and parse command line flags. |
| 40 | |
| 41 | This module defines a *distributed* flag-definition policy: rather than |
| 42 | an application having to define all flags in or near main(), each python |
| 43 | module defines flags that are useful to it. When one python module |
| 44 | imports another, it gains access to the other's flags. (This is |
| 45 | implemented by having all modules share a common, global registry object |
| 46 | containing all the flag information.) |
| 47 | |
| 48 | Flags are defined through the use of one of the DEFINE_xxx functions. |
| 49 | The specific function used determines how the flag is parsed, checked, |
| 50 | and optionally type-converted, when it's seen on the command line. |
| 51 | |
| 52 | |
| 53 | IMPLEMENTATION: DEFINE_* creates a 'Flag' object and registers it with a |
| 54 | 'FlagValues' object (typically the global FlagValues FLAGS, defined |
| 55 | here). The 'FlagValues' object can scan the command line arguments and |
| 56 | pass flag arguments to the corresponding 'Flag' objects for |
| 57 | value-checking and type conversion. The converted flag values are |
| 58 | available as attributes of the 'FlagValues' object. |
| 59 | |
| 60 | Code can access the flag through a FlagValues object, for instance |
| 61 | gflags.FLAGS.myflag. Typically, the __main__ module passes the |
| 62 | command line arguments to gflags.FLAGS for parsing. |
| 63 | |
| 64 | At bottom, this module calls getopt(), so getopt functionality is |
| 65 | supported, including short- and long-style flags, and the use of -- to |
| 66 | terminate flags. |
| 67 | |
| 68 | Methods defined by the flag module will throw 'FlagsError' exceptions. |
| 69 | The exception argument will be a human-readable string. |
| 70 | |
| 71 | |
| 72 | FLAG TYPES: This is a list of the DEFINE_*'s that you can do. All flags |
| 73 | take a name, default value, help-string, and optional 'short' name |
| 74 | (one-letter name). Some flags have other arguments, which are described |
| 75 | with the flag. |
| 76 | |
| 77 | DEFINE_string: takes any input, and interprets it as a string. |
| 78 | |
| 79 | DEFINE_bool or |
| 80 | DEFINE_boolean: typically does not take an argument: say --myflag to |
| 81 | set FLAGS.myflag to true, or --nomyflag to set |
| 82 | FLAGS.myflag to false. Alternately, you can say |
| 83 | --myflag=true or --myflag=t or --myflag=1 or |
| 84 | --myflag=false or --myflag=f or --myflag=0 |
| 85 | |
| 86 | DEFINE_float: takes an input and interprets it as a floating point |
| 87 | number. Takes optional args lower_bound and upper_bound; |
| 88 | if the number specified on the command line is out of |
| 89 | range, it will raise a FlagError. |
| 90 | |
| 91 | DEFINE_integer: takes an input and interprets it as an integer. Takes |
| 92 | optional args lower_bound and upper_bound as for floats. |
| 93 | |
| 94 | DEFINE_enum: takes a list of strings which represents legal values. If |
| 95 | the command-line value is not in this list, raise a flag |
| 96 | error. Otherwise, assign to FLAGS.flag as a string. |
| 97 | |
| 98 | DEFINE_list: Takes a comma-separated list of strings on the commandline. |
| 99 | Stores them in a python list object. |
| 100 | |
| 101 | DEFINE_spaceseplist: Takes a space-separated list of strings on the |
| 102 | commandline. Stores them in a python list object. |
| 103 | Example: --myspacesepflag "foo bar baz" |
| 104 | |
| 105 | DEFINE_multistring: The same as DEFINE_string, except the flag can be |
| 106 | specified more than once on the commandline. The |
| 107 | result is a python list object (list of strings), |
| 108 | even if the flag is only on the command line once. |
| 109 | |
| 110 | DEFINE_multi_int: The same as DEFINE_integer, except the flag can be |
| 111 | specified more than once on the commandline. The |
| 112 | result is a python list object (list of ints), even if |
| 113 | the flag is only on the command line once. |
| 114 | |
| 115 | |
| 116 | SPECIAL FLAGS: There are a few flags that have special meaning: |
| 117 | --help prints a list of all the flags in a human-readable fashion |
| 118 | --helpshort prints a list of all key flags (see below). |
| 119 | --helpxml prints a list of all flags, in XML format. DO NOT parse |
| 120 | the output of --help and --helpshort. Instead, parse |
| 121 | the output of --helpxml. For more info, see |
| 122 | "OUTPUT FOR --helpxml" below. |
| 123 | --flagfile=foo read flags from file foo. |
| 124 | --undefok=f1,f2 ignore unrecognized option errors for f1,f2. |
| 125 | For boolean flags, you should use --undefok=boolflag, and |
| 126 | --boolflag and --noboolflag will be accepted. Do not use |
| 127 | --undefok=noboolflag. |
| 128 | -- as in getopt(), terminates flag-processing |
| 129 | |
| 130 | |
| 131 | FLAGS VALIDATORS: If your program: |
| 132 | - requires flag X to be specified |
| 133 | - needs flag Y to match a regular expression |
| 134 | - or requires any more general constraint to be satisfied |
| 135 | then validators are for you! |
| 136 | |
| 137 | Each validator represents a constraint over one flag, which is enforced |
| 138 | starting from the initial parsing of the flags and until the program |
| 139 | terminates. |
| 140 | |
| 141 | Also, lower_bound and upper_bound for numerical flags are enforced using flag |
| 142 | validators. |
| 143 | |
| 144 | Howto: |
| 145 | If you want to enforce a constraint over one flag, use |
| 146 | |
| 147 | flags.RegisterValidator(flag_name, |
| 148 | checker, |
| 149 | message='Flag validation failed', |
| 150 | flag_values=FLAGS) |
| 151 | |
| 152 | After flag values are initially parsed, and after any change to the specified |
| 153 | flag, method checker(flag_value) will be executed. If constraint is not |
| 154 | satisfied, an IllegalFlagValue exception will be raised. See |
| 155 | RegisterValidator's docstring for a detailed explanation on how to construct |
| 156 | your own checker. |
| 157 | |
| 158 | |
| 159 | EXAMPLE USAGE: |
| 160 | |
| 161 | FLAGS = flags.FLAGS |
| 162 | |
| 163 | flags.DEFINE_integer('my_version', 0, 'Version number.') |
| 164 | flags.DEFINE_string('filename', None, 'Input file name', short_name='f') |
| 165 | |
| 166 | flags.RegisterValidator('my_version', |
| 167 | lambda value: value % 2 == 0, |
| 168 | message='--my_version must be divisible by 2') |
| 169 | flags.MarkFlagAsRequired('filename') |
| 170 | |
| 171 | |
| 172 | NOTE ON --flagfile: |
| 173 | |
| 174 | Flags may be loaded from text files in addition to being specified on |
| 175 | the commandline. |
| 176 | |
| 177 | Any flags you don't feel like typing, throw them in a file, one flag per |
| 178 | line, for instance: |
| 179 | --myflag=myvalue |
| 180 | --nomyboolean_flag |
| 181 | You then specify your file with the special flag '--flagfile=somefile'. |
| 182 | You CAN recursively nest flagfile= tokens OR use multiple files on the |
| 183 | command line. Lines beginning with a single hash '#' or a double slash |
| 184 | '//' are comments in your flagfile. |
| 185 | |
| 186 | Any flagfile=<file> will be interpreted as having a relative path from |
| 187 | the current working directory rather than from the place the file was |
| 188 | included from: |
| 189 | myPythonScript.py --flagfile=config/somefile.cfg |
| 190 | |
| 191 | If somefile.cfg includes further --flagfile= directives, these will be |
| 192 | referenced relative to the original CWD, not from the directory the |
| 193 | including flagfile was found in! |
| 194 | |
| 195 | The caveat applies to people who are including a series of nested files |
| 196 | in a different dir than they are executing out of. Relative path names |
| 197 | are always from CWD, not from the directory of the parent include |
| 198 | flagfile. We do now support '~' expanded directory names. |
| 199 | |
| 200 | Absolute path names ALWAYS work! |
| 201 | |
| 202 | |
| 203 | EXAMPLE USAGE: |
| 204 | |
| 205 | import gflags |
| 206 | FLAGS = gflags.FLAGS |
| 207 | |
| 208 | # Flag names are globally defined! So in general, we need to be |
| 209 | # careful to pick names that are unlikely to be used by other libraries. |
| 210 | # If there is a conflict, we'll get an error at import time. |
| 211 | gflags.DEFINE_string('name', 'Mr. President', 'your name') |
| 212 | gflags.DEFINE_integer('age', None, 'your age in years', lower_bound=0) |
| 213 | gflags.DEFINE_boolean('debug', False, 'produces debugging output') |
| 214 | gflags.DEFINE_enum('gender', 'male', ['male', 'female'], 'your gender') |
| 215 | |
| 216 | def main(argv): |
| 217 | try: |
| 218 | argv = FLAGS(argv) # parse flags |
| 219 | except gflags.FlagsError, e: |
| 220 | print '%s\\nUsage: %s ARGS\\n%s' % (e, sys.argv[0], FLAGS) |
| 221 | sys.exit(1) |
| 222 | if FLAGS.debug: print 'non-flag arguments:', argv |
| 223 | print 'Happy Birthday', FLAGS.name |
| 224 | if FLAGS.age is not None: |
| 225 | print 'You are a %s, who is %d years old' % (FLAGS.gender, FLAGS.age) |
| 226 | |
| 227 | if __name__ == '__main__': |
| 228 | main(sys.argv) |
| 229 | |
| 230 | |
| 231 | KEY FLAGS: |
| 232 | |
| 233 | As we already explained, each module gains access to all flags defined |
| 234 | by all the other modules it transitively imports. In the case of |
| 235 | non-trivial scripts, this means a lot of flags ... For documentation |
| 236 | purposes, it is good to identify the flags that are key (i.e., really |
| 237 | important) to a module. Clearly, the concept of "key flag" is a |
| 238 | subjective one. When trying to determine whether a flag is key to a |
| 239 | module or not, assume that you are trying to explain your module to a |
| 240 | potential user: which flags would you really like to mention first? |
| 241 | |
| 242 | We'll describe shortly how to declare which flags are key to a module. |
| 243 | For the moment, assume we know the set of key flags for each module. |
| 244 | Then, if you use the app.py module, you can use the --helpshort flag to |
| 245 | print only the help for the flags that are key to the main module, in a |
| 246 | human-readable format. |
| 247 | |
| 248 | NOTE: If you need to parse the flag help, do NOT use the output of |
| 249 | --help / --helpshort. That output is meant for human consumption, and |
| 250 | may be changed in the future. Instead, use --helpxml; flags that are |
| 251 | key for the main module are marked there with a <key>yes</key> element. |
| 252 | |
| 253 | The set of key flags for a module M is composed of: |
| 254 | |
| 255 | 1. Flags defined by module M by calling a DEFINE_* function. |
| 256 | |
| 257 | 2. Flags that module M explictly declares as key by using the function |
| 258 | |
| 259 | DECLARE_key_flag(<flag_name>) |
| 260 | |
| 261 | 3. Key flags of other modules that M specifies by using the function |
| 262 | |
| 263 | ADOPT_module_key_flags(<other_module>) |
| 264 | |
| 265 | This is a "bulk" declaration of key flags: each flag that is key for |
| 266 | <other_module> becomes key for the current module too. |
| 267 | |
| 268 | Notice that if you do not use the functions described at points 2 and 3 |
| 269 | above, then --helpshort prints information only about the flags defined |
| 270 | by the main module of our script. In many cases, this behavior is good |
| 271 | enough. But if you move part of the main module code (together with the |
| 272 | related flags) into a different module, then it is nice to use |
| 273 | DECLARE_key_flag / ADOPT_module_key_flags and make sure --helpshort |
| 274 | lists all relevant flags (otherwise, your code refactoring may confuse |
| 275 | your users). |
| 276 | |
| 277 | Note: each of DECLARE_key_flag / ADOPT_module_key_flags has its own |
| 278 | pluses and minuses: DECLARE_key_flag is more targeted and may lead a |
| 279 | more focused --helpshort documentation. ADOPT_module_key_flags is good |
| 280 | for cases when an entire module is considered key to the current script. |
| 281 | Also, it does not require updates to client scripts when a new flag is |
| 282 | added to the module. |
| 283 | |
| 284 | |
| 285 | EXAMPLE USAGE 2 (WITH KEY FLAGS): |
| 286 | |
| 287 | Consider an application that contains the following three files (two |
| 288 | auxiliary modules and a main module): |
| 289 | |
| 290 | File libfoo.py: |
| 291 | |
| 292 | import gflags |
| 293 | |
| 294 | gflags.DEFINE_integer('num_replicas', 3, 'Number of replicas to start') |
| 295 | gflags.DEFINE_boolean('rpc2', True, 'Turn on the usage of RPC2.') |
| 296 | |
| 297 | ... some code ... |
| 298 | |
| 299 | File libbar.py: |
| 300 | |
| 301 | import gflags |
| 302 | |
| 303 | gflags.DEFINE_string('bar_gfs_path', '/gfs/path', |
| 304 | 'Path to the GFS files for libbar.') |
| 305 | gflags.DEFINE_string('email_for_bar_errors', 'bar-team@google.com', |
| 306 | 'Email address for bug reports about module libbar.') |
| 307 | gflags.DEFINE_boolean('bar_risky_hack', False, |
| 308 | 'Turn on an experimental and buggy optimization.') |
| 309 | |
| 310 | ... some code ... |
| 311 | |
| 312 | File myscript.py: |
| 313 | |
| 314 | import gflags |
| 315 | import libfoo |
| 316 | import libbar |
| 317 | |
| 318 | gflags.DEFINE_integer('num_iterations', 0, 'Number of iterations.') |
| 319 | |
| 320 | # Declare that all flags that are key for libfoo are |
| 321 | # key for this module too. |
| 322 | gflags.ADOPT_module_key_flags(libfoo) |
| 323 | |
| 324 | # Declare that the flag --bar_gfs_path (defined in libbar) is key |
| 325 | # for this module. |
| 326 | gflags.DECLARE_key_flag('bar_gfs_path') |
| 327 | |
| 328 | ... some code ... |
| 329 | |
| 330 | When myscript is invoked with the flag --helpshort, the resulted help |
| 331 | message lists information about all the key flags for myscript: |
| 332 | --num_iterations, --num_replicas, --rpc2, and --bar_gfs_path (in |
| 333 | addition to the special flags --help and --helpshort). |
| 334 | |
| 335 | Of course, myscript uses all the flags declared by it (in this case, |
| 336 | just --num_replicas) or by any of the modules it transitively imports |
| 337 | (e.g., the modules libfoo, libbar). E.g., it can access the value of |
| 338 | FLAGS.bar_risky_hack, even if --bar_risky_hack is not declared as a key |
| 339 | flag for myscript. |
| 340 | |
| 341 | |
| 342 | OUTPUT FOR --helpxml: |
| 343 | |
| 344 | The --helpxml flag generates output with the following structure: |
| 345 | |
| 346 | <?xml version="1.0"?> |
| 347 | <AllFlags> |
| 348 | <program>PROGRAM_BASENAME</program> |
| 349 | <usage>MAIN_MODULE_DOCSTRING</usage> |
| 350 | (<flag> |
| 351 | [<key>yes</key>] |
| 352 | <file>DECLARING_MODULE</file> |
| 353 | <name>FLAG_NAME</name> |
| 354 | <meaning>FLAG_HELP_MESSAGE</meaning> |
| 355 | <default>DEFAULT_FLAG_VALUE</default> |
| 356 | <current>CURRENT_FLAG_VALUE</current> |
| 357 | <type>FLAG_TYPE</type> |
| 358 | [OPTIONAL_ELEMENTS] |
| 359 | </flag>)* |
| 360 | </AllFlags> |
| 361 | |
| 362 | Notes: |
| 363 | |
| 364 | 1. The output is intentionally similar to the output generated by the |
| 365 | C++ command-line flag library. The few differences are due to the |
| 366 | Python flags that do not have a C++ equivalent (at least not yet), |
| 367 | e.g., DEFINE_list. |
| 368 | |
| 369 | 2. New XML elements may be added in the future. |
| 370 | |
| 371 | 3. DEFAULT_FLAG_VALUE is in serialized form, i.e., the string you can |
| 372 | pass for this flag on the command-line. E.g., for a flag defined |
| 373 | using DEFINE_list, this field may be foo,bar, not ['foo', 'bar']. |
| 374 | |
| 375 | 4. CURRENT_FLAG_VALUE is produced using str(). This means that the |
| 376 | string 'false' will be represented in the same way as the boolean |
| 377 | False. Using repr() would have removed this ambiguity and simplified |
| 378 | parsing, but would have broken the compatibility with the C++ |
| 379 | command-line flags. |
| 380 | |
| 381 | 5. OPTIONAL_ELEMENTS describe elements relevant for certain kinds of |
| 382 | flags: lower_bound, upper_bound (for flags that specify bounds), |
| 383 | enum_value (for enum flags), list_separator (for flags that consist of |
| 384 | a list of values, separated by a special token). |
| 385 | |
| 386 | 6. We do not provide any example here: please use --helpxml instead. |
| 387 | """ |
| 388 | |
| 389 | import cgi |
| 390 | import getopt |
| 391 | import os |
| 392 | import re |
| 393 | import string |
| 394 | import sys |
| 395 | |
| 396 | import gflags_validators |
| 397 | |
| 398 | # Are we running at least python 2.2? |
| 399 | try: |
| 400 | if tuple(sys.version_info[:3]) < (2,2,0): |
| 401 | raise NotImplementedError("requires python 2.2.0 or later") |
| 402 | except AttributeError: # a very old python, that lacks sys.version_info |
| 403 | raise NotImplementedError("requires python 2.2.0 or later") |
| 404 | |
| 405 | # If we're not running at least python 2.2.1, define True, False, and bool. |
| 406 | # Thanks, Guido, for the code. |
| 407 | try: |
| 408 | True, False, bool |
| 409 | except NameError: |
| 410 | False = 0 |
| 411 | True = 1 |
| 412 | def bool(x): |
| 413 | if x: |
| 414 | return True |
| 415 | else: |
| 416 | return False |
| 417 | |
| 418 | # Are we running under pychecker? |
| 419 | _RUNNING_PYCHECKER = 'pychecker.python' in sys.modules |
| 420 | |
| 421 | |
| 422 | def _GetCallingModule(): |
| 423 | """Returns the name of the module that's calling into this module. |
| 424 | |
| 425 | We generally use this function to get the name of the module calling a |
| 426 | DEFINE_foo... function. |
| 427 | """ |
| 428 | # Walk down the stack to find the first globals dict that's not ours. |
| 429 | for depth in range(1, sys.getrecursionlimit()): |
| 430 | if not sys._getframe(depth).f_globals is globals(): |
| 431 | globals_for_frame = sys._getframe(depth).f_globals |
| 432 | module_name = _GetModuleObjectAndName(globals_for_frame)[1] |
| 433 | if module_name is not None: |
| 434 | return module_name |
| 435 | raise AssertionError("No module was found") |
| 436 | |
| 437 | |
| 438 | def _GetThisModuleObjectAndName(): |
| 439 | """Returns: (module object, module name) for this module.""" |
| 440 | return _GetModuleObjectAndName(globals()) |
| 441 | |
| 442 | |
| 443 | # module exceptions: |
| 444 | class FlagsError(Exception): |
| 445 | """The base class for all flags errors.""" |
| 446 | pass |
| 447 | |
| 448 | |
| 449 | class DuplicateFlag(FlagsError): |
| 450 | """Raised if there is a flag naming conflict.""" |
| 451 | pass |
| 452 | |
| 453 | |
| 454 | class DuplicateFlagCannotPropagateNoneToSwig(DuplicateFlag): |
| 455 | """Special case of DuplicateFlag -- SWIG flag value can't be set to None. |
| 456 | |
| 457 | This can be raised when a duplicate flag is created. Even if allow_override is |
| 458 | True, we still abort if the new value is None, because it's currently |
| 459 | impossible to pass None default value back to SWIG. See FlagValues.SetDefault |
| 460 | for details. |
| 461 | """ |
| 462 | pass |
| 463 | |
| 464 | |
| 465 | # A DuplicateFlagError conveys more information than a |
| 466 | # DuplicateFlag. Since there are external modules that create |
| 467 | # DuplicateFlags, the interface to DuplicateFlag shouldn't change. |
| 468 | class DuplicateFlagError(DuplicateFlag): |
| 469 | |
| 470 | def __init__(self, flagname, flag_values): |
| 471 | self.flagname = flagname |
| 472 | message = "The flag '%s' is defined twice." % self.flagname |
| 473 | flags_by_module = flag_values.FlagsByModuleDict() |
| 474 | for module in flags_by_module: |
| 475 | for flag in flags_by_module[module]: |
| 476 | if flag.name == flagname or flag.short_name == flagname: |
| 477 | message = message + " First from " + module + "," |
| 478 | break |
| 479 | message = message + " Second from " + _GetCallingModule() |
| 480 | DuplicateFlag.__init__(self, message) |
| 481 | |
| 482 | |
| 483 | class IllegalFlagValue(FlagsError): |
| 484 | """The flag command line argument is illegal.""" |
| 485 | pass |
| 486 | |
| 487 | |
| 488 | class UnrecognizedFlag(FlagsError): |
| 489 | """Raised if a flag is unrecognized.""" |
| 490 | pass |
| 491 | |
| 492 | |
| 493 | # An UnrecognizedFlagError conveys more information than an UnrecognizedFlag. |
| 494 | # Since there are external modules that create DuplicateFlags, the interface to |
| 495 | # DuplicateFlag shouldn't change. The flagvalue will be assigned the full value |
| 496 | # of the flag and its argument, if any, allowing handling of unrecognzed flags |
| 497 | # in an exception handler. |
| 498 | # If flagvalue is the empty string, then this exception is an due to a |
| 499 | # reference to a flag that was not already defined. |
| 500 | class UnrecognizedFlagError(UnrecognizedFlag): |
| 501 | def __init__(self, flagname, flagvalue=''): |
| 502 | self.flagname = flagname |
| 503 | self.flagvalue = flagvalue |
| 504 | UnrecognizedFlag.__init__( |
| 505 | self, "Unknown command line flag '%s'" % flagname) |
| 506 | |
| 507 | # Global variable used by expvar |
| 508 | _exported_flags = {} |
| 509 | _help_width = 80 # width of help output |
| 510 | |
| 511 | |
| 512 | def GetHelpWidth(): |
| 513 | """Returns: an integer, the width of help lines that is used in TextWrap.""" |
| 514 | return _help_width |
| 515 | |
| 516 | |
| 517 | def CutCommonSpacePrefix(text): |
| 518 | """Removes a common space prefix from the lines of a multiline text. |
| 519 | |
| 520 | If the first line does not start with a space, it is left as it is and |
| 521 | only in the remaining lines a common space prefix is being searched |
| 522 | for. That means the first line will stay untouched. This is especially |
| 523 | useful to turn doc strings into help texts. This is because some |
| 524 | people prefer to have the doc comment start already after the |
| 525 | apostrophy and then align the following lines while others have the |
| 526 | apostrophies on a seperately line. |
| 527 | |
| 528 | The function also drops trailing empty lines and ignores empty lines |
| 529 | following the initial content line while calculating the initial |
| 530 | common whitespace. |
| 531 | |
| 532 | Args: |
| 533 | text: text to work on |
| 534 | |
| 535 | Returns: |
| 536 | the resulting text |
| 537 | """ |
| 538 | text_lines = text.splitlines() |
| 539 | # Drop trailing empty lines |
| 540 | while text_lines and not text_lines[-1]: |
| 541 | text_lines = text_lines[:-1] |
| 542 | if text_lines: |
| 543 | # We got some content, is the first line starting with a space? |
| 544 | if text_lines[0] and text_lines[0][0].isspace(): |
| 545 | text_first_line = [] |
| 546 | else: |
| 547 | text_first_line = [text_lines.pop(0)] |
| 548 | # Calculate length of common leading whitesppace (only over content lines) |
| 549 | common_prefix = os.path.commonprefix([line for line in text_lines if line]) |
| 550 | space_prefix_len = len(common_prefix) - len(common_prefix.lstrip()) |
| 551 | # If we have a common space prefix, drop it from all lines |
| 552 | if space_prefix_len: |
| 553 | for index in xrange(len(text_lines)): |
| 554 | if text_lines[index]: |
| 555 | text_lines[index] = text_lines[index][space_prefix_len:] |
| 556 | return '\n'.join(text_first_line + text_lines) |
| 557 | return '' |
| 558 | |
| 559 | |
| 560 | def TextWrap(text, length=None, indent='', firstline_indent=None, tabs=' '): |
| 561 | """Wraps a given text to a maximum line length and returns it. |
| 562 | |
| 563 | We turn lines that only contain whitespaces into empty lines. We keep |
| 564 | new lines and tabs (e.g., we do not treat tabs as spaces). |
| 565 | |
| 566 | Args: |
| 567 | text: text to wrap |
| 568 | length: maximum length of a line, includes indentation |
| 569 | if this is None then use GetHelpWidth() |
| 570 | indent: indent for all but first line |
| 571 | firstline_indent: indent for first line; if None, fall back to indent |
| 572 | tabs: replacement for tabs |
| 573 | |
| 574 | Returns: |
| 575 | wrapped text |
| 576 | |
| 577 | Raises: |
| 578 | FlagsError: if indent not shorter than length |
| 579 | FlagsError: if firstline_indent not shorter than length |
| 580 | """ |
| 581 | # Get defaults where callee used None |
| 582 | if length is None: |
| 583 | length = GetHelpWidth() |
| 584 | if indent is None: |
| 585 | indent = '' |
| 586 | if len(indent) >= length: |
| 587 | raise FlagsError('Indent must be shorter than length') |
| 588 | # In line we will be holding the current line which is to be started |
| 589 | # with indent (or firstline_indent if available) and then appended |
| 590 | # with words. |
| 591 | if firstline_indent is None: |
| 592 | firstline_indent = '' |
| 593 | line = indent |
| 594 | else: |
| 595 | line = firstline_indent |
| 596 | if len(firstline_indent) >= length: |
| 597 | raise FlagsError('First iline indent must be shorter than length') |
| 598 | |
| 599 | # If the callee does not care about tabs we simply convert them to |
| 600 | # spaces If callee wanted tabs to be single space then we do that |
| 601 | # already here. |
| 602 | if not tabs or tabs == ' ': |
| 603 | text = text.replace('\t', ' ') |
| 604 | else: |
| 605 | tabs_are_whitespace = not tabs.strip() |
| 606 | |
| 607 | line_regex = re.compile('([ ]*)(\t*)([^ \t]+)', re.MULTILINE) |
| 608 | |
| 609 | # Split the text into lines and the lines with the regex above. The |
| 610 | # resulting lines are collected in result[]. For each split we get the |
| 611 | # spaces, the tabs and the next non white space (e.g. next word). |
| 612 | result = [] |
| 613 | for text_line in text.splitlines(): |
| 614 | # Store result length so we can find out whether processing the next |
| 615 | # line gave any new content |
| 616 | old_result_len = len(result) |
| 617 | # Process next line with line_regex. For optimization we do an rstrip(). |
| 618 | # - process tabs (changes either line or word, see below) |
| 619 | # - process word (first try to squeeze on line, then wrap or force wrap) |
| 620 | # Spaces found on the line are ignored, they get added while wrapping as |
| 621 | # needed. |
| 622 | for spaces, current_tabs, word in line_regex.findall(text_line.rstrip()): |
| 623 | # If tabs weren't converted to spaces, handle them now |
| 624 | if current_tabs: |
| 625 | # If the last thing we added was a space anyway then drop |
| 626 | # it. But let's not get rid of the indentation. |
| 627 | if (((result and line != indent) or |
| 628 | (not result and line != firstline_indent)) and line[-1] == ' '): |
| 629 | line = line[:-1] |
| 630 | # Add the tabs, if that means adding whitespace, just add it at |
| 631 | # the line, the rstrip() code while shorten the line down if |
| 632 | # necessary |
| 633 | if tabs_are_whitespace: |
| 634 | line += tabs * len(current_tabs) |
| 635 | else: |
| 636 | # if not all tab replacement is whitespace we prepend it to the word |
| 637 | word = tabs * len(current_tabs) + word |
| 638 | # Handle the case where word cannot be squeezed onto current last line |
| 639 | if len(line) + len(word) > length and len(indent) + len(word) <= length: |
| 640 | result.append(line.rstrip()) |
| 641 | line = indent + word |
| 642 | word = '' |
| 643 | # No space left on line or can we append a space? |
| 644 | if len(line) + 1 >= length: |
| 645 | result.append(line.rstrip()) |
| 646 | line = indent |
| 647 | else: |
| 648 | line += ' ' |
| 649 | # Add word and shorten it up to allowed line length. Restart next |
| 650 | # line with indent and repeat, or add a space if we're done (word |
| 651 | # finished) This deals with words that caanot fit on one line |
| 652 | # (e.g. indent + word longer than allowed line length). |
| 653 | while len(line) + len(word) >= length: |
| 654 | line += word |
| 655 | result.append(line[:length]) |
| 656 | word = line[length:] |
| 657 | line = indent |
| 658 | # Default case, simply append the word and a space |
| 659 | if word: |
| 660 | line += word + ' ' |
| 661 | # End of input line. If we have content we finish the line. If the |
| 662 | # current line is just the indent but we had content in during this |
| 663 | # original line then we need to add an emoty line. |
| 664 | if (result and line != indent) or (not result and line != firstline_indent): |
| 665 | result.append(line.rstrip()) |
| 666 | elif len(result) == old_result_len: |
| 667 | result.append('') |
| 668 | line = indent |
| 669 | |
| 670 | return '\n'.join(result) |
| 671 | |
| 672 | |
| 673 | def DocToHelp(doc): |
| 674 | """Takes a __doc__ string and reformats it as help.""" |
| 675 | |
| 676 | # Get rid of starting and ending white space. Using lstrip() or even |
| 677 | # strip() could drop more than maximum of first line and right space |
| 678 | # of last line. |
| 679 | doc = doc.strip() |
| 680 | |
| 681 | # Get rid of all empty lines |
| 682 | whitespace_only_line = re.compile('^[ \t]+$', re.M) |
| 683 | doc = whitespace_only_line.sub('', doc) |
| 684 | |
| 685 | # Cut out common space at line beginnings |
| 686 | doc = CutCommonSpacePrefix(doc) |
| 687 | |
| 688 | # Just like this module's comment, comments tend to be aligned somehow. |
| 689 | # In other words they all start with the same amount of white space |
| 690 | # 1) keep double new lines |
| 691 | # 2) keep ws after new lines if not empty line |
| 692 | # 3) all other new lines shall be changed to a space |
| 693 | # Solution: Match new lines between non white space and replace with space. |
| 694 | doc = re.sub('(?<=\S)\n(?=\S)', ' ', doc, re.M) |
| 695 | |
| 696 | return doc |
| 697 | |
| 698 | |
| 699 | def _GetModuleObjectAndName(globals_dict): |
| 700 | """Returns the module that defines a global environment, and its name. |
| 701 | |
| 702 | Args: |
| 703 | globals_dict: A dictionary that should correspond to an environment |
| 704 | providing the values of the globals. |
| 705 | |
| 706 | Returns: |
| 707 | A pair consisting of (1) module object and (2) module name (a |
| 708 | string). Returns (None, None) if the module could not be |
| 709 | identified. |
| 710 | """ |
| 711 | # The use of .items() (instead of .iteritems()) is NOT a mistake: if |
| 712 | # a parallel thread imports a module while we iterate over |
| 713 | # .iteritems() (not nice, but possible), we get a RuntimeError ... |
| 714 | # Hence, we use the slightly slower but safer .items(). |
| 715 | for name, module in sys.modules.items(): |
| 716 | if getattr(module, '__dict__', None) is globals_dict: |
| 717 | if name == '__main__': |
| 718 | # Pick a more informative name for the main module. |
| 719 | name = sys.argv[0] |
| 720 | return (module, name) |
| 721 | return (None, None) |
| 722 | |
| 723 | |
| 724 | def _GetMainModule(): |
| 725 | """Returns the name of the module from which execution started.""" |
| 726 | for depth in range(1, sys.getrecursionlimit()): |
| 727 | try: |
| 728 | globals_of_main = sys._getframe(depth).f_globals |
| 729 | except ValueError: |
| 730 | return _GetModuleObjectAndName(globals_of_main)[1] |
| 731 | raise AssertionError("No module was found") |
| 732 | |
| 733 | |
| 734 | class FlagValues: |
| 735 | """Registry of 'Flag' objects. |
| 736 | |
| 737 | A 'FlagValues' can then scan command line arguments, passing flag |
| 738 | arguments through to the 'Flag' objects that it owns. It also |
| 739 | provides easy access to the flag values. Typically only one |
| 740 | 'FlagValues' object is needed by an application: gflags.FLAGS |
| 741 | |
| 742 | This class is heavily overloaded: |
| 743 | |
| 744 | 'Flag' objects are registered via __setitem__: |
| 745 | FLAGS['longname'] = x # register a new flag |
| 746 | |
| 747 | The .value attribute of the registered 'Flag' objects can be accessed |
| 748 | as attributes of this 'FlagValues' object, through __getattr__. Both |
| 749 | the long and short name of the original 'Flag' objects can be used to |
| 750 | access its value: |
| 751 | FLAGS.longname # parsed flag value |
| 752 | FLAGS.x # parsed flag value (short name) |
| 753 | |
| 754 | Command line arguments are scanned and passed to the registered 'Flag' |
| 755 | objects through the __call__ method. Unparsed arguments, including |
| 756 | argv[0] (e.g. the program name) are returned. |
| 757 | argv = FLAGS(sys.argv) # scan command line arguments |
| 758 | |
| 759 | The original registered Flag objects can be retrieved through the use |
| 760 | of the dictionary-like operator, __getitem__: |
| 761 | x = FLAGS['longname'] # access the registered Flag object |
| 762 | |
| 763 | The str() operator of a 'FlagValues' object provides help for all of |
| 764 | the registered 'Flag' objects. |
| 765 | """ |
| 766 | |
| 767 | def __init__(self): |
| 768 | # Since everything in this class is so heavily overloaded, the only |
| 769 | # way of defining and using fields is to access __dict__ directly. |
| 770 | |
| 771 | # Dictionary: flag name (string) -> Flag object. |
| 772 | self.__dict__['__flags'] = {} |
| 773 | # Dictionary: module name (string) -> list of Flag objects that are defined |
| 774 | # by that module. |
| 775 | self.__dict__['__flags_by_module'] = {} |
| 776 | # Dictionary: module name (string) -> list of Flag objects that are |
| 777 | # key for that module. |
| 778 | self.__dict__['__key_flags_by_module'] = {} |
| 779 | |
| 780 | # Set if we should use new style gnu_getopt rather than getopt when parsing |
| 781 | # the args. Only possible with Python 2.3+ |
| 782 | self.UseGnuGetOpt(False) |
| 783 | |
| 784 | def UseGnuGetOpt(self, use_gnu_getopt=True): |
| 785 | self.__dict__['__use_gnu_getopt'] = use_gnu_getopt |
| 786 | |
| 787 | def IsGnuGetOpt(self): |
| 788 | return self.__dict__['__use_gnu_getopt'] |
| 789 | |
| 790 | def FlagDict(self): |
| 791 | return self.__dict__['__flags'] |
| 792 | |
| 793 | def FlagsByModuleDict(self): |
| 794 | """Returns the dictionary of module_name -> list of defined flags. |
| 795 | |
| 796 | Returns: |
| 797 | A dictionary. Its keys are module names (strings). Its values |
| 798 | are lists of Flag objects. |
| 799 | """ |
| 800 | return self.__dict__['__flags_by_module'] |
| 801 | |
| 802 | def KeyFlagsByModuleDict(self): |
| 803 | """Returns the dictionary of module_name -> list of key flags. |
| 804 | |
| 805 | Returns: |
| 806 | A dictionary. Its keys are module names (strings). Its values |
| 807 | are lists of Flag objects. |
| 808 | """ |
| 809 | return self.__dict__['__key_flags_by_module'] |
| 810 | |
| 811 | def _RegisterFlagByModule(self, module_name, flag): |
| 812 | """Records the module that defines a specific flag. |
| 813 | |
| 814 | We keep track of which flag is defined by which module so that we |
| 815 | can later sort the flags by module. |
| 816 | |
| 817 | Args: |
| 818 | module_name: A string, the name of a Python module. |
| 819 | flag: A Flag object, a flag that is key to the module. |
| 820 | """ |
| 821 | flags_by_module = self.FlagsByModuleDict() |
| 822 | flags_by_module.setdefault(module_name, []).append(flag) |
| 823 | |
| 824 | def _RegisterKeyFlagForModule(self, module_name, flag): |
| 825 | """Specifies that a flag is a key flag for a module. |
| 826 | |
| 827 | Args: |
| 828 | module_name: A string, the name of a Python module. |
| 829 | flag: A Flag object, a flag that is key to the module. |
| 830 | """ |
| 831 | key_flags_by_module = self.KeyFlagsByModuleDict() |
| 832 | # The list of key flags for the module named module_name. |
| 833 | key_flags = key_flags_by_module.setdefault(module_name, []) |
| 834 | # Add flag, but avoid duplicates. |
| 835 | if flag not in key_flags: |
| 836 | key_flags.append(flag) |
| 837 | |
| 838 | def _GetFlagsDefinedByModule(self, module): |
| 839 | """Returns the list of flags defined by a module. |
| 840 | |
| 841 | Args: |
| 842 | module: A module object or a module name (a string). |
| 843 | |
| 844 | Returns: |
| 845 | A new list of Flag objects. Caller may update this list as he |
| 846 | wishes: none of those changes will affect the internals of this |
| 847 | FlagValue object. |
| 848 | """ |
| 849 | if not isinstance(module, str): |
| 850 | module = module.__name__ |
| 851 | |
| 852 | return list(self.FlagsByModuleDict().get(module, [])) |
| 853 | |
| 854 | def _GetKeyFlagsForModule(self, module): |
| 855 | """Returns the list of key flags for a module. |
| 856 | |
| 857 | Args: |
| 858 | module: A module object or a module name (a string) |
| 859 | |
| 860 | Returns: |
| 861 | A new list of Flag objects. Caller may update this list as he |
| 862 | wishes: none of those changes will affect the internals of this |
| 863 | FlagValue object. |
| 864 | """ |
| 865 | if not isinstance(module, str): |
| 866 | module = module.__name__ |
| 867 | |
| 868 | # Any flag is a key flag for the module that defined it. NOTE: |
| 869 | # key_flags is a fresh list: we can update it without affecting the |
| 870 | # internals of this FlagValues object. |
| 871 | key_flags = self._GetFlagsDefinedByModule(module) |
| 872 | |
| 873 | # Take into account flags explicitly declared as key for a module. |
| 874 | for flag in self.KeyFlagsByModuleDict().get(module, []): |
| 875 | if flag not in key_flags: |
| 876 | key_flags.append(flag) |
| 877 | return key_flags |
| 878 | |
| 879 | def AppendFlagValues(self, flag_values): |
| 880 | """Appends flags registered in another FlagValues instance. |
| 881 | |
| 882 | Args: |
| 883 | flag_values: registry to copy from |
| 884 | """ |
| 885 | for flag_name, flag in flag_values.FlagDict().iteritems(): |
| 886 | # Each flags with shortname appears here twice (once under its |
| 887 | # normal name, and again with its short name). To prevent |
| 888 | # problems (DuplicateFlagError) with double flag registration, we |
| 889 | # perform a check to make sure that the entry we're looking at is |
| 890 | # for its normal name. |
| 891 | if flag_name == flag.name: |
| 892 | self[flag_name] = flag |
| 893 | |
| 894 | def RemoveFlagValues(self, flag_values): |
| 895 | """Remove flags that were previously appended from another FlagValues. |
| 896 | |
| 897 | Args: |
| 898 | flag_values: registry containing flags to remove. |
| 899 | """ |
| 900 | for flag_name in flag_values.FlagDict(): |
| 901 | self.__delattr__(flag_name) |
| 902 | |
| 903 | def __setitem__(self, name, flag): |
| 904 | """Registers a new flag variable.""" |
| 905 | fl = self.FlagDict() |
| 906 | if not isinstance(flag, Flag): |
| 907 | raise IllegalFlagValue(flag) |
| 908 | if not isinstance(name, type("")): |
| 909 | raise FlagsError("Flag name must be a string") |
| 910 | if len(name) == 0: |
| 911 | raise FlagsError("Flag name cannot be empty") |
| 912 | # If running under pychecker, duplicate keys are likely to be |
| 913 | # defined. Disable check for duplicate keys when pycheck'ing. |
| 914 | if (fl.has_key(name) and not flag.allow_override and |
| 915 | not fl[name].allow_override and not _RUNNING_PYCHECKER): |
| 916 | raise DuplicateFlagError(name, self) |
| 917 | short_name = flag.short_name |
| 918 | if short_name is not None: |
| 919 | if (fl.has_key(short_name) and not flag.allow_override and |
| 920 | not fl[short_name].allow_override and not _RUNNING_PYCHECKER): |
| 921 | raise DuplicateFlagError(short_name, self) |
| 922 | fl[short_name] = flag |
| 923 | fl[name] = flag |
| 924 | global _exported_flags |
| 925 | _exported_flags[name] = flag |
| 926 | |
| 927 | def __getitem__(self, name): |
| 928 | """Retrieves the Flag object for the flag --name.""" |
| 929 | return self.FlagDict()[name] |
| 930 | |
| 931 | def __getattr__(self, name): |
| 932 | """Retrieves the 'value' attribute of the flag --name.""" |
| 933 | fl = self.FlagDict() |
| 934 | if not fl.has_key(name): |
| 935 | raise AttributeError(name) |
| 936 | return fl[name].value |
| 937 | |
| 938 | def __setattr__(self, name, value): |
| 939 | """Sets the 'value' attribute of the flag --name.""" |
| 940 | fl = self.FlagDict() |
| 941 | fl[name].value = value |
| 942 | self._AssertValidators(fl[name].validators) |
| 943 | return value |
| 944 | |
| 945 | def _AssertAllValidators(self): |
| 946 | all_validators = set() |
| 947 | for flag in self.FlagDict().itervalues(): |
| 948 | for validator in flag.validators: |
| 949 | all_validators.add(validator) |
| 950 | self._AssertValidators(all_validators) |
| 951 | |
| 952 | def _AssertValidators(self, validators): |
| 953 | """Assert if all validators in the list are satisfied. |
| 954 | |
| 955 | Asserts validators in the order they were created. |
| 956 | Args: |
| 957 | validators: Iterable(gflags_validators.Validator), validators to be |
| 958 | verified |
| 959 | Raises: |
| 960 | AttributeError: if validators work with a non-existing flag. |
| 961 | IllegalFlagValue: if validation fails for at least one validator |
| 962 | """ |
| 963 | for validator in sorted( |
| 964 | validators, key=lambda validator: validator.insertion_index): |
| 965 | try: |
| 966 | validator.Verify(self) |
| 967 | except gflags_validators.Error, e: |
| 968 | message = validator.PrintFlagsWithValues(self) |
| 969 | raise IllegalFlagValue('%s: %s' % (message, str(e))) |
| 970 | |
| 971 | def _FlagIsRegistered(self, flag_obj): |
| 972 | """Checks whether a Flag object is registered under some name. |
| 973 | |
| 974 | Note: this is non trivial: in addition to its normal name, a flag |
| 975 | may have a short name too. In self.FlagDict(), both the normal and |
| 976 | the short name are mapped to the same flag object. E.g., calling |
| 977 | only "del FLAGS.short_name" is not unregistering the corresponding |
| 978 | Flag object (it is still registered under the longer name). |
| 979 | |
| 980 | Args: |
| 981 | flag_obj: A Flag object. |
| 982 | |
| 983 | Returns: |
| 984 | A boolean: True iff flag_obj is registered under some name. |
| 985 | """ |
| 986 | flag_dict = self.FlagDict() |
| 987 | # Check whether flag_obj is registered under its long name. |
| 988 | name = flag_obj.name |
| 989 | if flag_dict.get(name, None) == flag_obj: |
| 990 | return True |
| 991 | # Check whether flag_obj is registered under its short name. |
| 992 | short_name = flag_obj.short_name |
| 993 | if (short_name is not None and |
| 994 | flag_dict.get(short_name, None) == flag_obj): |
| 995 | return True |
| 996 | # The flag cannot be registered under any other name, so we do not |
| 997 | # need to do a full search through the values of self.FlagDict(). |
| 998 | return False |
| 999 | |
| 1000 | def __delattr__(self, flag_name): |
| 1001 | """Deletes a previously-defined flag from a flag object. |
| 1002 | |
| 1003 | This method makes sure we can delete a flag by using |
| 1004 | |
| 1005 | del flag_values_object.<flag_name> |
| 1006 | |
| 1007 | E.g., |
| 1008 | |
| 1009 | flags.DEFINE_integer('foo', 1, 'Integer flag.') |
| 1010 | del flags.FLAGS.foo |
| 1011 | |
| 1012 | Args: |
| 1013 | flag_name: A string, the name of the flag to be deleted. |
| 1014 | |
| 1015 | Raises: |
| 1016 | AttributeError: When there is no registered flag named flag_name. |
| 1017 | """ |
| 1018 | fl = self.FlagDict() |
| 1019 | if flag_name not in fl: |
| 1020 | raise AttributeError(flag_name) |
| 1021 | |
| 1022 | flag_obj = fl[flag_name] |
| 1023 | del fl[flag_name] |
| 1024 | |
| 1025 | if not self._FlagIsRegistered(flag_obj): |
| 1026 | # If the Flag object indicated by flag_name is no longer |
| 1027 | # registered (please see the docstring of _FlagIsRegistered), then |
| 1028 | # we delete the occurences of the flag object in all our internal |
| 1029 | # dictionaries. |
| 1030 | self.__RemoveFlagFromDictByModule(self.FlagsByModuleDict(), flag_obj) |
| 1031 | self.__RemoveFlagFromDictByModule(self.KeyFlagsByModuleDict(), flag_obj) |
| 1032 | |
| 1033 | def __RemoveFlagFromDictByModule(self, flags_by_module_dict, flag_obj): |
| 1034 | """Removes a flag object from a module -> list of flags dictionary. |
| 1035 | |
| 1036 | Args: |
| 1037 | flags_by_module_dict: A dictionary that maps module names to lists of |
| 1038 | flags. |
| 1039 | flag_obj: A flag object. |
| 1040 | """ |
| 1041 | for unused_module, flags_in_module in flags_by_module_dict.iteritems(): |
| 1042 | # while (as opposed to if) takes care of multiple occurences of a |
| 1043 | # flag in the list for the same module. |
| 1044 | while flag_obj in flags_in_module: |
| 1045 | flags_in_module.remove(flag_obj) |
| 1046 | |
| 1047 | def SetDefault(self, name, value): |
| 1048 | """Changes the default value of the named flag object.""" |
| 1049 | fl = self.FlagDict() |
| 1050 | if not fl.has_key(name): |
| 1051 | raise AttributeError(name) |
| 1052 | fl[name].SetDefault(value) |
| 1053 | self._AssertValidators(fl[name].validators) |
| 1054 | |
| 1055 | def __contains__(self, name): |
| 1056 | """Returns True if name is a value (flag) in the dict.""" |
| 1057 | return name in self.FlagDict() |
| 1058 | |
| 1059 | has_key = __contains__ # a synonym for __contains__() |
| 1060 | |
| 1061 | def __iter__(self): |
| 1062 | return self.FlagDict().iterkeys() |
| 1063 | |
| 1064 | def __call__(self, argv): |
| 1065 | """Parses flags from argv; stores parsed flags into this FlagValues object. |
| 1066 | |
| 1067 | All unparsed arguments are returned. Flags are parsed using the GNU |
| 1068 | Program Argument Syntax Conventions, using getopt: |
| 1069 | |
| 1070 | http://www.gnu.org/software/libc/manual/html_mono/libc.html#Getopt |
| 1071 | |
| 1072 | Args: |
| 1073 | argv: argument list. Can be of any type that may be converted to a list. |
| 1074 | |
| 1075 | Returns: |
| 1076 | The list of arguments not parsed as options, including argv[0] |
| 1077 | |
| 1078 | Raises: |
| 1079 | FlagsError: on any parsing error |
| 1080 | """ |
| 1081 | # Support any sequence type that can be converted to a list |
| 1082 | argv = list(argv) |
| 1083 | |
| 1084 | shortopts = "" |
| 1085 | longopts = [] |
| 1086 | |
| 1087 | fl = self.FlagDict() |
| 1088 | |
| 1089 | # This pre parses the argv list for --flagfile=<> options. |
| 1090 | argv = argv[:1] + self.ReadFlagsFromFiles(argv[1:], force_gnu=False) |
| 1091 | |
| 1092 | # Correct the argv to support the google style of passing boolean |
| 1093 | # parameters. Boolean parameters may be passed by using --mybool, |
| 1094 | # --nomybool, --mybool=(true|false|1|0). getopt does not support |
| 1095 | # having options that may or may not have a parameter. We replace |
| 1096 | # instances of the short form --mybool and --nomybool with their |
| 1097 | # full forms: --mybool=(true|false). |
| 1098 | original_argv = list(argv) # list() makes a copy |
| 1099 | shortest_matches = None |
| 1100 | for name, flag in fl.items(): |
| 1101 | if not flag.boolean: |
| 1102 | continue |
| 1103 | if shortest_matches is None: |
| 1104 | # Determine the smallest allowable prefix for all flag names |
| 1105 | shortest_matches = self.ShortestUniquePrefixes(fl) |
| 1106 | no_name = 'no' + name |
| 1107 | prefix = shortest_matches[name] |
| 1108 | no_prefix = shortest_matches[no_name] |
| 1109 | |
| 1110 | # Replace all occurences of this boolean with extended forms |
| 1111 | for arg_idx in range(1, len(argv)): |
| 1112 | arg = argv[arg_idx] |
| 1113 | if arg.find('=') >= 0: continue |
| 1114 | if arg.startswith('--'+prefix) and ('--'+name).startswith(arg): |
| 1115 | argv[arg_idx] = ('--%s=true' % name) |
| 1116 | elif arg.startswith('--'+no_prefix) and ('--'+no_name).startswith(arg): |
| 1117 | argv[arg_idx] = ('--%s=false' % name) |
| 1118 | |
| 1119 | # Loop over all of the flags, building up the lists of short options |
| 1120 | # and long options that will be passed to getopt. Short options are |
| 1121 | # specified as a string of letters, each letter followed by a colon |
| 1122 | # if it takes an argument. Long options are stored in an array of |
| 1123 | # strings. Each string ends with an '=' if it takes an argument. |
| 1124 | for name, flag in fl.items(): |
| 1125 | longopts.append(name + "=") |
| 1126 | if len(name) == 1: # one-letter option: allow short flag type also |
| 1127 | shortopts += name |
| 1128 | if not flag.boolean: |
| 1129 | shortopts += ":" |
| 1130 | |
| 1131 | longopts.append('undefok=') |
| 1132 | undefok_flags = [] |
| 1133 | |
| 1134 | # In case --undefok is specified, loop to pick up unrecognized |
| 1135 | # options one by one. |
| 1136 | unrecognized_opts = [] |
| 1137 | args = argv[1:] |
| 1138 | while True: |
| 1139 | try: |
| 1140 | if self.__dict__['__use_gnu_getopt']: |
| 1141 | optlist, unparsed_args = getopt.gnu_getopt(args, shortopts, longopts) |
| 1142 | else: |
| 1143 | optlist, unparsed_args = getopt.getopt(args, shortopts, longopts) |
| 1144 | break |
| 1145 | except getopt.GetoptError, e: |
| 1146 | if not e.opt or e.opt in fl: |
| 1147 | # Not an unrecognized option, reraise the exception as a FlagsError |
| 1148 | raise FlagsError(e) |
| 1149 | # Remove offender from args and try again |
| 1150 | for arg_index in range(len(args)): |
| 1151 | if ((args[arg_index] == '--' + e.opt) or |
| 1152 | (args[arg_index] == '-' + e.opt) or |
| 1153 | (args[arg_index].startswith('--' + e.opt + '='))): |
| 1154 | unrecognized_opts.append((e.opt, args[arg_index])) |
| 1155 | args = args[0:arg_index] + args[arg_index+1:] |
| 1156 | break |
| 1157 | else: |
| 1158 | # We should have found the option, so we don't expect to get |
| 1159 | # here. We could assert, but raising the original exception |
| 1160 | # might work better. |
| 1161 | raise FlagsError(e) |
| 1162 | |
| 1163 | for name, arg in optlist: |
| 1164 | if name == '--undefok': |
| 1165 | flag_names = arg.split(',') |
| 1166 | undefok_flags.extend(flag_names) |
| 1167 | # For boolean flags, if --undefok=boolflag is specified, then we should |
| 1168 | # also accept --noboolflag, in addition to --boolflag. |
| 1169 | # Since we don't know the type of the undefok'd flag, this will affect |
| 1170 | # non-boolean flags as well. |
| 1171 | # NOTE: You shouldn't use --undefok=noboolflag, because then we will |
| 1172 | # accept --nonoboolflag here. We are choosing not to do the conversion |
| 1173 | # from noboolflag -> boolflag because of the ambiguity that flag names |
| 1174 | # can start with 'no'. |
| 1175 | undefok_flags.extend('no' + name for name in flag_names) |
| 1176 | continue |
| 1177 | if name.startswith('--'): |
| 1178 | # long option |
| 1179 | name = name[2:] |
| 1180 | short_option = 0 |
| 1181 | else: |
| 1182 | # short option |
| 1183 | name = name[1:] |
| 1184 | short_option = 1 |
| 1185 | if fl.has_key(name): |
| 1186 | flag = fl[name] |
| 1187 | if flag.boolean and short_option: arg = 1 |
| 1188 | flag.Parse(arg) |
| 1189 | |
| 1190 | # If there were unrecognized options, raise an exception unless |
| 1191 | # the options were named via --undefok. |
| 1192 | for opt, value in unrecognized_opts: |
| 1193 | if opt not in undefok_flags: |
| 1194 | raise UnrecognizedFlagError(opt, value) |
| 1195 | |
| 1196 | if unparsed_args: |
| 1197 | if self.__dict__['__use_gnu_getopt']: |
| 1198 | # if using gnu_getopt just return the program name + remainder of argv. |
| 1199 | ret_val = argv[:1] + unparsed_args |
| 1200 | else: |
| 1201 | # unparsed_args becomes the first non-flag detected by getopt to |
| 1202 | # the end of argv. Because argv may have been modified above, |
| 1203 | # return original_argv for this region. |
| 1204 | ret_val = argv[:1] + original_argv[-len(unparsed_args):] |
| 1205 | else: |
| 1206 | ret_val = argv[:1] |
| 1207 | |
| 1208 | self._AssertAllValidators() |
| 1209 | return ret_val |
| 1210 | |
| 1211 | def Reset(self): |
| 1212 | """Resets the values to the point before FLAGS(argv) was called.""" |
| 1213 | for f in self.FlagDict().values(): |
| 1214 | f.Unparse() |
| 1215 | |
| 1216 | def RegisteredFlags(self): |
| 1217 | """Returns: a list of the names and short names of all registered flags.""" |
| 1218 | return self.FlagDict().keys() |
| 1219 | |
| 1220 | def FlagValuesDict(self): |
| 1221 | """Returns: a dictionary that maps flag names to flag values.""" |
| 1222 | flag_values = {} |
| 1223 | |
| 1224 | for flag_name in self.RegisteredFlags(): |
| 1225 | flag = self.FlagDict()[flag_name] |
| 1226 | flag_values[flag_name] = flag.value |
| 1227 | |
| 1228 | return flag_values |
| 1229 | |
| 1230 | def __str__(self): |
| 1231 | """Generates a help string for all known flags.""" |
| 1232 | return self.GetHelp() |
| 1233 | |
| 1234 | def GetHelp(self, prefix=''): |
| 1235 | """Generates a help string for all known flags.""" |
| 1236 | helplist = [] |
| 1237 | |
| 1238 | flags_by_module = self.FlagsByModuleDict() |
| 1239 | if flags_by_module: |
| 1240 | |
| 1241 | modules = flags_by_module.keys() |
| 1242 | modules.sort() |
| 1243 | |
| 1244 | # Print the help for the main module first, if possible. |
| 1245 | main_module = _GetMainModule() |
| 1246 | if main_module in modules: |
| 1247 | modules.remove(main_module) |
| 1248 | modules = [main_module] + modules |
| 1249 | |
| 1250 | for module in modules: |
| 1251 | self.__RenderOurModuleFlags(module, helplist) |
| 1252 | |
| 1253 | self.__RenderModuleFlags('gflags', |
| 1254 | _SPECIAL_FLAGS.FlagDict().values(), |
| 1255 | helplist) |
| 1256 | |
| 1257 | else: |
| 1258 | # Just print one long list of flags. |
| 1259 | self.__RenderFlagList( |
| 1260 | self.FlagDict().values() + _SPECIAL_FLAGS.FlagDict().values(), |
| 1261 | helplist, prefix) |
| 1262 | |
| 1263 | return '\n'.join(helplist) |
| 1264 | |
| 1265 | def __RenderModuleFlags(self, module, flags, output_lines, prefix=""): |
| 1266 | """Generates a help string for a given module.""" |
| 1267 | if not isinstance(module, str): |
| 1268 | module = module.__name__ |
| 1269 | output_lines.append('\n%s%s:' % (prefix, module)) |
| 1270 | self.__RenderFlagList(flags, output_lines, prefix + " ") |
| 1271 | |
| 1272 | def __RenderOurModuleFlags(self, module, output_lines, prefix=""): |
| 1273 | """Generates a help string for a given module.""" |
| 1274 | flags = self._GetFlagsDefinedByModule(module) |
| 1275 | if flags: |
| 1276 | self.__RenderModuleFlags(module, flags, output_lines, prefix) |
| 1277 | |
| 1278 | def __RenderOurModuleKeyFlags(self, module, output_lines, prefix=""): |
| 1279 | """Generates a help string for the key flags of a given module. |
| 1280 | |
| 1281 | Args: |
| 1282 | module: A module object or a module name (a string). |
| 1283 | output_lines: A list of strings. The generated help message |
| 1284 | lines will be appended to this list. |
| 1285 | prefix: A string that is prepended to each generated help line. |
| 1286 | """ |
| 1287 | key_flags = self._GetKeyFlagsForModule(module) |
| 1288 | if key_flags: |
| 1289 | self.__RenderModuleFlags(module, key_flags, output_lines, prefix) |
| 1290 | |
| 1291 | def ModuleHelp(self, module): |
| 1292 | """Describe the key flags of a module. |
| 1293 | |
| 1294 | Args: |
| 1295 | module: A module object or a module name (a string). |
| 1296 | |
| 1297 | Returns: |
| 1298 | string describing the key flags of a module. |
| 1299 | """ |
| 1300 | helplist = [] |
| 1301 | self.__RenderOurModuleKeyFlags(module, helplist) |
| 1302 | return '\n'.join(helplist) |
| 1303 | |
| 1304 | def MainModuleHelp(self): |
| 1305 | """Describe the key flags of the main module. |
| 1306 | |
| 1307 | Returns: |
| 1308 | string describing the key flags of a module. |
| 1309 | """ |
| 1310 | return self.ModuleHelp(_GetMainModule()) |
| 1311 | |
| 1312 | def __RenderFlagList(self, flaglist, output_lines, prefix=" "): |
| 1313 | fl = self.FlagDict() |
| 1314 | special_fl = _SPECIAL_FLAGS.FlagDict() |
| 1315 | flaglist = [(flag.name, flag) for flag in flaglist] |
| 1316 | flaglist.sort() |
| 1317 | flagset = {} |
| 1318 | for (name, flag) in flaglist: |
| 1319 | # It's possible this flag got deleted or overridden since being |
| 1320 | # registered in the per-module flaglist. Check now against the |
| 1321 | # canonical source of current flag information, the FlagDict. |
| 1322 | if fl.get(name, None) != flag and special_fl.get(name, None) != flag: |
| 1323 | # a different flag is using this name now |
| 1324 | continue |
| 1325 | # only print help once |
| 1326 | if flagset.has_key(flag): continue |
| 1327 | flagset[flag] = 1 |
| 1328 | flaghelp = "" |
| 1329 | if flag.short_name: flaghelp += "-%s," % flag.short_name |
| 1330 | if flag.boolean: |
| 1331 | flaghelp += "--[no]%s" % flag.name + ":" |
| 1332 | else: |
| 1333 | flaghelp += "--%s" % flag.name + ":" |
| 1334 | flaghelp += " " |
| 1335 | if flag.help: |
| 1336 | flaghelp += flag.help |
| 1337 | flaghelp = TextWrap(flaghelp, indent=prefix+" ", |
| 1338 | firstline_indent=prefix) |
| 1339 | if flag.default_as_str: |
| 1340 | flaghelp += "\n" |
| 1341 | flaghelp += TextWrap("(default: %s)" % flag.default_as_str, |
| 1342 | indent=prefix+" ") |
| 1343 | if flag.parser.syntactic_help: |
| 1344 | flaghelp += "\n" |
| 1345 | flaghelp += TextWrap("(%s)" % flag.parser.syntactic_help, |
| 1346 | indent=prefix+" ") |
| 1347 | output_lines.append(flaghelp) |
| 1348 | |
| 1349 | def get(self, name, default): |
| 1350 | """Returns the value of a flag (if not None) or a default value. |
| 1351 | |
| 1352 | Args: |
| 1353 | name: A string, the name of a flag. |
| 1354 | default: Default value to use if the flag value is None. |
| 1355 | """ |
| 1356 | |
| 1357 | value = self.__getattr__(name) |
| 1358 | if value is not None: # Can't do if not value, b/c value might be '0' or "" |
| 1359 | return value |
| 1360 | else: |
| 1361 | return default |
| 1362 | |
| 1363 | def ShortestUniquePrefixes(self, fl): |
| 1364 | """Returns: dictionary; maps flag names to their shortest unique prefix.""" |
| 1365 | # Sort the list of flag names |
| 1366 | sorted_flags = [] |
| 1367 | for name, flag in fl.items(): |
| 1368 | sorted_flags.append(name) |
| 1369 | if flag.boolean: |
| 1370 | sorted_flags.append('no%s' % name) |
| 1371 | sorted_flags.sort() |
| 1372 | |
| 1373 | # For each name in the sorted list, determine the shortest unique |
| 1374 | # prefix by comparing itself to the next name and to the previous |
| 1375 | # name (the latter check uses cached info from the previous loop). |
| 1376 | shortest_matches = {} |
| 1377 | prev_idx = 0 |
| 1378 | for flag_idx in range(len(sorted_flags)): |
| 1379 | curr = sorted_flags[flag_idx] |
| 1380 | if flag_idx == (len(sorted_flags) - 1): |
| 1381 | next = None |
| 1382 | else: |
| 1383 | next = sorted_flags[flag_idx+1] |
| 1384 | next_len = len(next) |
| 1385 | for curr_idx in range(len(curr)): |
| 1386 | if (next is None |
| 1387 | or curr_idx >= next_len |
| 1388 | or curr[curr_idx] != next[curr_idx]): |
| 1389 | # curr longer than next or no more chars in common |
| 1390 | shortest_matches[curr] = curr[:max(prev_idx, curr_idx) + 1] |
| 1391 | prev_idx = curr_idx |
| 1392 | break |
| 1393 | else: |
| 1394 | # curr shorter than (or equal to) next |
| 1395 | shortest_matches[curr] = curr |
| 1396 | prev_idx = curr_idx + 1 # next will need at least one more char |
| 1397 | return shortest_matches |
| 1398 | |
| 1399 | def __IsFlagFileDirective(self, flag_string): |
| 1400 | """Checks whether flag_string contain a --flagfile=<foo> directive.""" |
| 1401 | if isinstance(flag_string, type("")): |
| 1402 | if flag_string.startswith('--flagfile='): |
| 1403 | return 1 |
| 1404 | elif flag_string == '--flagfile': |
| 1405 | return 1 |
| 1406 | elif flag_string.startswith('-flagfile='): |
| 1407 | return 1 |
| 1408 | elif flag_string == '-flagfile': |
| 1409 | return 1 |
| 1410 | else: |
| 1411 | return 0 |
| 1412 | return 0 |
| 1413 | |
| 1414 | def ExtractFilename(self, flagfile_str): |
| 1415 | """Returns filename from a flagfile_str of form -[-]flagfile=filename. |
| 1416 | |
| 1417 | The cases of --flagfile foo and -flagfile foo shouldn't be hitting |
| 1418 | this function, as they are dealt with in the level above this |
| 1419 | function. |
| 1420 | """ |
| 1421 | if flagfile_str.startswith('--flagfile='): |
| 1422 | return os.path.expanduser((flagfile_str[(len('--flagfile=')):]).strip()) |
| 1423 | elif flagfile_str.startswith('-flagfile='): |
| 1424 | return os.path.expanduser((flagfile_str[(len('-flagfile=')):]).strip()) |
| 1425 | else: |
| 1426 | raise FlagsError('Hit illegal --flagfile type: %s' % flagfile_str) |
| 1427 | |
| 1428 | def __GetFlagFileLines(self, filename, parsed_file_list): |
| 1429 | """Returns the useful (!=comments, etc) lines from a file with flags. |
| 1430 | |
| 1431 | Args: |
| 1432 | filename: A string, the name of the flag file. |
| 1433 | parsed_file_list: A list of the names of the files we have |
| 1434 | already read. MUTATED BY THIS FUNCTION. |
| 1435 | |
| 1436 | Returns: |
| 1437 | List of strings. See the note below. |
| 1438 | |
| 1439 | NOTE(springer): This function checks for a nested --flagfile=<foo> |
| 1440 | tag and handles the lower file recursively. It returns a list of |
| 1441 | all the lines that _could_ contain command flags. This is |
| 1442 | EVERYTHING except whitespace lines and comments (lines starting |
| 1443 | with '#' or '//'). |
| 1444 | """ |
| 1445 | line_list = [] # All line from flagfile. |
| 1446 | flag_line_list = [] # Subset of lines w/o comments, blanks, flagfile= tags. |
| 1447 | try: |
| 1448 | file_obj = open(filename, 'r') |
| 1449 | except IOError, e_msg: |
| 1450 | print e_msg |
| 1451 | print 'ERROR:: Unable to open flagfile: %s' % (filename) |
| 1452 | return flag_line_list |
| 1453 | |
| 1454 | line_list = file_obj.readlines() |
| 1455 | file_obj.close() |
| 1456 | parsed_file_list.append(filename) |
| 1457 | |
| 1458 | # This is where we check each line in the file we just read. |
| 1459 | for line in line_list: |
| 1460 | if line.isspace(): |
| 1461 | pass |
| 1462 | # Checks for comment (a line that starts with '#'). |
| 1463 | elif line.startswith('#') or line.startswith('//'): |
| 1464 | pass |
| 1465 | # Checks for a nested "--flagfile=<bar>" flag in the current file. |
| 1466 | # If we find one, recursively parse down into that file. |
| 1467 | elif self.__IsFlagFileDirective(line): |
| 1468 | sub_filename = self.ExtractFilename(line) |
| 1469 | # We do a little safety check for reparsing a file we've already done. |
| 1470 | if not sub_filename in parsed_file_list: |
| 1471 | included_flags = self.__GetFlagFileLines(sub_filename, |
| 1472 | parsed_file_list) |
| 1473 | flag_line_list.extend(included_flags) |
| 1474 | else: # Case of hitting a circularly included file. |
| 1475 | print >>sys.stderr, ('Warning: Hit circular flagfile dependency: %s' |
| 1476 | % sub_filename) |
| 1477 | else: |
| 1478 | # Any line that's not a comment or a nested flagfile should get |
| 1479 | # copied into 2nd position. This leaves earlier arguements |
| 1480 | # further back in the list, thus giving them higher priority. |
| 1481 | flag_line_list.append(line.strip()) |
| 1482 | return flag_line_list |
| 1483 | |
| 1484 | def ReadFlagsFromFiles(self, argv, force_gnu=True): |
| 1485 | """Processes command line args, but also allow args to be read from file. |
| 1486 | Args: |
| 1487 | argv: A list of strings, usually sys.argv[1:], which may contain one or |
| 1488 | more flagfile directives of the form --flagfile="./filename". |
| 1489 | Note that the name of the program (sys.argv[0]) should be omitted. |
| 1490 | force_gnu: If False, --flagfile parsing obeys normal flag semantics. |
| 1491 | If True, --flagfile parsing instead follows gnu_getopt semantics. |
| 1492 | *** WARNING *** force_gnu=False may become the future default! |
| 1493 | |
| 1494 | Returns: |
| 1495 | |
| 1496 | A new list which has the original list combined with what we read |
| 1497 | from any flagfile(s). |
| 1498 | |
| 1499 | References: Global gflags.FLAG class instance. |
| 1500 | |
| 1501 | This function should be called before the normal FLAGS(argv) call. |
| 1502 | This function scans the input list for a flag that looks like: |
| 1503 | --flagfile=<somefile>. Then it opens <somefile>, reads all valid key |
| 1504 | and value pairs and inserts them into the input list between the |
| 1505 | first item of the list and any subsequent items in the list. |
| 1506 | |
| 1507 | Note that your application's flags are still defined the usual way |
| 1508 | using gflags DEFINE_flag() type functions. |
| 1509 | |
| 1510 | Notes (assuming we're getting a commandline of some sort as our input): |
| 1511 | --> Flags from the command line argv _should_ always take precedence! |
| 1512 | --> A further "--flagfile=<otherfile.cfg>" CAN be nested in a flagfile. |
| 1513 | It will be processed after the parent flag file is done. |
| 1514 | --> For duplicate flags, first one we hit should "win". |
| 1515 | --> In a flagfile, a line beginning with # or // is a comment. |
| 1516 | --> Entirely blank lines _should_ be ignored. |
| 1517 | """ |
| 1518 | parsed_file_list = [] |
| 1519 | rest_of_args = argv |
| 1520 | new_argv = [] |
| 1521 | while rest_of_args: |
| 1522 | current_arg = rest_of_args[0] |
| 1523 | rest_of_args = rest_of_args[1:] |
| 1524 | if self.__IsFlagFileDirective(current_arg): |
| 1525 | # This handles the case of -(-)flagfile foo. In this case the |
| 1526 | # next arg really is part of this one. |
| 1527 | if current_arg == '--flagfile' or current_arg == '-flagfile': |
| 1528 | if not rest_of_args: |
| 1529 | raise IllegalFlagValue('--flagfile with no argument') |
| 1530 | flag_filename = os.path.expanduser(rest_of_args[0]) |
| 1531 | rest_of_args = rest_of_args[1:] |
| 1532 | else: |
| 1533 | # This handles the case of (-)-flagfile=foo. |
| 1534 | flag_filename = self.ExtractFilename(current_arg) |
| 1535 | new_argv[0:0] = self.__GetFlagFileLines(flag_filename, parsed_file_list) |
| 1536 | else: |
| 1537 | new_argv.append(current_arg) |
| 1538 | # Stop parsing after '--', like getopt and gnu_getopt. |
| 1539 | if current_arg == '--': |
| 1540 | break |
| 1541 | # Stop parsing after a non-flag, like getopt. |
| 1542 | if not current_arg.startswith('-'): |
| 1543 | if not force_gnu and not self.__dict__['__use_gnu_getopt']: |
| 1544 | break |
| 1545 | |
| 1546 | if rest_of_args: |
| 1547 | new_argv.extend(rest_of_args) |
| 1548 | |
| 1549 | return new_argv |
| 1550 | |
| 1551 | def FlagsIntoString(self): |
| 1552 | """Returns a string with the flags assignments from this FlagValues object. |
| 1553 | |
| 1554 | This function ignores flags whose value is None. Each flag |
| 1555 | assignment is separated by a newline. |
| 1556 | |
| 1557 | NOTE: MUST mirror the behavior of the C++ function |
| 1558 | CommandlineFlagsIntoString from google3/base/commandlineflags.cc. |
| 1559 | """ |
| 1560 | s = '' |
| 1561 | for flag in self.FlagDict().values(): |
| 1562 | if flag.value is not None: |
| 1563 | s += flag.Serialize() + '\n' |
| 1564 | return s |
| 1565 | |
| 1566 | def AppendFlagsIntoFile(self, filename): |
| 1567 | """Appends all flags assignments from this FlagInfo object to a file. |
| 1568 | |
| 1569 | Output will be in the format of a flagfile. |
| 1570 | |
| 1571 | NOTE: MUST mirror the behavior of the C++ version of |
| 1572 | AppendFlagsIntoFile from google3/base/commandlineflags.cc. |
| 1573 | """ |
| 1574 | out_file = open(filename, 'a') |
| 1575 | out_file.write(self.FlagsIntoString()) |
| 1576 | out_file.close() |
| 1577 | |
| 1578 | def WriteHelpInXMLFormat(self, outfile=None): |
| 1579 | """Outputs flag documentation in XML format. |
| 1580 | |
| 1581 | NOTE: We use element names that are consistent with those used by |
| 1582 | the C++ command-line flag library, from |
| 1583 | google3/base/commandlineflags_reporting.cc. We also use a few new |
| 1584 | elements (e.g., <key>), but we do not interfere / overlap with |
| 1585 | existing XML elements used by the C++ library. Please maintain this |
| 1586 | consistency. |
| 1587 | |
| 1588 | Args: |
| 1589 | outfile: File object we write to. Default None means sys.stdout. |
| 1590 | """ |
| 1591 | outfile = outfile or sys.stdout |
| 1592 | |
| 1593 | outfile.write('<?xml version=\"1.0\"?>\n') |
| 1594 | outfile.write('<AllFlags>\n') |
| 1595 | indent = ' ' |
| 1596 | _WriteSimpleXMLElement(outfile, 'program', os.path.basename(sys.argv[0]), |
| 1597 | indent) |
| 1598 | |
| 1599 | usage_doc = sys.modules['__main__'].__doc__ |
| 1600 | if not usage_doc: |
| 1601 | usage_doc = '\nUSAGE: %s [flags]\n' % sys.argv[0] |
| 1602 | else: |
| 1603 | usage_doc = usage_doc.replace('%s', sys.argv[0]) |
| 1604 | _WriteSimpleXMLElement(outfile, 'usage', usage_doc, indent) |
| 1605 | |
| 1606 | # Get list of key flags for the main module. |
| 1607 | key_flags = self._GetKeyFlagsForModule(_GetMainModule()) |
| 1608 | |
| 1609 | # Sort flags by declaring module name and next by flag name. |
| 1610 | flags_by_module = self.FlagsByModuleDict() |
| 1611 | all_module_names = list(flags_by_module.keys()) |
| 1612 | all_module_names.sort() |
| 1613 | for module_name in all_module_names: |
| 1614 | flag_list = [(f.name, f) for f in flags_by_module[module_name]] |
| 1615 | flag_list.sort() |
| 1616 | for unused_flag_name, flag in flag_list: |
| 1617 | is_key = flag in key_flags |
| 1618 | flag.WriteInfoInXMLFormat(outfile, module_name, |
| 1619 | is_key=is_key, indent=indent) |
| 1620 | |
| 1621 | outfile.write('</AllFlags>\n') |
| 1622 | outfile.flush() |
| 1623 | |
| 1624 | def AddValidator(self, validator): |
| 1625 | """Register new flags validator to be checked. |
| 1626 | |
| 1627 | Args: |
| 1628 | validator: gflags_validators.Validator |
| 1629 | Raises: |
| 1630 | AttributeError: if validators work with a non-existing flag. |
| 1631 | """ |
| 1632 | for flag_name in validator.GetFlagsNames(): |
| 1633 | flag = self.FlagDict()[flag_name] |
| 1634 | flag.validators.append(validator) |
| 1635 | |
| 1636 | # end of FlagValues definition |
| 1637 | |
| 1638 | |
| 1639 | # The global FlagValues instance |
| 1640 | FLAGS = FlagValues() |
| 1641 | |
| 1642 | |
| 1643 | def _MakeXMLSafe(s): |
| 1644 | """Escapes <, >, and & from s, and removes XML 1.0-illegal chars.""" |
| 1645 | s = cgi.escape(s) # Escape <, >, and & |
| 1646 | # Remove characters that cannot appear in an XML 1.0 document |
| 1647 | # (http://www.w3.org/TR/REC-xml/#charsets). |
| 1648 | # |
| 1649 | # NOTE: if there are problems with current solution, one may move to |
| 1650 | # XML 1.1, which allows such chars, if they're entity-escaped (&#xHH;). |
| 1651 | s = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f]', '', s) |
| 1652 | return s |
| 1653 | |
| 1654 | |
| 1655 | def _WriteSimpleXMLElement(outfile, name, value, indent): |
| 1656 | """Writes a simple XML element. |
| 1657 | |
| 1658 | Args: |
| 1659 | outfile: File object we write the XML element to. |
| 1660 | name: A string, the name of XML element. |
| 1661 | value: A Python object, whose string representation will be used |
| 1662 | as the value of the XML element. |
| 1663 | indent: A string, prepended to each line of generated output. |
| 1664 | """ |
| 1665 | value_str = str(value) |
| 1666 | if isinstance(value, bool): |
| 1667 | # Display boolean values as the C++ flag library does: no caps. |
| 1668 | value_str = value_str.lower() |
| 1669 | outfile.write('%s<%s>%s</%s>\n' % |
| 1670 | (indent, name, _MakeXMLSafe(value_str), name)) |
| 1671 | |
| 1672 | |
| 1673 | class Flag: |
| 1674 | """Information about a command-line flag. |
| 1675 | |
| 1676 | 'Flag' objects define the following fields: |
| 1677 | .name - the name for this flag |
| 1678 | .default - the default value for this flag |
| 1679 | .default_as_str - default value as repr'd string, e.g., "'true'" (or None) |
| 1680 | .value - the most recent parsed value of this flag; set by Parse() |
| 1681 | .help - a help string or None if no help is available |
| 1682 | .short_name - the single letter alias for this flag (or None) |
| 1683 | .boolean - if 'true', this flag does not accept arguments |
| 1684 | .present - true if this flag was parsed from command line flags. |
| 1685 | .parser - an ArgumentParser object |
| 1686 | .serializer - an ArgumentSerializer object |
| 1687 | .allow_override - the flag may be redefined without raising an error |
| 1688 | |
| 1689 | The only public method of a 'Flag' object is Parse(), but it is |
| 1690 | typically only called by a 'FlagValues' object. The Parse() method is |
| 1691 | a thin wrapper around the 'ArgumentParser' Parse() method. The parsed |
| 1692 | value is saved in .value, and the .present attribute is updated. If |
| 1693 | this flag was already present, a FlagsError is raised. |
| 1694 | |
| 1695 | Parse() is also called during __init__ to parse the default value and |
| 1696 | initialize the .value attribute. This enables other python modules to |
| 1697 | safely use flags even if the __main__ module neglects to parse the |
| 1698 | command line arguments. The .present attribute is cleared after |
| 1699 | __init__ parsing. If the default value is set to None, then the |
| 1700 | __init__ parsing step is skipped and the .value attribute is |
| 1701 | initialized to None. |
| 1702 | |
| 1703 | Note: The default value is also presented to the user in the help |
| 1704 | string, so it is important that it be a legal value for this flag. |
| 1705 | """ |
| 1706 | |
| 1707 | def __init__(self, parser, serializer, name, default, help_string, |
| 1708 | short_name=None, boolean=0, allow_override=0): |
| 1709 | self.name = name |
| 1710 | |
| 1711 | if not help_string: |
| 1712 | help_string = '(no help available)' |
| 1713 | |
| 1714 | self.help = help_string |
| 1715 | self.short_name = short_name |
| 1716 | self.boolean = boolean |
| 1717 | self.present = 0 |
| 1718 | self.parser = parser |
| 1719 | self.serializer = serializer |
| 1720 | self.allow_override = allow_override |
| 1721 | self.value = None |
| 1722 | self.validators = [] |
| 1723 | |
| 1724 | self.SetDefault(default) |
| 1725 | |
| 1726 | def __GetParsedValueAsString(self, value): |
| 1727 | if value is None: |
| 1728 | return None |
| 1729 | if self.serializer: |
| 1730 | return repr(self.serializer.Serialize(value)) |
| 1731 | if self.boolean: |
| 1732 | if value: |
| 1733 | return repr('true') |
| 1734 | else: |
| 1735 | return repr('false') |
| 1736 | return repr(str(value)) |
| 1737 | |
| 1738 | def Parse(self, argument): |
| 1739 | try: |
| 1740 | self.value = self.parser.Parse(argument) |
| 1741 | except ValueError, e: # recast ValueError as IllegalFlagValue |
| 1742 | raise IllegalFlagValue("flag --%s=%s: %s" % (self.name, argument, e)) |
| 1743 | self.present += 1 |
| 1744 | |
| 1745 | def Unparse(self): |
| 1746 | if self.default is None: |
| 1747 | self.value = None |
| 1748 | else: |
| 1749 | self.Parse(self.default) |
| 1750 | self.present = 0 |
| 1751 | |
| 1752 | def Serialize(self): |
| 1753 | if self.value is None: |
| 1754 | return '' |
| 1755 | if self.boolean: |
| 1756 | if self.value: |
| 1757 | return "--%s" % self.name |
| 1758 | else: |
| 1759 | return "--no%s" % self.name |
| 1760 | else: |
| 1761 | if not self.serializer: |
| 1762 | raise FlagsError("Serializer not present for flag %s" % self.name) |
| 1763 | return "--%s=%s" % (self.name, self.serializer.Serialize(self.value)) |
| 1764 | |
| 1765 | def SetDefault(self, value): |
| 1766 | """Changes the default value (and current value too) for this Flag.""" |
| 1767 | # We can't allow a None override because it may end up not being |
| 1768 | # passed to C++ code when we're overriding C++ flags. So we |
| 1769 | # cowardly bail out until someone fixes the semantics of trying to |
| 1770 | # pass None to a C++ flag. See swig_flags.Init() for details on |
| 1771 | # this behavior. |
| 1772 | # TODO(olexiy): Users can directly call this method, bypassing all flags |
| 1773 | # validators (we don't have FlagValues here, so we can not check |
| 1774 | # validators). |
| 1775 | # The simplest solution I see is to make this method private. |
| 1776 | # Another approach would be to store reference to the corresponding |
| 1777 | # FlagValues with each flag, but this seems to be an overkill. |
| 1778 | if value is None and self.allow_override: |
| 1779 | raise DuplicateFlagCannotPropagateNoneToSwig(self.name) |
| 1780 | |
| 1781 | self.default = value |
| 1782 | self.Unparse() |
| 1783 | self.default_as_str = self.__GetParsedValueAsString(self.value) |
| 1784 | |
| 1785 | def Type(self): |
| 1786 | """Returns: a string that describes the type of this Flag.""" |
| 1787 | # NOTE: we use strings, and not the types.*Type constants because |
| 1788 | # our flags can have more exotic types, e.g., 'comma separated list |
| 1789 | # of strings', 'whitespace separated list of strings', etc. |
| 1790 | return self.parser.Type() |
| 1791 | |
| 1792 | def WriteInfoInXMLFormat(self, outfile, module_name, is_key=False, indent=''): |
| 1793 | """Writes common info about this flag, in XML format. |
| 1794 | |
| 1795 | This is information that is relevant to all flags (e.g., name, |
| 1796 | meaning, etc.). If you defined a flag that has some other pieces of |
| 1797 | info, then please override _WriteCustomInfoInXMLFormat. |
| 1798 | |
| 1799 | Please do NOT override this method. |
| 1800 | |
| 1801 | Args: |
| 1802 | outfile: File object we write to. |
| 1803 | module_name: A string, the name of the module that defines this flag. |
| 1804 | is_key: A boolean, True iff this flag is key for main module. |
| 1805 | indent: A string that is prepended to each generated line. |
| 1806 | """ |
| 1807 | outfile.write(indent + '<flag>\n') |
| 1808 | inner_indent = indent + ' ' |
| 1809 | if is_key: |
| 1810 | _WriteSimpleXMLElement(outfile, 'key', 'yes', inner_indent) |
| 1811 | _WriteSimpleXMLElement(outfile, 'file', module_name, inner_indent) |
| 1812 | # Print flag features that are relevant for all flags. |
| 1813 | _WriteSimpleXMLElement(outfile, 'name', self.name, inner_indent) |
| 1814 | if self.short_name: |
| 1815 | _WriteSimpleXMLElement(outfile, 'short_name', self.short_name, |
| 1816 | inner_indent) |
| 1817 | if self.help: |
| 1818 | _WriteSimpleXMLElement(outfile, 'meaning', self.help, inner_indent) |
| 1819 | # The default flag value can either be represented as a string like on the |
| 1820 | # command line, or as a Python object. We serialize this value in the |
| 1821 | # latter case in order to remain consistent. |
| 1822 | if self.serializer and not isinstance(self.default, str): |
| 1823 | default_serialized = self.serializer.Serialize(self.default) |
| 1824 | else: |
| 1825 | default_serialized = self.default |
| 1826 | _WriteSimpleXMLElement(outfile, 'default', default_serialized, inner_indent) |
| 1827 | _WriteSimpleXMLElement(outfile, 'current', self.value, inner_indent) |
| 1828 | _WriteSimpleXMLElement(outfile, 'type', self.Type(), inner_indent) |
| 1829 | # Print extra flag features this flag may have. |
| 1830 | self._WriteCustomInfoInXMLFormat(outfile, inner_indent) |
| 1831 | outfile.write(indent + '</flag>\n') |
| 1832 | |
| 1833 | def _WriteCustomInfoInXMLFormat(self, outfile, indent): |
| 1834 | """Writes extra info about this flag, in XML format. |
| 1835 | |
| 1836 | "Extra" means "not already printed by WriteInfoInXMLFormat above." |
| 1837 | |
| 1838 | Args: |
| 1839 | outfile: File object we write to. |
| 1840 | indent: A string that is prepended to each generated line. |
| 1841 | """ |
| 1842 | # Usually, the parser knows the extra details about the flag, so |
| 1843 | # we just forward the call to it. |
| 1844 | self.parser.WriteCustomInfoInXMLFormat(outfile, indent) |
| 1845 | # End of Flag definition |
| 1846 | |
| 1847 | |
| 1848 | class _ArgumentParserCache(type): |
| 1849 | """Metaclass used to cache and share argument parsers among flags.""" |
| 1850 | |
| 1851 | _instances = {} |
| 1852 | |
| 1853 | def __call__(mcs, *args, **kwargs): |
| 1854 | """Returns an instance of the argument parser cls. |
| 1855 | |
| 1856 | This method overrides behavior of the __new__ methods in |
| 1857 | all subclasses of ArgumentParser (inclusive). If an instance |
| 1858 | for mcs with the same set of arguments exists, this instance is |
| 1859 | returned, otherwise a new instance is created. |
| 1860 | |
| 1861 | If any keyword arguments are defined, or the values in args |
| 1862 | are not hashable, this method always returns a new instance of |
| 1863 | cls. |
| 1864 | |
| 1865 | Args: |
| 1866 | args: Positional initializer arguments. |
| 1867 | kwargs: Initializer keyword arguments. |
| 1868 | |
| 1869 | Returns: |
| 1870 | An instance of cls, shared or new. |
| 1871 | """ |
| 1872 | if kwargs: |
| 1873 | return type.__call__(mcs, *args, **kwargs) |
| 1874 | else: |
| 1875 | instances = mcs._instances |
| 1876 | key = (mcs,) + tuple(args) |
| 1877 | try: |
| 1878 | return instances[key] |
| 1879 | except KeyError: |
| 1880 | # No cache entry for key exists, create a new one. |
| 1881 | return instances.setdefault(key, type.__call__(mcs, *args)) |
| 1882 | except TypeError: |
| 1883 | # An object in args cannot be hashed, always return |
| 1884 | # a new instance. |
| 1885 | return type.__call__(mcs, *args) |
| 1886 | |
| 1887 | |
| 1888 | class ArgumentParser(object): |
| 1889 | """Base class used to parse and convert arguments. |
| 1890 | |
| 1891 | The Parse() method checks to make sure that the string argument is a |
| 1892 | legal value and convert it to a native type. If the value cannot be |
| 1893 | converted, it should throw a 'ValueError' exception with a human |
| 1894 | readable explanation of why the value is illegal. |
| 1895 | |
| 1896 | Subclasses should also define a syntactic_help string which may be |
| 1897 | presented to the user to describe the form of the legal values. |
| 1898 | |
| 1899 | Argument parser classes must be stateless, since instances are cached |
| 1900 | and shared between flags. Initializer arguments are allowed, but all |
| 1901 | member variables must be derived from initializer arguments only. |
| 1902 | """ |
| 1903 | __metaclass__ = _ArgumentParserCache |
| 1904 | |
| 1905 | syntactic_help = "" |
| 1906 | |
| 1907 | def Parse(self, argument): |
| 1908 | """Default implementation: always returns its argument unmodified.""" |
| 1909 | return argument |
| 1910 | |
| 1911 | def Type(self): |
| 1912 | return 'string' |
| 1913 | |
| 1914 | def WriteCustomInfoInXMLFormat(self, outfile, indent): |
| 1915 | pass |
| 1916 | |
| 1917 | |
| 1918 | class ArgumentSerializer: |
| 1919 | """Base class for generating string representations of a flag value.""" |
| 1920 | |
| 1921 | def Serialize(self, value): |
| 1922 | return str(value) |
| 1923 | |
| 1924 | |
| 1925 | class ListSerializer(ArgumentSerializer): |
| 1926 | |
| 1927 | def __init__(self, list_sep): |
| 1928 | self.list_sep = list_sep |
| 1929 | |
| 1930 | def Serialize(self, value): |
| 1931 | return self.list_sep.join([str(x) for x in value]) |
| 1932 | |
| 1933 | |
| 1934 | # Flags validators |
| 1935 | |
| 1936 | |
| 1937 | def RegisterValidator(flag_name, |
| 1938 | checker, |
| 1939 | message='Flag validation failed', |
| 1940 | flag_values=FLAGS): |
| 1941 | """Adds a constraint, which will be enforced during program execution. |
| 1942 | |
| 1943 | The constraint is validated when flags are initially parsed, and after each |
| 1944 | change of the corresponding flag's value. |
| 1945 | Args: |
| 1946 | flag_name: string, name of the flag to be checked. |
| 1947 | checker: method to validate the flag. |
| 1948 | input - value of the corresponding flag (string, boolean, etc. |
| 1949 | This value will be passed to checker by the library). See file's |
| 1950 | docstring for examples. |
| 1951 | output - Boolean. |
| 1952 | Must return True if validator constraint is satisfied. |
| 1953 | If constraint is not satisfied, it should either return False or |
| 1954 | raise gflags_validators.Error(desired_error_message). |
| 1955 | message: error text to be shown to the user if checker returns False. |
| 1956 | If checker raises gflags_validators.Error, message from the raised |
| 1957 | Error will be shown. |
| 1958 | flag_values: FlagValues |
| 1959 | Raises: |
| 1960 | AttributeError: if flag_name is not registered as a valid flag name. |
| 1961 | """ |
| 1962 | flag_values.AddValidator(gflags_validators.SimpleValidator(flag_name, |
| 1963 | checker, |
| 1964 | message)) |
| 1965 | |
| 1966 | |
| 1967 | def MarkFlagAsRequired(flag_name, flag_values=FLAGS): |
| 1968 | """Ensure that flag is not None during program execution. |
| 1969 | |
| 1970 | Registers a flag validator, which will follow usual validator |
| 1971 | rules. |
| 1972 | Args: |
| 1973 | flag_name: string, name of the flag |
| 1974 | flag_values: FlagValues |
| 1975 | Raises: |
| 1976 | AttributeError: if flag_name is not registered as a valid flag name. |
| 1977 | """ |
| 1978 | RegisterValidator(flag_name, |
| 1979 | lambda value: value is not None, |
| 1980 | message='Flag --%s must be specified.' % flag_name, |
| 1981 | flag_values=flag_values) |
| 1982 | |
| 1983 | |
| 1984 | def _RegisterBoundsValidatorIfNeeded(parser, name, flag_values): |
| 1985 | """Enforce lower and upper bounds for numeric flags. |
| 1986 | |
| 1987 | Args: |
| 1988 | parser: NumericParser (either FloatParser or IntegerParser). Provides lower |
| 1989 | and upper bounds, and help text to display. |
| 1990 | name: string, name of the flag |
| 1991 | flag_values: FlagValues |
| 1992 | """ |
| 1993 | if parser.lower_bound is not None or parser.upper_bound is not None: |
| 1994 | |
| 1995 | def Checker(value): |
| 1996 | if value is not None and parser.IsOutsideBounds(value): |
| 1997 | message = '%s is not %s' % (value, parser.syntactic_help) |
| 1998 | raise gflags_validators.Error(message) |
| 1999 | return True |
| 2000 | |
| 2001 | RegisterValidator(name, |
| 2002 | Checker, |
| 2003 | flag_values=flag_values) |
| 2004 | |
| 2005 | |
| 2006 | # The DEFINE functions are explained in mode details in the module doc string. |
| 2007 | |
| 2008 | |
| 2009 | def DEFINE(parser, name, default, help, flag_values=FLAGS, serializer=None, |
| 2010 | **args): |
| 2011 | """Registers a generic Flag object. |
| 2012 | |
| 2013 | NOTE: in the docstrings of all DEFINE* functions, "registers" is short |
| 2014 | for "creates a new flag and registers it". |
| 2015 | |
| 2016 | Auxiliary function: clients should use the specialized DEFINE_<type> |
| 2017 | function instead. |
| 2018 | |
| 2019 | Args: |
| 2020 | parser: ArgumentParser that is used to parse the flag arguments. |
| 2021 | name: A string, the flag name. |
| 2022 | default: The default value of the flag. |
| 2023 | help: A help string. |
| 2024 | flag_values: FlagValues object the flag will be registered with. |
| 2025 | serializer: ArgumentSerializer that serializes the flag value. |
| 2026 | args: Dictionary with extra keyword args that are passes to the |
| 2027 | Flag __init__. |
| 2028 | """ |
| 2029 | DEFINE_flag(Flag(parser, serializer, name, default, help, **args), |
| 2030 | flag_values) |
| 2031 | |
| 2032 | |
| 2033 | def DEFINE_flag(flag, flag_values=FLAGS): |
| 2034 | """Registers a 'Flag' object with a 'FlagValues' object. |
| 2035 | |
| 2036 | By default, the global FLAGS 'FlagValue' object is used. |
| 2037 | |
| 2038 | Typical users will use one of the more specialized DEFINE_xxx |
| 2039 | functions, such as DEFINE_string or DEFINE_integer. But developers |
| 2040 | who need to create Flag objects themselves should use this function |
| 2041 | to register their flags. |
| 2042 | """ |
| 2043 | # copying the reference to flag_values prevents pychecker warnings |
| 2044 | fv = flag_values |
| 2045 | fv[flag.name] = flag |
| 2046 | # Tell flag_values who's defining the flag. |
| 2047 | if isinstance(flag_values, FlagValues): |
| 2048 | # Regarding the above isinstance test: some users pass funny |
| 2049 | # values of flag_values (e.g., {}) in order to avoid the flag |
| 2050 | # registration (in the past, there used to be a flag_values == |
| 2051 | # FLAGS test here) and redefine flags with the same name (e.g., |
| 2052 | # debug). To avoid breaking their code, we perform the |
| 2053 | # registration only if flag_values is a real FlagValues object. |
| 2054 | flag_values._RegisterFlagByModule(_GetCallingModule(), flag) |
| 2055 | |
| 2056 | |
| 2057 | def _InternalDeclareKeyFlags(flag_names, |
| 2058 | flag_values=FLAGS, key_flag_values=None): |
| 2059 | """Declares a flag as key for the calling module. |
| 2060 | |
| 2061 | Internal function. User code should call DECLARE_key_flag or |
| 2062 | ADOPT_module_key_flags instead. |
| 2063 | |
| 2064 | Args: |
| 2065 | flag_names: A list of strings that are names of already-registered |
| 2066 | Flag objects. |
| 2067 | flag_values: A FlagValues object that the flags listed in |
| 2068 | flag_names have registered with (the value of the flag_values |
| 2069 | argument from the DEFINE_* calls that defined those flags). |
| 2070 | This should almost never need to be overridden. |
| 2071 | key_flag_values: A FlagValues object that (among possibly many |
| 2072 | other things) keeps track of the key flags for each module. |
| 2073 | Default None means "same as flag_values". This should almost |
| 2074 | never need to be overridden. |
| 2075 | |
| 2076 | Raises: |
| 2077 | UnrecognizedFlagError: when we refer to a flag that was not |
| 2078 | defined yet. |
| 2079 | """ |
| 2080 | key_flag_values = key_flag_values or flag_values |
| 2081 | |
| 2082 | module = _GetCallingModule() |
| 2083 | |
| 2084 | for flag_name in flag_names: |
| 2085 | if flag_name not in flag_values: |
| 2086 | raise UnrecognizedFlagError(flag_name) |
| 2087 | flag = flag_values.FlagDict()[flag_name] |
| 2088 | key_flag_values._RegisterKeyFlagForModule(module, flag) |
| 2089 | |
| 2090 | |
| 2091 | def DECLARE_key_flag(flag_name, flag_values=FLAGS): |
| 2092 | """Declares one flag as key to the current module. |
| 2093 | |
| 2094 | Key flags are flags that are deemed really important for a module. |
| 2095 | They are important when listing help messages; e.g., if the |
| 2096 | --helpshort command-line flag is used, then only the key flags of the |
| 2097 | main module are listed (instead of all flags, as in the case of |
| 2098 | --help). |
| 2099 | |
| 2100 | Sample usage: |
| 2101 | |
| 2102 | flags.DECLARED_key_flag('flag_1') |
| 2103 | |
| 2104 | Args: |
| 2105 | flag_name: A string, the name of an already declared flag. |
| 2106 | (Redeclaring flags as key, including flags implicitly key |
| 2107 | because they were declared in this module, is a no-op.) |
| 2108 | flag_values: A FlagValues object. This should almost never |
| 2109 | need to be overridden. |
| 2110 | """ |
| 2111 | if flag_name in _SPECIAL_FLAGS: |
| 2112 | # Take care of the special flags, e.g., --flagfile, --undefok. |
| 2113 | # These flags are defined in _SPECIAL_FLAGS, and are treated |
| 2114 | # specially during flag parsing, taking precedence over the |
| 2115 | # user-defined flags. |
| 2116 | _InternalDeclareKeyFlags([flag_name], |
| 2117 | flag_values=_SPECIAL_FLAGS, |
| 2118 | key_flag_values=flag_values) |
| 2119 | return |
| 2120 | _InternalDeclareKeyFlags([flag_name], flag_values=flag_values) |
| 2121 | |
| 2122 | |
| 2123 | def ADOPT_module_key_flags(module, flag_values=FLAGS): |
| 2124 | """Declares that all flags key to a module are key to the current module. |
| 2125 | |
| 2126 | Args: |
| 2127 | module: A module object. |
| 2128 | flag_values: A FlagValues object. This should almost never need |
| 2129 | to be overridden. |
| 2130 | |
| 2131 | Raises: |
| 2132 | FlagsError: When given an argument that is a module name (a |
| 2133 | string), instead of a module object. |
| 2134 | """ |
| 2135 | # NOTE(salcianu): an even better test would be if not |
| 2136 | # isinstance(module, types.ModuleType) but I didn't want to import |
| 2137 | # types for such a tiny use. |
| 2138 | if isinstance(module, str): |
| 2139 | raise FlagsError('Received module name %s; expected a module object.' |
| 2140 | % module) |
| 2141 | _InternalDeclareKeyFlags( |
| 2142 | [f.name for f in flag_values._GetKeyFlagsForModule(module.__name__)], |
| 2143 | flag_values=flag_values) |
| 2144 | # If module is this flag module, take _SPECIAL_FLAGS into account. |
| 2145 | if module == _GetThisModuleObjectAndName()[0]: |
| 2146 | _InternalDeclareKeyFlags( |
| 2147 | # As we associate flags with _GetCallingModule(), the special |
| 2148 | # flags defined in this module are incorrectly registered with |
| 2149 | # a different module. So, we can't use _GetKeyFlagsForModule. |
| 2150 | # Instead, we take all flags from _SPECIAL_FLAGS (a private |
| 2151 | # FlagValues, where no other module should register flags). |
| 2152 | [f.name for f in _SPECIAL_FLAGS.FlagDict().values()], |
| 2153 | flag_values=_SPECIAL_FLAGS, |
| 2154 | key_flag_values=flag_values) |
| 2155 | |
| 2156 | |
| 2157 | # |
| 2158 | # STRING FLAGS |
| 2159 | # |
| 2160 | |
| 2161 | |
| 2162 | def DEFINE_string(name, default, help, flag_values=FLAGS, **args): |
| 2163 | """Registers a flag whose value can be any string.""" |
| 2164 | parser = ArgumentParser() |
| 2165 | serializer = ArgumentSerializer() |
| 2166 | DEFINE(parser, name, default, help, flag_values, serializer, **args) |
| 2167 | |
| 2168 | |
| 2169 | # |
| 2170 | # BOOLEAN FLAGS |
| 2171 | # |
| 2172 | # and the special HELP flags. |
| 2173 | |
| 2174 | class BooleanParser(ArgumentParser): |
| 2175 | """Parser of boolean values.""" |
| 2176 | |
| 2177 | def Convert(self, argument): |
| 2178 | """Converts the argument to a boolean; raise ValueError on errors.""" |
| 2179 | if type(argument) == str: |
| 2180 | if argument.lower() in ['true', 't', '1']: |
| 2181 | return True |
| 2182 | elif argument.lower() in ['false', 'f', '0']: |
| 2183 | return False |
| 2184 | |
| 2185 | bool_argument = bool(argument) |
| 2186 | if argument == bool_argument: |
| 2187 | # The argument is a valid boolean (True, False, 0, or 1), and not just |
| 2188 | # something that always converts to bool (list, string, int, etc.). |
| 2189 | return bool_argument |
| 2190 | |
| 2191 | raise ValueError('Non-boolean argument to boolean flag', argument) |
| 2192 | |
| 2193 | def Parse(self, argument): |
| 2194 | val = self.Convert(argument) |
| 2195 | return val |
| 2196 | |
| 2197 | def Type(self): |
| 2198 | return 'bool' |
| 2199 | |
| 2200 | |
| 2201 | class BooleanFlag(Flag): |
| 2202 | """Basic boolean flag. |
| 2203 | |
| 2204 | Boolean flags do not take any arguments, and their value is either |
| 2205 | True (1) or False (0). The false value is specified on the command |
| 2206 | line by prepending the word 'no' to either the long or the short flag |
| 2207 | name. |
| 2208 | |
| 2209 | For example, if a Boolean flag was created whose long name was |
| 2210 | 'update' and whose short name was 'x', then this flag could be |
| 2211 | explicitly unset through either --noupdate or --nox. |
| 2212 | """ |
| 2213 | |
| 2214 | def __init__(self, name, default, help, short_name=None, **args): |
| 2215 | p = BooleanParser() |
| 2216 | Flag.__init__(self, p, None, name, default, help, short_name, 1, **args) |
| 2217 | if not self.help: self.help = "a boolean value" |
| 2218 | |
| 2219 | |
| 2220 | def DEFINE_boolean(name, default, help, flag_values=FLAGS, **args): |
| 2221 | """Registers a boolean flag. |
| 2222 | |
| 2223 | Such a boolean flag does not take an argument. If a user wants to |
| 2224 | specify a false value explicitly, the long option beginning with 'no' |
| 2225 | must be used: i.e. --noflag |
| 2226 | |
| 2227 | This flag will have a value of None, True or False. None is possible |
| 2228 | if default=None and the user does not specify the flag on the command |
| 2229 | line. |
| 2230 | """ |
| 2231 | DEFINE_flag(BooleanFlag(name, default, help, **args), flag_values) |
| 2232 | |
| 2233 | # Match C++ API to unconfuse C++ people. |
| 2234 | DEFINE_bool = DEFINE_boolean |
| 2235 | |
| 2236 | class HelpFlag(BooleanFlag): |
| 2237 | """ |
| 2238 | HelpFlag is a special boolean flag that prints usage information and |
| 2239 | raises a SystemExit exception if it is ever found in the command |
| 2240 | line arguments. Note this is called with allow_override=1, so other |
| 2241 | apps can define their own --help flag, replacing this one, if they want. |
| 2242 | """ |
| 2243 | def __init__(self): |
| 2244 | BooleanFlag.__init__(self, "help", 0, "show this help", |
| 2245 | short_name="?", allow_override=1) |
| 2246 | def Parse(self, arg): |
| 2247 | if arg: |
| 2248 | doc = sys.modules["__main__"].__doc__ |
| 2249 | flags = str(FLAGS) |
| 2250 | print doc or ("\nUSAGE: %s [flags]\n" % sys.argv[0]) |
| 2251 | if flags: |
| 2252 | print "flags:" |
| 2253 | print flags |
| 2254 | sys.exit(1) |
| 2255 | |
| 2256 | |
| 2257 | class HelpXMLFlag(BooleanFlag): |
| 2258 | """Similar to HelpFlag, but generates output in XML format.""" |
| 2259 | |
| 2260 | def __init__(self): |
| 2261 | BooleanFlag.__init__(self, 'helpxml', False, |
| 2262 | 'like --help, but generates XML output', |
| 2263 | allow_override=1) |
| 2264 | |
| 2265 | def Parse(self, arg): |
| 2266 | if arg: |
| 2267 | FLAGS.WriteHelpInXMLFormat(sys.stdout) |
| 2268 | sys.exit(1) |
| 2269 | |
| 2270 | |
| 2271 | class HelpshortFlag(BooleanFlag): |
| 2272 | """ |
| 2273 | HelpshortFlag is a special boolean flag that prints usage |
| 2274 | information for the "main" module, and rasies a SystemExit exception |
| 2275 | if it is ever found in the command line arguments. Note this is |
| 2276 | called with allow_override=1, so other apps can define their own |
| 2277 | --helpshort flag, replacing this one, if they want. |
| 2278 | """ |
| 2279 | def __init__(self): |
| 2280 | BooleanFlag.__init__(self, "helpshort", 0, |
| 2281 | "show usage only for this module", allow_override=1) |
| 2282 | def Parse(self, arg): |
| 2283 | if arg: |
| 2284 | doc = sys.modules["__main__"].__doc__ |
| 2285 | flags = FLAGS.MainModuleHelp() |
| 2286 | print doc or ("\nUSAGE: %s [flags]\n" % sys.argv[0]) |
| 2287 | if flags: |
| 2288 | print "flags:" |
| 2289 | print flags |
| 2290 | sys.exit(1) |
| 2291 | |
| 2292 | # |
| 2293 | # Numeric parser - base class for Integer and Float parsers |
| 2294 | # |
| 2295 | |
| 2296 | |
| 2297 | class NumericParser(ArgumentParser): |
| 2298 | """Parser of numeric values. |
| 2299 | |
| 2300 | Parsed value may be bounded to a given upper and lower bound. |
| 2301 | """ |
| 2302 | |
| 2303 | def IsOutsideBounds(self, val): |
| 2304 | return ((self.lower_bound is not None and val < self.lower_bound) or |
| 2305 | (self.upper_bound is not None and val > self.upper_bound)) |
| 2306 | |
| 2307 | def Parse(self, argument): |
| 2308 | val = self.Convert(argument) |
| 2309 | if self.IsOutsideBounds(val): |
| 2310 | raise ValueError("%s is not %s" % (val, self.syntactic_help)) |
| 2311 | return val |
| 2312 | |
| 2313 | def WriteCustomInfoInXMLFormat(self, outfile, indent): |
| 2314 | if self.lower_bound is not None: |
| 2315 | _WriteSimpleXMLElement(outfile, 'lower_bound', self.lower_bound, indent) |
| 2316 | if self.upper_bound is not None: |
| 2317 | _WriteSimpleXMLElement(outfile, 'upper_bound', self.upper_bound, indent) |
| 2318 | |
| 2319 | def Convert(self, argument): |
| 2320 | """Default implementation: always returns its argument unmodified.""" |
| 2321 | return argument |
| 2322 | |
| 2323 | # End of Numeric Parser |
| 2324 | |
| 2325 | # |
| 2326 | # FLOAT FLAGS |
| 2327 | # |
| 2328 | |
| 2329 | class FloatParser(NumericParser): |
| 2330 | """Parser of floating point values. |
| 2331 | |
| 2332 | Parsed value may be bounded to a given upper and lower bound. |
| 2333 | """ |
| 2334 | number_article = "a" |
| 2335 | number_name = "number" |
| 2336 | syntactic_help = " ".join((number_article, number_name)) |
| 2337 | |
| 2338 | def __init__(self, lower_bound=None, upper_bound=None): |
| 2339 | super(FloatParser, self).__init__() |
| 2340 | self.lower_bound = lower_bound |
| 2341 | self.upper_bound = upper_bound |
| 2342 | sh = self.syntactic_help |
| 2343 | if lower_bound is not None and upper_bound is not None: |
| 2344 | sh = ("%s in the range [%s, %s]" % (sh, lower_bound, upper_bound)) |
| 2345 | elif lower_bound == 0: |
| 2346 | sh = "a non-negative %s" % self.number_name |
| 2347 | elif upper_bound == 0: |
| 2348 | sh = "a non-positive %s" % self.number_name |
| 2349 | elif upper_bound is not None: |
| 2350 | sh = "%s <= %s" % (self.number_name, upper_bound) |
| 2351 | elif lower_bound is not None: |
| 2352 | sh = "%s >= %s" % (self.number_name, lower_bound) |
| 2353 | self.syntactic_help = sh |
| 2354 | |
| 2355 | def Convert(self, argument): |
| 2356 | """Converts argument to a float; raises ValueError on errors.""" |
| 2357 | return float(argument) |
| 2358 | |
| 2359 | def Type(self): |
| 2360 | return 'float' |
| 2361 | # End of FloatParser |
| 2362 | |
| 2363 | |
| 2364 | def DEFINE_float(name, default, help, lower_bound=None, upper_bound=None, |
| 2365 | flag_values=FLAGS, **args): |
| 2366 | """Registers a flag whose value must be a float. |
| 2367 | |
| 2368 | If lower_bound or upper_bound are set, then this flag must be |
| 2369 | within the given range. |
| 2370 | """ |
| 2371 | parser = FloatParser(lower_bound, upper_bound) |
| 2372 | serializer = ArgumentSerializer() |
| 2373 | DEFINE(parser, name, default, help, flag_values, serializer, **args) |
| 2374 | _RegisterBoundsValidatorIfNeeded(parser, name, flag_values=flag_values) |
| 2375 | |
| 2376 | # |
| 2377 | # INTEGER FLAGS |
| 2378 | # |
| 2379 | |
| 2380 | |
| 2381 | class IntegerParser(NumericParser): |
| 2382 | """Parser of an integer value. |
| 2383 | |
| 2384 | Parsed value may be bounded to a given upper and lower bound. |
| 2385 | """ |
| 2386 | number_article = "an" |
| 2387 | number_name = "integer" |
| 2388 | syntactic_help = " ".join((number_article, number_name)) |
| 2389 | |
| 2390 | def __init__(self, lower_bound=None, upper_bound=None): |
| 2391 | super(IntegerParser, self).__init__() |
| 2392 | self.lower_bound = lower_bound |
| 2393 | self.upper_bound = upper_bound |
| 2394 | sh = self.syntactic_help |
| 2395 | if lower_bound is not None and upper_bound is not None: |
| 2396 | sh = ("%s in the range [%s, %s]" % (sh, lower_bound, upper_bound)) |
| 2397 | elif lower_bound == 1: |
| 2398 | sh = "a positive %s" % self.number_name |
| 2399 | elif upper_bound == -1: |
| 2400 | sh = "a negative %s" % self.number_name |
| 2401 | elif lower_bound == 0: |
| 2402 | sh = "a non-negative %s" % self.number_name |
| 2403 | elif upper_bound == 0: |
| 2404 | sh = "a non-positive %s" % self.number_name |
| 2405 | elif upper_bound is not None: |
| 2406 | sh = "%s <= %s" % (self.number_name, upper_bound) |
| 2407 | elif lower_bound is not None: |
| 2408 | sh = "%s >= %s" % (self.number_name, lower_bound) |
| 2409 | self.syntactic_help = sh |
| 2410 | |
| 2411 | def Convert(self, argument): |
| 2412 | __pychecker__ = 'no-returnvalues' |
| 2413 | if type(argument) == str: |
| 2414 | base = 10 |
| 2415 | if len(argument) > 2 and argument[0] == "0" and argument[1] == "x": |
| 2416 | base = 16 |
| 2417 | try: |
| 2418 | return int(argument, base) |
| 2419 | # ValueError is thrown when argument is a string, and overflows an int. |
| 2420 | except ValueError: |
| 2421 | return long(argument, base) |
| 2422 | else: |
| 2423 | try: |
| 2424 | return int(argument) |
| 2425 | # OverflowError is thrown when argument is numeric, and overflows an int. |
| 2426 | except OverflowError: |
| 2427 | return long(argument) |
| 2428 | |
| 2429 | def Type(self): |
| 2430 | return 'int' |
| 2431 | |
| 2432 | |
| 2433 | def DEFINE_integer(name, default, help, lower_bound=None, upper_bound=None, |
| 2434 | flag_values=FLAGS, **args): |
| 2435 | """Registers a flag whose value must be an integer. |
| 2436 | |
| 2437 | If lower_bound, or upper_bound are set, then this flag must be |
| 2438 | within the given range. |
| 2439 | """ |
| 2440 | parser = IntegerParser(lower_bound, upper_bound) |
| 2441 | serializer = ArgumentSerializer() |
| 2442 | DEFINE(parser, name, default, help, flag_values, serializer, **args) |
| 2443 | _RegisterBoundsValidatorIfNeeded(parser, name, flag_values=flag_values) |
| 2444 | |
| 2445 | |
| 2446 | # |
| 2447 | # ENUM FLAGS |
| 2448 | # |
| 2449 | |
| 2450 | |
| 2451 | class EnumParser(ArgumentParser): |
| 2452 | """Parser of a string enum value (a string value from a given set). |
| 2453 | |
| 2454 | If enum_values (see below) is not specified, any string is allowed. |
| 2455 | """ |
| 2456 | |
| 2457 | def __init__(self, enum_values=None): |
| 2458 | super(EnumParser, self).__init__() |
| 2459 | self.enum_values = enum_values |
| 2460 | |
| 2461 | def Parse(self, argument): |
| 2462 | if self.enum_values and argument not in self.enum_values: |
| 2463 | raise ValueError("value should be one of <%s>" % |
| 2464 | "|".join(self.enum_values)) |
| 2465 | return argument |
| 2466 | |
| 2467 | def Type(self): |
| 2468 | return 'string enum' |
| 2469 | |
| 2470 | |
| 2471 | class EnumFlag(Flag): |
| 2472 | """Basic enum flag; its value can be any string from list of enum_values.""" |
| 2473 | |
| 2474 | def __init__(self, name, default, help, enum_values=None, |
| 2475 | short_name=None, **args): |
| 2476 | enum_values = enum_values or [] |
| 2477 | p = EnumParser(enum_values) |
| 2478 | g = ArgumentSerializer() |
| 2479 | Flag.__init__(self, p, g, name, default, help, short_name, **args) |
| 2480 | if not self.help: self.help = "an enum string" |
| 2481 | self.help = "<%s>: %s" % ("|".join(enum_values), self.help) |
| 2482 | |
| 2483 | def _WriteCustomInfoInXMLFormat(self, outfile, indent): |
| 2484 | for enum_value in self.parser.enum_values: |
| 2485 | _WriteSimpleXMLElement(outfile, 'enum_value', enum_value, indent) |
| 2486 | |
| 2487 | |
| 2488 | def DEFINE_enum(name, default, enum_values, help, flag_values=FLAGS, |
| 2489 | **args): |
| 2490 | """Registers a flag whose value can be any string from enum_values.""" |
| 2491 | DEFINE_flag(EnumFlag(name, default, help, enum_values, ** args), |
| 2492 | flag_values) |
| 2493 | |
| 2494 | |
| 2495 | # |
| 2496 | # LIST FLAGS |
| 2497 | # |
| 2498 | |
| 2499 | |
| 2500 | class BaseListParser(ArgumentParser): |
| 2501 | """Base class for a parser of lists of strings. |
| 2502 | |
| 2503 | To extend, inherit from this class; from the subclass __init__, call |
| 2504 | |
| 2505 | BaseListParser.__init__(self, token, name) |
| 2506 | |
| 2507 | where token is a character used to tokenize, and name is a description |
| 2508 | of the separator. |
| 2509 | """ |
| 2510 | |
| 2511 | def __init__(self, token=None, name=None): |
| 2512 | assert name |
| 2513 | super(BaseListParser, self).__init__() |
| 2514 | self._token = token |
| 2515 | self._name = name |
| 2516 | self.syntactic_help = "a %s separated list" % self._name |
| 2517 | |
| 2518 | def Parse(self, argument): |
| 2519 | if isinstance(argument, list): |
| 2520 | return argument |
| 2521 | elif argument == '': |
| 2522 | return [] |
| 2523 | else: |
| 2524 | return [s.strip() for s in argument.split(self._token)] |
| 2525 | |
| 2526 | def Type(self): |
| 2527 | return '%s separated list of strings' % self._name |
| 2528 | |
| 2529 | |
| 2530 | class ListParser(BaseListParser): |
| 2531 | """Parser for a comma-separated list of strings.""" |
| 2532 | |
| 2533 | def __init__(self): |
| 2534 | BaseListParser.__init__(self, ',', 'comma') |
| 2535 | |
| 2536 | def WriteCustomInfoInXMLFormat(self, outfile, indent): |
| 2537 | BaseListParser.WriteCustomInfoInXMLFormat(self, outfile, indent) |
| 2538 | _WriteSimpleXMLElement(outfile, 'list_separator', repr(','), indent) |
| 2539 | |
| 2540 | |
| 2541 | class WhitespaceSeparatedListParser(BaseListParser): |
| 2542 | """Parser for a whitespace-separated list of strings.""" |
| 2543 | |
| 2544 | def __init__(self): |
| 2545 | BaseListParser.__init__(self, None, 'whitespace') |
| 2546 | |
| 2547 | def WriteCustomInfoInXMLFormat(self, outfile, indent): |
| 2548 | BaseListParser.WriteCustomInfoInXMLFormat(self, outfile, indent) |
| 2549 | separators = list(string.whitespace) |
| 2550 | separators.sort() |
| 2551 | for ws_char in string.whitespace: |
| 2552 | _WriteSimpleXMLElement(outfile, 'list_separator', repr(ws_char), indent) |
| 2553 | |
| 2554 | |
| 2555 | def DEFINE_list(name, default, help, flag_values=FLAGS, **args): |
| 2556 | """Registers a flag whose value is a comma-separated list of strings.""" |
| 2557 | parser = ListParser() |
| 2558 | serializer = ListSerializer(',') |
| 2559 | DEFINE(parser, name, default, help, flag_values, serializer, **args) |
| 2560 | |
| 2561 | |
| 2562 | def DEFINE_spaceseplist(name, default, help, flag_values=FLAGS, **args): |
| 2563 | """Registers a flag whose value is a whitespace-separated list of strings. |
| 2564 | |
| 2565 | Any whitespace can be used as a separator. |
| 2566 | """ |
| 2567 | parser = WhitespaceSeparatedListParser() |
| 2568 | serializer = ListSerializer(' ') |
| 2569 | DEFINE(parser, name, default, help, flag_values, serializer, **args) |
| 2570 | |
| 2571 | |
| 2572 | # |
| 2573 | # MULTI FLAGS |
| 2574 | # |
| 2575 | |
| 2576 | |
| 2577 | class MultiFlag(Flag): |
| 2578 | """A flag that can appear multiple time on the command-line. |
| 2579 | |
| 2580 | The value of such a flag is a list that contains the individual values |
| 2581 | from all the appearances of that flag on the command-line. |
| 2582 | |
| 2583 | See the __doc__ for Flag for most behavior of this class. Only |
| 2584 | differences in behavior are described here: |
| 2585 | |
| 2586 | * The default value may be either a single value or a list of values. |
| 2587 | A single value is interpreted as the [value] singleton list. |
| 2588 | |
| 2589 | * The value of the flag is always a list, even if the option was |
| 2590 | only supplied once, and even if the default value is a single |
| 2591 | value |
| 2592 | """ |
| 2593 | |
| 2594 | def __init__(self, *args, **kwargs): |
| 2595 | Flag.__init__(self, *args, **kwargs) |
| 2596 | self.help += ';\n repeat this option to specify a list of values' |
| 2597 | |
| 2598 | def Parse(self, arguments): |
| 2599 | """Parses one or more arguments with the installed parser. |
| 2600 | |
| 2601 | Args: |
| 2602 | arguments: a single argument or a list of arguments (typically a |
| 2603 | list of default values); a single argument is converted |
| 2604 | internally into a list containing one item. |
| 2605 | """ |
| 2606 | if not isinstance(arguments, list): |
| 2607 | # Default value may be a list of values. Most other arguments |
| 2608 | # will not be, so convert them into a single-item list to make |
| 2609 | # processing simpler below. |
| 2610 | arguments = [arguments] |
| 2611 | |
| 2612 | if self.present: |
| 2613 | # keep a backup reference to list of previously supplied option values |
| 2614 | values = self.value |
| 2615 | else: |
| 2616 | # "erase" the defaults with an empty list |
| 2617 | values = [] |
| 2618 | |
| 2619 | for item in arguments: |
| 2620 | # have Flag superclass parse argument, overwriting self.value reference |
| 2621 | Flag.Parse(self, item) # also increments self.present |
| 2622 | values.append(self.value) |
| 2623 | |
| 2624 | # put list of option values back in the 'value' attribute |
| 2625 | self.value = values |
| 2626 | |
| 2627 | def Serialize(self): |
| 2628 | if not self.serializer: |
| 2629 | raise FlagsError("Serializer not present for flag %s" % self.name) |
| 2630 | if self.value is None: |
| 2631 | return '' |
| 2632 | |
| 2633 | s = '' |
| 2634 | |
| 2635 | multi_value = self.value |
| 2636 | |
| 2637 | for self.value in multi_value: |
| 2638 | if s: s += ' ' |
| 2639 | s += Flag.Serialize(self) |
| 2640 | |
| 2641 | self.value = multi_value |
| 2642 | |
| 2643 | return s |
| 2644 | |
| 2645 | def Type(self): |
| 2646 | return 'multi ' + self.parser.Type() |
| 2647 | |
| 2648 | |
| 2649 | def DEFINE_multi(parser, serializer, name, default, help, flag_values=FLAGS, |
| 2650 | **args): |
| 2651 | """Registers a generic MultiFlag that parses its args with a given parser. |
| 2652 | |
| 2653 | Auxiliary function. Normal users should NOT use it directly. |
| 2654 | |
| 2655 | Developers who need to create their own 'Parser' classes for options |
| 2656 | which can appear multiple times can call this module function to |
| 2657 | register their flags. |
| 2658 | """ |
| 2659 | DEFINE_flag(MultiFlag(parser, serializer, name, default, help, **args), |
| 2660 | flag_values) |
| 2661 | |
| 2662 | |
| 2663 | def DEFINE_multistring(name, default, help, flag_values=FLAGS, **args): |
| 2664 | """Registers a flag whose value can be a list of any strings. |
| 2665 | |
| 2666 | Use the flag on the command line multiple times to place multiple |
| 2667 | string values into the list. The 'default' may be a single string |
| 2668 | (which will be converted into a single-element list) or a list of |
| 2669 | strings. |
| 2670 | """ |
| 2671 | parser = ArgumentParser() |
| 2672 | serializer = ArgumentSerializer() |
| 2673 | DEFINE_multi(parser, serializer, name, default, help, flag_values, **args) |
| 2674 | |
| 2675 | |
| 2676 | def DEFINE_multi_int(name, default, help, lower_bound=None, upper_bound=None, |
| 2677 | flag_values=FLAGS, **args): |
| 2678 | """Registers a flag whose value can be a list of arbitrary integers. |
| 2679 | |
| 2680 | Use the flag on the command line multiple times to place multiple |
| 2681 | integer values into the list. The 'default' may be a single integer |
| 2682 | (which will be converted into a single-element list) or a list of |
| 2683 | integers. |
| 2684 | """ |
| 2685 | parser = IntegerParser(lower_bound, upper_bound) |
| 2686 | serializer = ArgumentSerializer() |
| 2687 | DEFINE_multi(parser, serializer, name, default, help, flag_values, **args) |
| 2688 | |
| 2689 | |
| 2690 | # Now register the flags that we want to exist in all applications. |
| 2691 | # These are all defined with allow_override=1, so user-apps can use |
| 2692 | # these flagnames for their own purposes, if they want. |
| 2693 | DEFINE_flag(HelpFlag()) |
| 2694 | DEFINE_flag(HelpshortFlag()) |
| 2695 | DEFINE_flag(HelpXMLFlag()) |
| 2696 | |
| 2697 | # Define special flags here so that help may be generated for them. |
| 2698 | # NOTE: Please do NOT use _SPECIAL_FLAGS from outside this module. |
| 2699 | _SPECIAL_FLAGS = FlagValues() |
| 2700 | |
| 2701 | |
| 2702 | DEFINE_string( |
| 2703 | 'flagfile', "", |
| 2704 | "Insert flag definitions from the given file into the command line.", |
| 2705 | _SPECIAL_FLAGS) |
| 2706 | |
| 2707 | DEFINE_string( |
| 2708 | 'undefok', "", |
| 2709 | "comma-separated list of flag names that it is okay to specify " |
| 2710 | "on the command line even if the program does not define a flag " |
| 2711 | "with that name. IMPORTANT: flags in this list that have " |
| 2712 | "arguments MUST use the --flag=value format.", _SPECIAL_FLAGS) |