1# Copyright 2017 The Abseil Authors. 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14 15"""This modules contains flags DEFINE functions. 16 17Do NOT import this module directly. Import the flags package and use the 18aliases defined at the package level instead. 19""" 20 21from __future__ import absolute_import 22from __future__ import division 23from __future__ import print_function 24 25import sys 26import types 27 28from absl.flags import _argument_parser 29from absl.flags import _exceptions 30from absl.flags import _flag 31from absl.flags import _flagvalues 32from absl.flags import _helpers 33from absl.flags import _validators 34 35 36_helpers.disclaim_module_ids.add(id(sys.modules[__name__])) 37 38 39def _register_bounds_validator_if_needed(parser, name, flag_values): 40 """Enforces lower and upper bounds for numeric flags. 41 42 Args: 43 parser: NumericParser (either FloatParser or IntegerParser), provides lower 44 and upper bounds, and help text to display. 45 name: str, name of the flag 46 flag_values: FlagValues. 47 """ 48 if parser.lower_bound is not None or parser.upper_bound is not None: 49 50 def checker(value): 51 if value is not None and parser.is_outside_bounds(value): 52 message = '%s is not %s' % (value, parser.syntactic_help) 53 raise _exceptions.ValidationError(message) 54 return True 55 56 _validators.register_validator(name, checker, flag_values=flag_values) 57 58 59def DEFINE(parser, name, default, help, flag_values=_flagvalues.FLAGS, # pylint: disable=redefined-builtin,invalid-name 60 serializer=None, module_name=None, **args): 61 """Registers a generic Flag object. 62 63 NOTE: in the docstrings of all DEFINE* functions, "registers" is short 64 for "creates a new flag and registers it". 65 66 Auxiliary function: clients should use the specialized DEFINE_<type> 67 function instead. 68 69 Args: 70 parser: ArgumentParser, used to parse the flag arguments. 71 name: str, the flag name. 72 default: The default value of the flag. 73 help: str, the help message. 74 flag_values: FlagValues, the FlagValues instance with which the flag will 75 be registered. This should almost never need to be overridden. 76 serializer: ArgumentSerializer, the flag serializer instance. 77 module_name: str, the name of the Python module declaring this flag. 78 If not provided, it will be computed using the stack trace of this call. 79 **args: dict, the extra keyword args that are passed to Flag __init__. 80 """ 81 DEFINE_flag(_flag.Flag(parser, serializer, name, default, help, **args), 82 flag_values, module_name) 83 84 85def DEFINE_flag(flag, flag_values=_flagvalues.FLAGS, module_name=None): # pylint: disable=invalid-name 86 """Registers a 'Flag' object with a 'FlagValues' object. 87 88 By default, the global FLAGS 'FlagValue' object is used. 89 90 Typical users will use one of the more specialized DEFINE_xxx 91 functions, such as DEFINE_string or DEFINE_integer. But developers 92 who need to create Flag objects themselves should use this function 93 to register their flags. 94 95 Args: 96 flag: Flag, a flag that is key to the module. 97 flag_values: FlagValues, the FlagValues instance with which the flag will 98 be registered. This should almost never need to be overridden. 99 module_name: str, the name of the Python module declaring this flag. 100 If not provided, it will be computed using the stack trace of this call. 101 """ 102 # Copying the reference to flag_values prevents pychecker warnings. 103 fv = flag_values 104 fv[flag.name] = flag 105 # Tell flag_values who's defining the flag. 106 if module_name: 107 module = sys.modules.get(module_name) 108 else: 109 module, module_name = _helpers.get_calling_module_object_and_name() 110 flag_values.register_flag_by_module(module_name, flag) 111 flag_values.register_flag_by_module_id(id(module), flag) 112 113 114def _internal_declare_key_flags( 115 flag_names, flag_values=_flagvalues.FLAGS, key_flag_values=None): 116 """Declares a flag as key for the calling module. 117 118 Internal function. User code should call declare_key_flag or 119 adopt_module_key_flags instead. 120 121 Args: 122 flag_names: [str], a list of strings that are names of already-registered 123 Flag objects. 124 flag_values: FlagValues, the FlagValues instance with which the flags listed 125 in flag_names have registered (the value of the flag_values 126 argument from the DEFINE_* calls that defined those flags). 127 This should almost never need to be overridden. 128 key_flag_values: FlagValues, the FlagValues instance that (among possibly 129 many other things) keeps track of the key flags for each module. 130 Default None means "same as flag_values". This should almost 131 never need to be overridden. 132 133 Raises: 134 UnrecognizedFlagError: Raised when the flag is not defined. 135 """ 136 key_flag_values = key_flag_values or flag_values 137 138 module = _helpers.get_calling_module() 139 140 for flag_name in flag_names: 141 flag = flag_values[flag_name] 142 key_flag_values.register_key_flag_for_module(module, flag) 143 144 145def declare_key_flag(flag_name, flag_values=_flagvalues.FLAGS): 146 """Declares one flag as key to the current module. 147 148 Key flags are flags that are deemed really important for a module. 149 They are important when listing help messages; e.g., if the 150 --helpshort command-line flag is used, then only the key flags of the 151 main module are listed (instead of all flags, as in the case of 152 --helpfull). 153 154 Sample usage: 155 156 flags.declare_key_flag('flag_1') 157 158 Args: 159 flag_name: str, the name of an already declared flag. 160 (Redeclaring flags as key, including flags implicitly key 161 because they were declared in this module, is a no-op.) 162 flag_values: FlagValues, the FlagValues instance in which the flag will 163 be declared as a key flag. This should almost never need to be 164 overridden. 165 166 Raises: 167 ValueError: Raised if flag_name not defined as a Python flag. 168 """ 169 if flag_name in _helpers.SPECIAL_FLAGS: 170 # Take care of the special flags, e.g., --flagfile, --undefok. 171 # These flags are defined in SPECIAL_FLAGS, and are treated 172 # specially during flag parsing, taking precedence over the 173 # user-defined flags. 174 _internal_declare_key_flags([flag_name], 175 flag_values=_helpers.SPECIAL_FLAGS, 176 key_flag_values=flag_values) 177 return 178 try: 179 _internal_declare_key_flags([flag_name], flag_values=flag_values) 180 except KeyError: 181 raise ValueError('Flag --%s is undefined. To set a flag as a key flag ' 182 'first define it in Python.' % flag_name) 183 184 185def adopt_module_key_flags(module, flag_values=_flagvalues.FLAGS): 186 """Declares that all flags key to a module are key to the current module. 187 188 Args: 189 module: module, the module object from which all key flags will be declared 190 as key flags to the current module. 191 flag_values: FlagValues, the FlagValues instance in which the flags will 192 be declared as key flags. This should almost never need to be 193 overridden. 194 195 Raises: 196 Error: Raised when given an argument that is a module name (a string), 197 instead of a module object. 198 """ 199 if not isinstance(module, types.ModuleType): 200 raise _exceptions.Error('Expected a module object, not %r.' % (module,)) 201 _internal_declare_key_flags( 202 [f.name for f in flag_values.get_key_flags_for_module(module.__name__)], 203 flag_values=flag_values) 204 # If module is this flag module, take _helpers.SPECIAL_FLAGS into account. 205 if module == _helpers.FLAGS_MODULE: 206 _internal_declare_key_flags( 207 # As we associate flags with get_calling_module_object_and_name(), the 208 # special flags defined in this module are incorrectly registered with 209 # a different module. So, we can't use get_key_flags_for_module. 210 # Instead, we take all flags from _helpers.SPECIAL_FLAGS (a private 211 # FlagValues, where no other module should register flags). 212 [_helpers.SPECIAL_FLAGS[name].name for name in _helpers.SPECIAL_FLAGS], 213 flag_values=_helpers.SPECIAL_FLAGS, 214 key_flag_values=flag_values) 215 216 217def disclaim_key_flags(): 218 """Declares that the current module will not define any more key flags. 219 220 Normally, the module that calls the DEFINE_xxx functions claims the 221 flag to be its key flag. This is undesirable for modules that 222 define additional DEFINE_yyy functions with its own flag parsers and 223 serializers, since that module will accidentally claim flags defined 224 by DEFINE_yyy as its key flags. After calling this function, the 225 module disclaims flag definitions thereafter, so the key flags will 226 be correctly attributed to the caller of DEFINE_yyy. 227 228 After calling this function, the module will not be able to define 229 any more flags. This function will affect all FlagValues objects. 230 """ 231 globals_for_caller = sys._getframe(1).f_globals # pylint: disable=protected-access 232 module, _ = _helpers.get_module_object_and_name(globals_for_caller) 233 _helpers.disclaim_module_ids.add(id(module)) 234 235 236def DEFINE_string( # pylint: disable=invalid-name,redefined-builtin 237 name, default, help, flag_values=_flagvalues.FLAGS, **args): 238 """Registers a flag whose value can be any string.""" 239 parser = _argument_parser.ArgumentParser() 240 serializer = _argument_parser.ArgumentSerializer() 241 DEFINE(parser, name, default, help, flag_values, serializer, **args) 242 243 244def DEFINE_boolean( # pylint: disable=invalid-name,redefined-builtin 245 name, default, help, flag_values=_flagvalues.FLAGS, module_name=None, 246 **args): 247 """Registers a boolean flag. 248 249 Such a boolean flag does not take an argument. If a user wants to 250 specify a false value explicitly, the long option beginning with 'no' 251 must be used: i.e. --noflag 252 253 This flag will have a value of None, True or False. None is possible 254 if default=None and the user does not specify the flag on the command 255 line. 256 257 Args: 258 name: str, the flag name. 259 default: bool|str|None, the default value of the flag. 260 help: str, the help message. 261 flag_values: FlagValues, the FlagValues instance with which the flag will 262 be registered. This should almost never need to be overridden. 263 module_name: str, the name of the Python module declaring this flag. 264 If not provided, it will be computed using the stack trace of this call. 265 **args: dict, the extra keyword args that are passed to Flag __init__. 266 """ 267 DEFINE_flag(_flag.BooleanFlag(name, default, help, **args), 268 flag_values, module_name) 269 270 271def DEFINE_float( # pylint: disable=invalid-name,redefined-builtin 272 name, default, help, lower_bound=None, upper_bound=None, 273 flag_values=_flagvalues.FLAGS, **args): # pylint: disable=invalid-name 274 """Registers a flag whose value must be a float. 275 276 If lower_bound or upper_bound are set, then this flag must be 277 within the given range. 278 279 Args: 280 name: str, the flag name. 281 default: float|str|None, the default value of the flag. 282 help: str, the help message. 283 lower_bound: float, min value of the flag. 284 upper_bound: float, max value of the flag. 285 flag_values: FlagValues, the FlagValues instance with which the flag will 286 be registered. This should almost never need to be overridden. 287 **args: dict, the extra keyword args that are passed to DEFINE. 288 """ 289 parser = _argument_parser.FloatParser(lower_bound, upper_bound) 290 serializer = _argument_parser.ArgumentSerializer() 291 DEFINE(parser, name, default, help, flag_values, serializer, **args) 292 _register_bounds_validator_if_needed(parser, name, flag_values=flag_values) 293 294 295def DEFINE_integer( # pylint: disable=invalid-name,redefined-builtin 296 name, default, help, lower_bound=None, upper_bound=None, 297 flag_values=_flagvalues.FLAGS, **args): 298 """Registers a flag whose value must be an integer. 299 300 If lower_bound, or upper_bound are set, then this flag must be 301 within the given range. 302 303 Args: 304 name: str, the flag name. 305 default: int|str|None, the default value of the flag. 306 help: str, the help message. 307 lower_bound: int, min value of the flag. 308 upper_bound: int, max value of the flag. 309 flag_values: FlagValues, the FlagValues instance with which the flag will 310 be registered. This should almost never need to be overridden. 311 **args: dict, the extra keyword args that are passed to DEFINE. 312 """ 313 parser = _argument_parser.IntegerParser(lower_bound, upper_bound) 314 serializer = _argument_parser.ArgumentSerializer() 315 DEFINE(parser, name, default, help, flag_values, serializer, **args) 316 _register_bounds_validator_if_needed(parser, name, flag_values=flag_values) 317 318 319def DEFINE_enum( # pylint: disable=invalid-name,redefined-builtin 320 name, default, enum_values, help, flag_values=_flagvalues.FLAGS, 321 module_name=None, **args): 322 """Registers a flag whose value can be any string from enum_values. 323 324 Instead of a string enum, prefer `DEFINE_enum_class`, which allows 325 defining enums from an `enum.Enum` class. 326 327 Args: 328 name: str, the flag name. 329 default: str|None, the default value of the flag. 330 enum_values: [str], a non-empty list of strings with the possible values for 331 the flag. 332 help: str, the help message. 333 flag_values: FlagValues, the FlagValues instance with which the flag will 334 be registered. This should almost never need to be overridden. 335 module_name: str, the name of the Python module declaring this flag. 336 If not provided, it will be computed using the stack trace of this call. 337 **args: dict, the extra keyword args that are passed to Flag __init__. 338 """ 339 DEFINE_flag(_flag.EnumFlag(name, default, help, enum_values, **args), 340 flag_values, module_name) 341 342 343def DEFINE_enum_class( # pylint: disable=invalid-name,redefined-builtin 344 name, default, enum_class, help, flag_values=_flagvalues.FLAGS, 345 module_name=None, **args): 346 """Registers a flag whose value can be the name of enum members. 347 348 Args: 349 name: str, the flag name. 350 default: Enum|str|None, the default value of the flag. 351 enum_class: class, the Enum class with all the possible values for the flag. 352 help: str, the help message. 353 flag_values: FlagValues, the FlagValues instance with which the flag will 354 be registered. This should almost never need to be overridden. 355 module_name: str, the name of the Python module declaring this flag. 356 If not provided, it will be computed using the stack trace of this call. 357 **args: dict, the extra keyword args that are passed to Flag __init__. 358 """ 359 DEFINE_flag(_flag.EnumClassFlag(name, default, help, enum_class, **args), 360 flag_values, module_name) 361 362 363def DEFINE_list( # pylint: disable=invalid-name,redefined-builtin 364 name, default, help, flag_values=_flagvalues.FLAGS, **args): 365 """Registers a flag whose value is a comma-separated list of strings. 366 367 The flag value is parsed with a CSV parser. 368 369 Args: 370 name: str, the flag name. 371 default: list|str|None, the default value of the flag. 372 help: str, the help message. 373 flag_values: FlagValues, the FlagValues instance with which the flag will 374 be registered. This should almost never need to be overridden. 375 **args: Dictionary with extra keyword args that are passed to the 376 Flag __init__. 377 """ 378 parser = _argument_parser.ListParser() 379 serializer = _argument_parser.CsvListSerializer(',') 380 DEFINE(parser, name, default, help, flag_values, serializer, **args) 381 382 383def DEFINE_spaceseplist( # pylint: disable=invalid-name,redefined-builtin 384 name, default, help, comma_compat=False, flag_values=_flagvalues.FLAGS, 385 **args): 386 """Registers a flag whose value is a whitespace-separated list of strings. 387 388 Any whitespace can be used as a separator. 389 390 Args: 391 name: str, the flag name. 392 default: list|str|None, the default value of the flag. 393 help: str, the help message. 394 comma_compat: bool - Whether to support comma as an additional separator. 395 If false then only whitespace is supported. This is intended only for 396 backwards compatibility with flags that used to be comma-separated. 397 flag_values: FlagValues, the FlagValues instance with which the flag will 398 be registered. This should almost never need to be overridden. 399 **args: Dictionary with extra keyword args that are passed to the 400 Flag __init__. 401 """ 402 parser = _argument_parser.WhitespaceSeparatedListParser( 403 comma_compat=comma_compat) 404 serializer = _argument_parser.ListSerializer(' ') 405 DEFINE(parser, name, default, help, flag_values, serializer, **args) 406 407 408def DEFINE_multi( # pylint: disable=invalid-name,redefined-builtin 409 parser, serializer, name, default, help, flag_values=_flagvalues.FLAGS, 410 module_name=None, **args): 411 """Registers a generic MultiFlag that parses its args with a given parser. 412 413 Auxiliary function. Normal users should NOT use it directly. 414 415 Developers who need to create their own 'Parser' classes for options 416 which can appear multiple times can call this module function to 417 register their flags. 418 419 Args: 420 parser: ArgumentParser, used to parse the flag arguments. 421 serializer: ArgumentSerializer, the flag serializer instance. 422 name: str, the flag name. 423 default: Union[Iterable[T], Text, None], the default value of the flag. 424 If the value is text, it will be parsed as if it was provided from 425 the command line. If the value is a non-string iterable, it will be 426 iterated over to create a shallow copy of the values. If it is None, 427 it is left as-is. 428 help: str, the help message. 429 flag_values: FlagValues, the FlagValues instance with which the flag will 430 be registered. This should almost never need to be overridden. 431 module_name: A string, the name of the Python module declaring this flag. 432 If not provided, it will be computed using the stack trace of this call. 433 **args: Dictionary with extra keyword args that are passed to the 434 Flag __init__. 435 """ 436 DEFINE_flag(_flag.MultiFlag(parser, serializer, name, default, help, **args), 437 flag_values, module_name) 438 439 440def DEFINE_multi_string( # pylint: disable=invalid-name,redefined-builtin 441 name, default, help, flag_values=_flagvalues.FLAGS, **args): 442 """Registers a flag whose value can be a list of any strings. 443 444 Use the flag on the command line multiple times to place multiple 445 string values into the list. The 'default' may be a single string 446 (which will be converted into a single-element list) or a list of 447 strings. 448 449 450 Args: 451 name: str, the flag name. 452 default: Union[Iterable[Text], Text, None], the default value of the flag; 453 see `DEFINE_multi`. 454 help: str, the help message. 455 flag_values: FlagValues, the FlagValues instance with which the flag will 456 be registered. This should almost never need to be overridden. 457 **args: Dictionary with extra keyword args that are passed to the 458 Flag __init__. 459 """ 460 parser = _argument_parser.ArgumentParser() 461 serializer = _argument_parser.ArgumentSerializer() 462 DEFINE_multi(parser, serializer, name, default, help, flag_values, **args) 463 464 465def DEFINE_multi_integer( # pylint: disable=invalid-name,redefined-builtin 466 name, default, help, lower_bound=None, upper_bound=None, 467 flag_values=_flagvalues.FLAGS, **args): 468 """Registers a flag whose value can be a list of arbitrary integers. 469 470 Use the flag on the command line multiple times to place multiple 471 integer values into the list. The 'default' may be a single integer 472 (which will be converted into a single-element list) or a list of 473 integers. 474 475 Args: 476 name: str, the flag name. 477 default: Union[Iterable[int], Text, None], the default value of the flag; 478 see `DEFINE_multi`. 479 help: str, the help message. 480 lower_bound: int, min values of the flag. 481 upper_bound: int, max values of the flag. 482 flag_values: FlagValues, the FlagValues instance with which the flag will 483 be registered. This should almost never need to be overridden. 484 **args: Dictionary with extra keyword args that are passed to the 485 Flag __init__. 486 """ 487 parser = _argument_parser.IntegerParser(lower_bound, upper_bound) 488 serializer = _argument_parser.ArgumentSerializer() 489 DEFINE_multi(parser, serializer, name, default, help, flag_values, **args) 490 491 492def DEFINE_multi_float( # pylint: disable=invalid-name,redefined-builtin 493 name, default, help, lower_bound=None, upper_bound=None, 494 flag_values=_flagvalues.FLAGS, **args): 495 """Registers a flag whose value can be a list of arbitrary floats. 496 497 Use the flag on the command line multiple times to place multiple 498 float values into the list. The 'default' may be a single float 499 (which will be converted into a single-element list) or a list of 500 floats. 501 502 Args: 503 name: str, the flag name. 504 default: Union[Iterable[float], Text, None], the default value of the flag; 505 see `DEFINE_multi`. 506 help: str, the help message. 507 lower_bound: float, min values of the flag. 508 upper_bound: float, max values of the flag. 509 flag_values: FlagValues, the FlagValues instance with which the flag will 510 be registered. This should almost never need to be overridden. 511 **args: Dictionary with extra keyword args that are passed to the 512 Flag __init__. 513 """ 514 parser = _argument_parser.FloatParser(lower_bound, upper_bound) 515 serializer = _argument_parser.ArgumentSerializer() 516 DEFINE_multi(parser, serializer, name, default, help, flag_values, **args) 517 518 519def DEFINE_multi_enum( # pylint: disable=invalid-name,redefined-builtin 520 name, default, enum_values, help, flag_values=_flagvalues.FLAGS, 521 case_sensitive=True, **args): 522 """Registers a flag whose value can be a list strings from enum_values. 523 524 Use the flag on the command line multiple times to place multiple 525 enum values into the list. The 'default' may be a single string 526 (which will be converted into a single-element list) or a list of 527 strings. 528 529 Args: 530 name: str, the flag name. 531 default: Union[Iterable[Text], Text, None], the default value of the flag; 532 see `DEFINE_multi`. 533 enum_values: [str], a non-empty list of strings with the possible values for 534 the flag. 535 help: str, the help message. 536 flag_values: FlagValues, the FlagValues instance with which the flag will 537 be registered. This should almost never need to be overridden. 538 case_sensitive: Whether or not the enum is to be case-sensitive. 539 **args: Dictionary with extra keyword args that are passed to the 540 Flag __init__. 541 """ 542 parser = _argument_parser.EnumParser(enum_values, case_sensitive) 543 serializer = _argument_parser.ArgumentSerializer() 544 DEFINE_multi(parser, serializer, name, default, help, flag_values, **args) 545 546 547def DEFINE_multi_enum_class( # pylint: disable=invalid-name,redefined-builtin 548 name, 549 default, 550 enum_class, 551 help, 552 flag_values=_flagvalues.FLAGS, 553 module_name=None, 554 **args): 555 """Registers a flag whose value can be a list of enum members. 556 557 Use the flag on the command line multiple times to place multiple 558 enum values into the list. 559 560 Args: 561 name: str, the flag name. 562 default: Union[Iterable[Enum], Iterable[Text], Enum, Text, None], the 563 default value of the flag; see 564 `DEFINE_multi`; only differences are documented here. If the value is 565 a single Enum, it is treated as a single-item list of that Enum value. 566 If it is an iterable, text values within the iterable will be converted 567 to the equivalent Enum objects. 568 enum_class: class, the Enum class with all the possible values for the flag. 569 help: str, the help message. 570 flag_values: FlagValues, the FlagValues instance with which the flag will be 571 registered. This should almost never need to be overridden. 572 module_name: A string, the name of the Python module declaring this flag. If 573 not provided, it will be computed using the stack trace of this call. 574 **args: Dictionary with extra keyword args that are passed to the Flag 575 __init__. 576 """ 577 DEFINE_flag( 578 _flag.MultiEnumClassFlag(name, default, help, enum_class), 579 flag_values, module_name, **args) 580 581 582def DEFINE_alias(name, original_name, flag_values=_flagvalues.FLAGS, # pylint: disable=invalid-name 583 module_name=None): 584 """Defines an alias flag for an existing one. 585 586 Args: 587 name: str, the flag name. 588 original_name: str, the original flag name. 589 flag_values: FlagValues, the FlagValues instance with which the flag will 590 be registered. This should almost never need to be overridden. 591 module_name: A string, the name of the module that defines this flag. 592 593 Raises: 594 flags.FlagError: 595 UnrecognizedFlagError: if the referenced flag doesn't exist. 596 DuplicateFlagError: if the alias name has been used by some existing flag. 597 """ 598 if original_name not in flag_values: 599 raise _exceptions.UnrecognizedFlagError(original_name) 600 flag = flag_values[original_name] 601 602 class _Parser(_argument_parser.ArgumentParser): 603 """The parser for the alias flag calls the original flag parser.""" 604 605 def parse(self, argument): 606 flag.parse(argument) 607 return flag.value 608 609 class _FlagAlias(_flag.Flag): 610 """Overrides Flag class so alias value is copy of original flag value.""" 611 612 @property 613 def value(self): 614 return flag.value 615 616 @value.setter 617 def value(self, value): 618 flag.value = value 619 620 help_msg = 'Alias for --%s.' % flag.name 621 # If alias_name has been used, flags.DuplicatedFlag will be raised. 622 DEFINE_flag(_FlagAlias(_Parser(), flag.serializer, name, flag.default, 623 help_msg, boolean=flag.boolean), 624 flag_values, module_name) 625