Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
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"""Defines the FlagValues class - registry of 'Flag' objects.
16Do NOT import this module directly. Import the flags package and use the
17aliases defined at the package level instead.
18"""
20import copy
21import logging
22import os
23import sys
24from typing import Any, Callable, Dict, Generic, Iterable, Iterator, List, Optional, Sequence, Set, TextIO, Tuple, TypeVar, Union
25from xml.dom import minidom
27from absl.flags import _exceptions
28from absl.flags import _flag
29from absl.flags import _helpers
30from absl.flags import _validators_classes
31from absl.flags._flag import Flag
33# Add flagvalues module to disclaimed module ids.
34_helpers.disclaim_module_ids.add(id(sys.modules[__name__]))
36_T = TypeVar('_T')
37_T_co = TypeVar('_T_co', covariant=True) # pytype: disable=not-supported-yet
40class FlagValues:
41 """Registry of :class:`~absl.flags.Flag` objects.
43 A :class:`FlagValues` can then scan command line arguments, passing flag
44 arguments through to the 'Flag' objects that it owns. It also
45 provides easy access to the flag values. Typically only one
46 :class:`FlagValues` object is needed by an application:
47 :const:`FLAGS`.
49 This class is heavily overloaded:
51 :class:`Flag` objects are registered via ``__setitem__``::
53 FLAGS['longname'] = x # register a new flag
55 The ``.value`` attribute of the registered :class:`~absl.flags.Flag` objects
56 can be accessed as attributes of this :class:`FlagValues` object, through
57 ``__getattr__``. Both the long and short name of the original
58 :class:`~absl.flags.Flag` objects can be used to access its value::
60 FLAGS.longname # parsed flag value
61 FLAGS.x # parsed flag value (short name)
63 Command line arguments are scanned and passed to the registered
64 :class:`~absl.flags.Flag` objects through the ``__call__`` method. Unparsed
65 arguments, including ``argv[0]`` (e.g. the program name) are returned::
67 argv = FLAGS(sys.argv) # scan command line arguments
69 The original registered :class:`~absl.flags.Flag` objects can be retrieved
70 through the use of the dictionary-like operator, ``__getitem__``::
72 x = FLAGS['longname'] # access the registered Flag object
74 The ``str()`` operator of a :class:`absl.flags.FlagValues` object provides
75 help for all of the registered :class:`~absl.flags.Flag` objects.
76 """
78 _HAS_DYNAMIC_ATTRIBUTES = True
80 # A note on collections.abc.Mapping:
81 # FlagValues defines __getitem__, __iter__, and __len__. It makes perfect
82 # sense to let it be a collections.abc.Mapping class. However, we are not
83 # able to do so. The mixin methods, e.g. keys, values, are not uncommon flag
84 # names. Those flag values would not be accessible via the FLAGS.xxx form.
86 __dict__: Dict[str, Any]
88 def __init__(self):
89 # Since everything in this class is so heavily overloaded, the only
90 # way of defining and using fields is to access __dict__ directly.
92 # Dictionary: flag name (string) -> Flag object.
93 self.__dict__['__flags'] = {}
95 # Set: name of hidden flag (string).
96 # Holds flags that should not be directly accessible from Python.
97 self.__dict__['__hiddenflags'] = set()
99 # Dictionary: module name (string) -> list of Flag objects that are defined
100 # by that module.
101 self.__dict__['__flags_by_module'] = {}
102 # Dictionary: module id (int) -> list of Flag objects that are defined by
103 # that module.
104 self.__dict__['__flags_by_module_id'] = {}
105 # Dictionary: module name (string) -> list of Flag objects that are
106 # key for that module.
107 self.__dict__['__key_flags_by_module'] = {}
109 # Bool: True if flags were parsed.
110 self.__dict__['__flags_parsed'] = False
112 # Bool: True if unparse_flags() was called.
113 self.__dict__['__unparse_flags_called'] = False
115 # None or Method(name, value) to call from __setattr__ for an unknown flag.
116 self.__dict__['__set_unknown'] = None
118 # A set of banned flag names. This is to prevent users from accidentally
119 # defining a flag that has the same name as a method on this class.
120 # Users can still allow defining the flag by passing
121 # allow_using_method_names=True in DEFINE_xxx functions.
122 self.__dict__['__banned_flag_names'] = frozenset(dir(FlagValues))
124 # Bool: Whether to use GNU style scanning.
125 self.__dict__['__use_gnu_getopt'] = True
127 # Bool: Whether use_gnu_getopt has been explicitly set by the user.
128 self.__dict__['__use_gnu_getopt_explicitly_set'] = False
130 # Function: Takes a flag name as parameter, returns a tuple
131 # (is_retired, type_is_bool).
132 self.__dict__['__is_retired_flag_func'] = None
134 def set_gnu_getopt(self, gnu_getopt: bool = True) -> None:
135 """Sets whether or not to use GNU style scanning.
137 GNU style allows mixing of flag and non-flag arguments. See
138 http://docs.python.org/library/getopt.html#getopt.gnu_getopt
140 Args:
141 gnu_getopt: bool, whether or not to use GNU style scanning.
142 """
143 self.__dict__['__use_gnu_getopt'] = gnu_getopt
144 self.__dict__['__use_gnu_getopt_explicitly_set'] = True
146 def is_gnu_getopt(self) -> bool:
147 return self.__dict__['__use_gnu_getopt']
149 def _flags(self) -> Dict[str, Flag]:
150 return self.__dict__['__flags']
152 def flags_by_module_dict(self) -> Dict[str, List[Flag]]:
153 """Returns the dictionary of module_name -> list of defined flags.
155 Returns:
156 A dictionary. Its keys are module names (strings). Its values
157 are lists of Flag objects.
158 """
159 return self.__dict__['__flags_by_module']
161 def flags_by_module_id_dict(self) -> Dict[int, List[Flag]]:
162 """Returns the dictionary of module_id -> list of defined flags.
164 Returns:
165 A dictionary. Its keys are module IDs (ints). Its values
166 are lists of Flag objects.
167 """
168 return self.__dict__['__flags_by_module_id']
170 def key_flags_by_module_dict(self) -> Dict[str, List[Flag]]:
171 """Returns the dictionary of module_name -> list of key flags.
173 Returns:
174 A dictionary. Its keys are module names (strings). Its values
175 are lists of Flag objects.
176 """
177 return self.__dict__['__key_flags_by_module']
179 def register_flag_by_module(self, module_name: str, flag: Flag) -> None:
180 """Records the module that defines a specific flag.
182 We keep track of which flag is defined by which module so that we
183 can later sort the flags by module.
185 Args:
186 module_name: str, the name of a Python module.
187 flag: Flag, the Flag instance that is key to the module.
188 """
189 flags_by_module = self.flags_by_module_dict()
190 flags_by_module.setdefault(module_name, []).append(flag)
192 def register_flag_by_module_id(self, module_id: int, flag: Flag) -> None:
193 """Records the module that defines a specific flag.
195 Args:
196 module_id: int, the ID of the Python module.
197 flag: Flag, the Flag instance that is key to the module.
198 """
199 flags_by_module_id = self.flags_by_module_id_dict()
200 flags_by_module_id.setdefault(module_id, []).append(flag)
202 def register_key_flag_for_module(self, module_name: str, flag: Flag) -> None:
203 """Specifies that a flag is a key flag for a module.
205 Args:
206 module_name: str, the name of a Python module.
207 flag: Flag, the Flag instance that is key to the module.
208 """
209 key_flags_by_module = self.key_flags_by_module_dict()
210 # The list of key flags for the module named module_name.
211 key_flags = key_flags_by_module.setdefault(module_name, [])
212 # Add flag, but avoid duplicates.
213 if flag not in key_flags:
214 key_flags.append(flag)
216 def _flag_is_registered(self, flag_obj: Flag) -> bool:
217 """Checks whether a Flag object is registered under long name or short name.
219 Args:
220 flag_obj: Flag, the Flag instance to check for.
222 Returns:
223 bool, True iff flag_obj is registered under long name or short name.
224 """
225 flag_dict = self._flags()
226 # Check whether flag_obj is registered under its long name.
227 name = flag_obj.name
228 if name in flag_dict and flag_dict[name] == flag_obj:
229 return True
230 # Check whether flag_obj is registered under its short name.
231 short_name = flag_obj.short_name
232 if (
233 short_name is not None
234 and short_name in flag_dict
235 and flag_dict[short_name] == flag_obj
236 ):
237 return True
238 return False
240 def _cleanup_unregistered_flag_from_module_dicts(
241 self, flag_obj: Flag
242 ) -> None:
243 """Cleans up unregistered flags from all module -> [flags] dictionaries.
245 If flag_obj is registered under either its long name or short name, it
246 won't be removed from the dictionaries.
248 Args:
249 flag_obj: Flag, the Flag instance to clean up for.
250 """
251 if self._flag_is_registered(flag_obj):
252 return
253 # Materialize dict values to list to avoid concurrent modification.
254 for flags_in_module in [
255 *self.flags_by_module_dict().values(),
256 *self.flags_by_module_id_dict().values(),
257 *self.key_flags_by_module_dict().values(),
258 ]:
259 # While (as opposed to if) takes care of multiple occurrences of a
260 # flag in the list for the same module.
261 while flag_obj in flags_in_module:
262 flags_in_module.remove(flag_obj)
264 def get_flags_for_module(self, module: Union[str, Any]) -> List[Flag]:
265 """Returns the list of flags defined by a module.
267 Args:
268 module: module|str, the module to get flags from.
270 Returns:
271 [Flag], a new list of Flag instances. Caller may update this list as
272 desired: none of those changes will affect the internals of this
273 FlagValue instance.
274 """
275 if not isinstance(module, str):
276 module = module.__name__
277 if module == '__main__':
278 module = sys.argv[0]
280 return list(self.flags_by_module_dict().get(module, []))
282 def get_key_flags_for_module(self, module: Union[str, Any]) -> List[Flag]:
283 """Returns the list of key flags for a module.
285 Args:
286 module: module|str, the module to get key flags from.
288 Returns:
289 [Flag], a new list of Flag instances. Caller may update this list as
290 desired: none of those changes will affect the internals of this
291 FlagValue instance.
292 """
293 if not isinstance(module, str):
294 module = module.__name__
295 if module == '__main__':
296 module = sys.argv[0]
298 # Any flag is a key flag for the module that defined it. NOTE:
299 # key_flags is a fresh list: we can update it without affecting the
300 # internals of this FlagValues object.
301 key_flags = self.get_flags_for_module(module)
303 # Take into account flags explicitly declared as key for a module.
304 for flag in self.key_flags_by_module_dict().get(module, []):
305 if flag not in key_flags:
306 key_flags.append(flag)
307 return key_flags
309 # TODO(yileiyang): Restrict default to Optional[str].
310 def find_module_defining_flag(
311 self, flagname: str, default: Optional[_T] = None
312 ) -> Union[str, Optional[_T]]:
313 """Return the name of the module defining this flag, or default.
315 Args:
316 flagname: str, name of the flag to lookup.
317 default: Value to return if flagname is not defined. Defaults to None.
319 Returns:
320 The name of the module which registered the flag with this name.
321 If no such module exists (i.e. no flag with this name exists),
322 we return default.
323 """
324 registered_flag = self._flags().get(flagname)
325 if registered_flag is None:
326 return default
327 for module, flags in self.flags_by_module_dict().items():
328 for flag in flags:
329 # It must compare the flag with the one in _flags. This is because a
330 # flag might be overridden only for its long name (or short name),
331 # and only its short name (or long name) is considered registered.
332 if (flag.name == registered_flag.name and
333 flag.short_name == registered_flag.short_name):
334 return module
335 return default
337 # TODO(yileiyang): Restrict default to Optional[str].
338 def find_module_id_defining_flag(
339 self, flagname: str, default: Optional[_T] = None
340 ) -> Union[int, Optional[_T]]:
341 """Return the ID of the module defining this flag, or default.
343 Args:
344 flagname: str, name of the flag to lookup.
345 default: Value to return if flagname is not defined. Defaults to None.
347 Returns:
348 The ID of the module which registered the flag with this name.
349 If no such module exists (i.e. no flag with this name exists),
350 we return default.
351 """
352 registered_flag = self._flags().get(flagname)
353 if registered_flag is None:
354 return default
355 for module_id, flags in self.flags_by_module_id_dict().items():
356 for flag in flags:
357 # It must compare the flag with the one in _flags. This is because a
358 # flag might be overridden only for its long name (or short name),
359 # and only its short name (or long name) is considered registered.
360 if (flag.name == registered_flag.name and
361 flag.short_name == registered_flag.short_name):
362 return module_id
363 return default
365 def _register_unknown_flag_setter(
366 self, setter: Callable[[str, Any], None]
367 ) -> None:
368 """Allow set default values for undefined flags.
370 Args:
371 setter: Method(name, value) to call to __setattr__ an unknown flag. Must
372 raise NameError or ValueError for invalid name/value.
373 """
374 self.__dict__['__set_unknown'] = setter
376 def _set_unknown_flag(self, name: str, value: _T) -> _T:
377 """Returns value if setting flag |name| to |value| returned True.
379 Args:
380 name: str, name of the flag to set.
381 value: Value to set.
383 Returns:
384 Flag value on successful call.
386 Raises:
387 UnrecognizedFlagError
388 IllegalFlagValueError
389 """
390 setter = self.__dict__['__set_unknown']
391 if setter:
392 try:
393 setter(name, value)
394 return value
395 except (TypeError, ValueError): # Flag value is not valid.
396 raise _exceptions.IllegalFlagValueError(
397 f'"{value}" is not valid for --{name}'
398 )
399 except NameError: # Flag name is not valid.
400 pass
401 raise _exceptions.UnrecognizedFlagError(name, value)
403 def append_flag_values(self, flag_values: 'FlagValues') -> None:
404 """Appends flags registered in another FlagValues instance.
406 Args:
407 flag_values: FlagValues, the FlagValues instance from which to copy flags.
408 """
409 for flag_name, flag in flag_values._flags().items(): # pylint: disable=protected-access
410 # Each flags with short_name appears here twice (once under its
411 # normal name, and again with its short name). To prevent
412 # problems (DuplicateFlagError) with double flag registration, we
413 # perform a check to make sure that the entry we're looking at is
414 # for its normal name.
415 if flag_name == flag.name:
416 try:
417 self[flag_name] = flag
418 except _exceptions.DuplicateFlagError:
419 raise _exceptions.DuplicateFlagError.from_flag(
420 flag_name, self, other_flag_values=flag_values)
422 def remove_flag_values(
423 self, flag_values: 'Union[FlagValues, Iterable[str]]'
424 ) -> None:
425 """Remove flags that were previously appended from another FlagValues.
427 Args:
428 flag_values: FlagValues, the FlagValues instance containing flags to
429 remove.
430 """
431 for flag_name in flag_values:
432 self.__delattr__(flag_name)
434 def __setitem__(self, name: str, flag: Flag) -> None:
435 """Registers a new flag variable."""
436 fl = self._flags()
437 if not isinstance(flag, _flag.Flag):
438 raise _exceptions.IllegalFlagValueError(
439 f'Expect Flag instances, found type {type(flag)}. '
440 "Maybe you didn't mean to use FlagValue.__setitem__?")
441 if not isinstance(name, str):
442 raise _exceptions.Error('Flag name must be a string')
443 if not name:
444 raise _exceptions.Error('Flag name cannot be empty')
445 if ' ' in name:
446 raise _exceptions.Error('Flag name cannot contain a space')
447 self._check_method_name_conflicts(name, flag)
448 if name in fl and not flag.allow_override and not fl[name].allow_override:
449 module, module_name = _helpers.get_calling_module_object_and_name()
450 if (self.find_module_defining_flag(name) == module_name and
451 id(module) != self.find_module_id_defining_flag(name)):
452 # If the flag has already been defined by a module with the same name,
453 # but a different ID, we can stop here because it indicates that the
454 # module is simply being imported a subsequent time.
455 return
456 raise _exceptions.DuplicateFlagError.from_flag(name, self)
457 # If a new flag overrides an old one, we need to cleanup the old flag's
458 # modules if it's not registered.
459 flags_to_cleanup = set()
460 short_name: Optional[str] = flag.short_name
461 if short_name is not None:
462 if (short_name in fl and not flag.allow_override and
463 not fl[short_name].allow_override):
464 raise _exceptions.DuplicateFlagError.from_flag(short_name, self)
465 if short_name in fl and fl[short_name] != flag:
466 flags_to_cleanup.add(fl[short_name])
467 fl[short_name] = flag
468 if (name not in fl # new flag
469 or fl[name].using_default_value or not flag.using_default_value):
470 if name in fl and fl[name] != flag:
471 flags_to_cleanup.add(fl[name])
472 fl[name] = flag
473 for f in flags_to_cleanup:
474 self._cleanup_unregistered_flag_from_module_dicts(f)
476 def __dir__(self) -> List[str]:
477 """Returns list of names of all defined flags.
479 Useful for TAB-completion in ipython.
481 Returns:
482 [str], a list of names of all defined flags.
483 """
484 return sorted(self._flags())
486 def __getitem__(self, name: str) -> Flag:
487 """Returns the Flag object for the flag --name."""
488 return self._flags()[name]
490 def _hide_flag(self, name):
491 """Marks the flag --name as hidden."""
492 self.__dict__['__hiddenflags'].add(name)
494 def __getattr__(self, name: str) -> Any:
495 """Retrieves the 'value' attribute of the flag --name."""
496 flag_entry = self._flags().get(name)
497 if flag_entry is None:
498 raise AttributeError(name)
499 if name in self.__dict__['__hiddenflags']:
500 raise AttributeError(name)
502 if self.__dict__['__flags_parsed'] or flag_entry.present:
503 return flag_entry.value
504 else:
505 raise _exceptions.UnparsedFlagAccessError(
506 'Trying to access flag --%s before flags were parsed.' % name)
508 def __setattr__(self, name: str, value: _T) -> _T:
509 """Sets the 'value' attribute of the flag --name."""
510 self._set_attributes(**{name: value})
511 return value
513 def _set_attributes(self, **attributes: Any) -> None:
514 """Sets multiple flag values together, triggers validators afterwards."""
515 fl = self._flags()
516 known_flag_vals = {}
517 known_flag_used_defaults = {}
518 try:
519 for name, value in attributes.items():
520 if name in self.__dict__['__hiddenflags']:
521 raise AttributeError(name)
522 flag_entry = fl.get(name)
523 if flag_entry is not None:
524 orig = flag_entry.value
525 flag_entry.value = value
526 known_flag_vals[name] = orig
527 else:
528 self._set_unknown_flag(name, value)
529 for name in known_flag_vals:
530 self._assert_validators(fl[name].validators)
531 known_flag_used_defaults[name] = fl[name].using_default_value
532 fl[name].using_default_value = False
533 except:
534 for name, orig in known_flag_vals.items():
535 fl[name].value = orig
536 for name, orig in known_flag_used_defaults.items():
537 fl[name].using_default_value = orig
538 # NOTE: We do not attempt to undo unknown flag side effects because we
539 # cannot reliably undo the user-configured behavior.
540 raise
542 def validate_all_flags(self) -> None:
543 """Verifies whether all flags pass validation.
545 Raises:
546 AttributeError: Raised if validators work with a non-existing flag.
547 IllegalFlagValueError: Raised if validation fails for at least one
548 validator.
549 """
550 all_validators = set()
551 for flag in self._flags().values():
552 all_validators.update(flag.validators)
553 self._assert_validators(all_validators)
555 def _assert_validators(
556 self, validators: Iterable[_validators_classes.Validator]
557 ) -> None:
558 """Asserts if all validators in the list are satisfied.
560 It asserts validators in the order they were created.
562 Args:
563 validators: Iterable(validators.Validator), validators to be verified.
565 Raises:
566 AttributeError: Raised if validators work with a non-existing flag.
567 IllegalFlagValueError: Raised if validation fails for at least one
568 validator.
569 """
570 messages = []
571 bad_flags: Set[str] = set()
572 for validator in sorted(
573 validators, key=lambda validator: validator.insertion_index):
574 try:
575 if isinstance(validator, _validators_classes.SingleFlagValidator):
576 if validator.flag_name in bad_flags:
577 continue
578 elif isinstance(validator, _validators_classes.MultiFlagsValidator):
579 if bad_flags & set(validator.flag_names):
580 continue
581 validator.verify(self)
582 except _exceptions.ValidationError as e:
583 if isinstance(validator, _validators_classes.SingleFlagValidator):
584 bad_flags.add(validator.flag_name)
585 elif isinstance(validator, _validators_classes.MultiFlagsValidator):
586 bad_flags.update(set(validator.flag_names))
587 message = validator.print_flags_with_values(self)
588 messages.append('%s: %s' % (message, str(e)))
589 if messages:
590 raise _exceptions.IllegalFlagValueError('\n'.join(messages))
592 def __delattr__(self, flag_name: str) -> None:
593 """Deletes a previously-defined flag from a flag object.
595 This method makes sure we can delete a flag by using
597 del FLAGS.<flag_name>
599 E.g.,
601 flags.DEFINE_integer('foo', 1, 'Integer flag.')
602 del flags.FLAGS.foo
604 If a flag is also registered by its the other name (long name or short
605 name), the other name won't be deleted.
607 Args:
608 flag_name: str, the name of the flag to be deleted.
610 Raises:
611 AttributeError: Raised when there is no registered flag named flag_name.
612 """
613 fl = self._flags()
614 flag_entry = fl.get(flag_name)
615 if flag_entry is None:
616 raise AttributeError(flag_name)
617 del fl[flag_name]
619 self._cleanup_unregistered_flag_from_module_dicts(flag_entry)
621 def set_default(self, name: str, value: Any) -> None:
622 """Changes the default value of the named flag object.
624 The flag's current value is also updated if the flag is currently using
625 the default value, i.e. not specified in the command line, and not set
626 by FLAGS.name = value.
628 Args:
629 name: str, the name of the flag to modify.
630 value: The new default value.
632 Raises:
633 UnrecognizedFlagError: Raised when there is no registered flag named name.
634 IllegalFlagValueError: Raised when value is not valid.
635 """
636 fl = self._flags()
637 flag_entry = fl.get(name)
638 if flag_entry is None:
639 self._set_unknown_flag(name, value)
640 return
641 flag_entry._set_default(value) # pylint: disable=protected-access
642 self._assert_validators(flag_entry.validators)
644 def __contains__(self, name: str) -> bool:
645 """Returns True if name is a value (flag) in the dict."""
646 return name in self._flags()
648 def __len__(self) -> int:
649 return len(self.__dict__['__flags'])
651 def __iter__(self) -> Iterator[str]:
652 return iter(self._flags())
654 def __call__(
655 self, argv: Sequence[str], known_only: bool = False
656 ) -> List[str]:
657 """Parses flags from argv; stores parsed flags into this FlagValues object.
659 All unparsed arguments are returned.
661 Args:
662 argv: a tuple/list of strings.
663 known_only: bool, if True, parse and remove known flags; return the rest
664 untouched. Unknown flags specified by --undefok are not returned.
666 Returns:
667 The list of arguments not parsed as options, including argv[0].
669 Raises:
670 Error: Raised on any parsing error.
671 TypeError: Raised on passing wrong type of arguments.
672 ValueError: Raised on flag value parsing error.
673 """
674 if isinstance(argv, (str, bytes)):
675 raise TypeError(
676 'argv should be a tuple/list of strings, not bytes or string.')
677 if not argv:
678 raise ValueError(
679 'argv cannot be an empty list, and must contain the program name as '
680 'the first element.')
682 # This pre parses the argv list for --flagfile=<> options.
683 program_name = argv[0]
684 args = self.read_flags_from_files(argv[1:], force_gnu=False)
686 # Parse the arguments.
687 unknown_flags, unparsed_args = self._parse_args(args, known_only)
689 # Handle unknown flags by raising UnrecognizedFlagError.
690 # Note some users depend on us raising this particular error.
691 for name, value in unknown_flags:
692 suggestions = _helpers.get_flag_suggestions(name, list(self))
693 raise _exceptions.UnrecognizedFlagError(
694 name, value, suggestions=suggestions)
696 self.mark_as_parsed()
697 self.validate_all_flags()
698 return [program_name] + unparsed_args
700 def __getstate__(self) -> Any:
701 raise TypeError("can't pickle FlagValues")
703 def __copy__(self) -> Any:
704 raise TypeError('FlagValues does not support shallow copies. '
705 'Use absl.testing.flagsaver or copy.deepcopy instead.')
707 def __deepcopy__(self, memo) -> Any:
708 result = object.__new__(type(self))
709 result.__dict__.update(copy.deepcopy(self.__dict__, memo))
710 return result
712 def _set_is_retired_flag_func(self, is_retired_flag_func):
713 """Sets a function for checking retired flags.
715 Do not use it. This is a private absl API used to check retired flags
716 registered by the absl C++ flags library.
718 Args:
719 is_retired_flag_func: Callable(str) -> (bool, bool), a function takes flag
720 name as parameter, returns a tuple (is_retired, type_is_bool).
721 """
722 self.__dict__['__is_retired_flag_func'] = is_retired_flag_func
724 def _parse_args(
725 self, args: List[str], known_only: bool
726 ) -> Tuple[List[Tuple[str, Any]], List[str]]:
727 """Helper function to do the main argument parsing.
729 This function goes through args and does the bulk of the flag parsing.
730 It will find the corresponding flag in our flag dictionary, and call its
731 .parse() method on the flag value.
733 Args:
734 args: [str], a list of strings with the arguments to parse.
735 known_only: bool, if True, parse and remove known flags; return the rest
736 untouched. Unknown flags specified by --undefok are not returned.
738 Returns:
739 A tuple with the following:
740 unknown_flags: List of (flag name, arg) for flags we don't know about.
741 unparsed_args: List of arguments we did not parse.
743 Raises:
744 Error: Raised on any parsing error.
745 ValueError: Raised on flag value parsing error.
746 """
747 unparsed_names_and_args: List[Tuple[Optional[str], str]] = []
748 undefok: Set[str] = set()
749 retired_flag_func = self.__dict__['__is_retired_flag_func']
751 flag_dict = self._flags()
752 args_it = iter(args)
753 del args
754 for arg in args_it:
755 value = None
757 def get_value() -> str:
758 try:
759 return next(args_it) if value is None else value # pylint: disable=cell-var-from-loop
760 except StopIteration:
761 raise _exceptions.Error('Missing value for flag ' + arg) from None # pylint: disable=cell-var-from-loop
763 if not arg.startswith('-'):
764 # A non-argument: default is break, GNU is skip.
765 unparsed_names_and_args.append((None, arg))
766 if self.is_gnu_getopt():
767 continue
768 else:
769 break
771 if arg == '--':
772 if known_only:
773 unparsed_names_and_args.append((None, arg))
774 break
776 # At this point, arg must start with '-'.
777 if arg.startswith('--'):
778 arg_without_dashes = arg[2:]
779 else:
780 arg_without_dashes = arg[1:]
782 if '=' in arg_without_dashes:
783 name, value = arg_without_dashes.split('=', 1)
784 else:
785 name, value = arg_without_dashes, None
787 if not name:
788 # The argument is all dashes (including one dash).
789 unparsed_names_and_args.append((None, arg))
790 if self.is_gnu_getopt():
791 continue
792 else:
793 break
795 # --undefok is a special case.
796 if name == 'undefok':
797 value = get_value()
798 undefok.update(v.strip() for v in value.split(','))
799 undefok.update('no' + v.strip() for v in value.split(','))
800 continue
802 flag = flag_dict.get(name)
803 if flag is not None:
804 if flag.boolean and value is None:
805 value = 'true'
806 else:
807 value = get_value()
808 elif name.startswith('no') and len(name) > 2:
809 # Boolean flags can take the form of --noflag, with no value.
810 noflag = flag_dict.get(name[2:])
811 if noflag is not None and noflag.boolean:
812 if value is not None:
813 raise ValueError(arg + ' does not take an argument')
814 flag = noflag
815 value = 'false'
817 if retired_flag_func and flag is None:
818 is_retired, is_bool = retired_flag_func(name)
820 # If we didn't recognize that flag, but it starts with
821 # "no" then maybe it was a boolean flag specified in the
822 # --nofoo form.
823 if not is_retired and name.startswith('no'):
824 is_retired, is_bool = retired_flag_func(name[2:])
825 is_retired = is_retired and is_bool
827 if is_retired:
828 if not is_bool and value is None:
829 # This happens when a non-bool retired flag is specified
830 # in format of "--flag value".
831 get_value()
832 logging.error(
833 'Flag "%s" is retired and should no longer be specified. See '
834 'https://abseil.io/tips/90.',
835 name,
836 )
837 continue
839 if flag is not None:
840 # LINT.IfChange
841 flag.parse(value)
842 flag.using_default_value = False
843 # LINT.ThenChange(../testing/flagsaver.py:flag_override_parsing)
844 else:
845 unparsed_names_and_args.append((name, arg))
847 unknown_flags = []
848 unparsed_args = []
849 for arg_name, arg in unparsed_names_and_args:
850 if arg_name is None:
851 # Positional arguments.
852 unparsed_args.append(arg)
853 elif arg_name in undefok:
854 # Remove undefok flags.
855 continue
856 else:
857 # This is an unknown flag.
858 if known_only:
859 unparsed_args.append(arg)
860 else:
861 unknown_flags.append((arg_name, arg))
863 unparsed_args.extend(list(args_it))
864 return unknown_flags, unparsed_args
866 def is_parsed(self) -> bool:
867 """Returns whether flags were parsed."""
868 return self.__dict__['__flags_parsed']
870 def mark_as_parsed(self) -> None:
871 """Explicitly marks flags as parsed.
873 Use this when the caller knows that this FlagValues has been parsed as if
874 a ``__call__()`` invocation has happened. This is only a public method for
875 use by things like appcommands which do additional command like parsing.
876 """
877 self.__dict__['__flags_parsed'] = True
879 def unparse_flags(self) -> None:
880 """Unparses all flags to the point before any FLAGS(argv) was called."""
881 for f in self._flags().values():
882 f.unparse()
883 # We log this message before marking flags as unparsed to avoid a
884 # problem when the logging library causes flags access.
885 logging.info('unparse_flags() called; flags access will now raise errors.')
886 self.__dict__['__flags_parsed'] = False
887 self.__dict__['__unparse_flags_called'] = True
889 def flag_values_dict(self) -> Dict[str, Any]:
890 """Returns a dictionary that maps flag names to flag values."""
891 return {name: flag.value for name, flag in list(self._flags().items())}
893 def __str__(self):
894 """Returns a help string for all known flags."""
895 return self.get_help()
897 def get_help(
898 self, prefix: str = '', include_special_flags: bool = True
899 ) -> str:
900 """Returns a help string for all known flags.
902 Args:
903 prefix: str, per-line output prefix.
904 include_special_flags: bool, whether to include description of
905 SPECIAL_FLAGS, i.e. --flagfile and --undefok.
907 Returns:
908 str, formatted help message.
909 """
910 flags_by_module = self.flags_by_module_dict()
911 if flags_by_module:
912 modules = sorted(flags_by_module)
913 # Print the help for the main module first, if possible.
914 main_module = sys.argv[0]
915 if main_module in modules:
916 modules.remove(main_module)
917 modules = [main_module] + modules
918 return self._get_help_for_modules(modules, prefix, include_special_flags)
919 else:
920 output_lines: List[str] = []
921 # Just print one long list of flags.
922 values = list(self._flags().values())
923 if include_special_flags:
924 values.extend(_helpers.SPECIAL_FLAGS._flags().values()) # pylint: disable=protected-access
925 self._render_flag_list(values, output_lines, prefix)
926 return '\n'.join(output_lines)
928 def _get_help_for_modules(self, modules, prefix, include_special_flags):
929 """Returns the help string for a list of modules.
931 Private to absl.flags package.
933 Args:
934 modules: List[str], a list of modules to get the help string for.
935 prefix: str, a string that is prepended to each generated help line.
936 include_special_flags: bool, whether to include description of
937 SPECIAL_FLAGS, i.e. --flagfile and --undefok.
938 """
939 output_lines = []
940 for module in modules:
941 self._render_our_module_flags(module, output_lines, prefix)
942 if include_special_flags:
943 self._render_module_flags(
944 'absl.flags',
945 _helpers.SPECIAL_FLAGS._flags().values(), # pylint: disable=protected-access # pytype: disable=attribute-error
946 output_lines,
947 prefix,
948 )
949 return '\n'.join(output_lines)
951 def _render_module_flags(self, module, flags, output_lines, prefix=''):
952 """Returns a help string for a given module."""
953 if not isinstance(module, str):
954 module = module.__name__
955 output_lines.append('\n%s%s:' % (prefix, module))
956 self._render_flag_list(flags, output_lines, prefix + ' ')
958 def _render_our_module_flags(self, module, output_lines, prefix=''):
959 """Returns a help string for a given module."""
960 flags = self.get_flags_for_module(module)
961 if flags:
962 self._render_module_flags(module, flags, output_lines, prefix)
964 def _render_our_module_key_flags(self, module, output_lines, prefix=''):
965 """Returns a help string for the key flags of a given module.
967 Args:
968 module: module|str, the module to render key flags for.
969 output_lines: [str], a list of strings. The generated help message lines
970 will be appended to this list.
971 prefix: str, a string that is prepended to each generated help line.
972 """
973 key_flags = self.get_key_flags_for_module(module)
974 if key_flags:
975 self._render_module_flags(module, key_flags, output_lines, prefix)
977 def module_help(self, module: Any) -> str:
978 """Describes the key flags of a module.
980 Args:
981 module: module|str, the module to describe the key flags for.
983 Returns:
984 str, describing the key flags of a module.
985 """
986 helplist: List[str] = []
987 self._render_our_module_key_flags(module, helplist)
988 return '\n'.join(helplist)
990 def main_module_help(self) -> str:
991 """Describes the key flags of the main module.
993 Returns:
994 str, describing the key flags of the main module.
995 """
996 return self.module_help(sys.argv[0])
998 def _render_flag_list(self, flaglist, output_lines, prefix=' '):
999 fl = self._flags()
1000 special_fl = _helpers.SPECIAL_FLAGS._flags() # pylint: disable=protected-access # pytype: disable=attribute-error
1001 flaglist = [(flag.name, flag) for flag in flaglist]
1002 flaglist.sort()
1003 flagset = {}
1004 for (name, flag) in flaglist:
1005 # It's possible this flag got deleted or overridden since being
1006 # registered in the per-module flaglist. Check now against the
1007 # canonical source of current flag information, the _flags.
1008 if fl.get(name, None) != flag and special_fl.get(name, None) != flag:
1009 # a different flag is using this name now
1010 continue
1011 # only print help once
1012 if flag in flagset:
1013 continue
1014 flagset[flag] = 1
1015 flaghelp = ''
1016 if flag.short_name:
1017 flaghelp += '-%s,' % flag.short_name
1018 if flag.boolean:
1019 flaghelp += '--[no]%s:' % flag.name
1020 else:
1021 flaghelp += '--%s:' % flag.name
1022 flaghelp += ' '
1023 if flag.help:
1024 flaghelp += flag.help
1025 flaghelp = _helpers.text_wrap(
1026 flaghelp, indent=prefix + ' ', firstline_indent=prefix)
1027 if flag.default_as_str:
1028 flaghelp += '\n'
1029 flaghelp += _helpers.text_wrap(
1030 '(default: %s)' % flag.default_as_str, indent=prefix + ' ')
1031 if flag.parser.syntactic_help:
1032 flaghelp += '\n'
1033 flaghelp += _helpers.text_wrap(
1034 '(%s)' % flag.parser.syntactic_help, indent=prefix + ' ')
1035 output_lines.append(flaghelp)
1037 def get_flag_value(self, name: str, default: Any) -> Any: # pylint: disable=invalid-name
1038 """Returns the value of a flag (if not None) or a default value.
1040 Args:
1041 name: str, the name of a flag.
1042 default: Default value to use if the flag value is None.
1044 Returns:
1045 Requested flag value or default.
1046 """
1048 value = self.__getattr__(name)
1049 if value is not None: # Can't do if not value, b/c value might be '0' or ""
1050 return value
1051 else:
1052 return default
1054 def _is_flag_file_directive(self, flag_string):
1055 """Checks whether flag_string contain a --flagfile=<foo> directive."""
1056 if isinstance(flag_string, str):
1057 if flag_string.startswith('--flagfile='):
1058 return 1
1059 elif flag_string == '--flagfile':
1060 return 1
1061 elif flag_string.startswith('-flagfile='):
1062 return 1
1063 elif flag_string == '-flagfile':
1064 return 1
1065 else:
1066 return 0
1067 return 0
1069 def _extract_filename(self, flagfile_str):
1070 """Returns filename from a flagfile_str of form -[-]flagfile=filename.
1072 The cases of --flagfile foo and -flagfile foo shouldn't be hitting
1073 this function, as they are dealt with in the level above this
1074 function.
1076 Args:
1077 flagfile_str: str, the flagfile string.
1079 Returns:
1080 str, the filename from a flagfile_str of form -[-]flagfile=filename.
1082 Raises:
1083 Error: Raised when illegal --flagfile is provided.
1084 """
1085 if flagfile_str.startswith('--flagfile='):
1086 return os.path.expanduser((flagfile_str[(len('--flagfile=')):]).strip())
1087 elif flagfile_str.startswith('-flagfile='):
1088 return os.path.expanduser((flagfile_str[(len('-flagfile=')):]).strip())
1089 else:
1090 raise _exceptions.Error('Hit illegal --flagfile type: %s' % flagfile_str)
1092 def _get_flag_file_lines(self, filename, parsed_file_stack=None):
1093 """Returns the useful (!=comments, etc) lines from a file with flags.
1095 Args:
1096 filename: str, the name of the flag file.
1097 parsed_file_stack: [str], a list of the names of the files that we have
1098 recursively encountered at the current depth. MUTATED BY THIS FUNCTION
1099 (but the original value is preserved upon successfully returning from
1100 function call).
1102 Returns:
1103 List of strings. See the note below.
1105 NOTE(springer): This function checks for a nested --flagfile=<foo>
1106 tag and handles the lower file recursively. It returns a list of
1107 all the lines that _could_ contain command flags. This is
1108 EVERYTHING except whitespace lines and comments (lines starting
1109 with '#' or '//').
1110 """
1111 # For consistency with the cpp version, ignore empty values.
1112 if not filename:
1113 return []
1114 if parsed_file_stack is None:
1115 parsed_file_stack = []
1116 # We do a little safety check for reparsing a file we've already encountered
1117 # at a previous depth.
1118 if filename in parsed_file_stack:
1119 sys.stderr.write('Warning: Hit circular flagfile dependency. Ignoring'
1120 ' flagfile: %s\n' % (filename,))
1121 return []
1122 else:
1123 parsed_file_stack.append(filename)
1125 line_list = [] # All line from flagfile.
1126 flag_line_list = [] # Subset of lines w/o comments, blanks, flagfile= tags.
1127 try:
1128 file_obj = open(filename)
1129 except OSError as e_msg:
1130 raise _exceptions.CantOpenFlagFileError(
1131 'ERROR:: Unable to open flagfile: %s' % e_msg)
1133 with file_obj:
1134 line_list = file_obj.readlines()
1136 # This is where we check each line in the file we just read.
1137 for line in line_list:
1138 if line.isspace():
1139 pass
1140 # Checks for comment (a line that starts with '#').
1141 elif line.startswith('#') or line.startswith('//'):
1142 pass
1143 # Checks for a nested "--flagfile=<bar>" flag in the current file.
1144 # If we find one, recursively parse down into that file.
1145 elif self._is_flag_file_directive(line):
1146 sub_filename = self._extract_filename(line)
1147 included_flags = self._get_flag_file_lines(
1148 sub_filename, parsed_file_stack=parsed_file_stack)
1149 flag_line_list.extend(included_flags)
1150 else:
1151 # Any line that's not a comment or a nested flagfile should get
1152 # copied into 2nd position. This leaves earlier arguments
1153 # further back in the list, thus giving them higher priority.
1154 flag_line_list.append(line.strip())
1156 parsed_file_stack.pop()
1157 return flag_line_list
1159 def read_flags_from_files(
1160 self, argv: Sequence[str], force_gnu: bool = True
1161 ) -> List[str]:
1162 """Processes command line args, but also allow args to be read from file.
1164 Args:
1165 argv: [str], a list of strings, usually sys.argv[1:], which may contain
1166 one or more flagfile directives of the form --flagfile="./filename".
1167 Note that the name of the program (sys.argv[0]) should be omitted.
1168 force_gnu: bool, if False, --flagfile parsing obeys the
1169 FLAGS.is_gnu_getopt() value. If True, ignore the value and always follow
1170 gnu_getopt semantics.
1172 Returns:
1173 A new list which has the original list combined with what we read
1174 from any flagfile(s).
1176 Raises:
1177 IllegalFlagValueError: Raised when --flagfile is provided with no
1178 argument.
1180 This function is called by FLAGS(argv).
1181 It scans the input list for a flag that looks like:
1182 --flagfile=<somefile>. Then it opens <somefile>, reads all valid key
1183 and value pairs and inserts them into the input list in exactly the
1184 place where the --flagfile arg is found.
1186 Note that your application's flags are still defined the usual way
1187 using absl.flags DEFINE_flag() type functions.
1189 Notes (assuming we're getting a commandline of some sort as our input):
1191 * For duplicate flags, the last one we hit should "win".
1192 * Since flags that appear later win, a flagfile's settings can be "weak"
1193 if the --flagfile comes at the beginning of the argument sequence,
1194 and it can be "strong" if the --flagfile comes at the end.
1195 * A further "--flagfile=<otherfile.cfg>" CAN be nested in a flagfile.
1196 It will be expanded in exactly the spot where it is found.
1197 * In a flagfile, a line beginning with # or // is a comment.
1198 * Entirely blank lines _should_ be ignored.
1199 """
1200 rest_of_args = argv
1201 new_argv = []
1202 while rest_of_args:
1203 current_arg = rest_of_args[0]
1204 rest_of_args = rest_of_args[1:]
1205 if self._is_flag_file_directive(current_arg):
1206 # This handles the case of -(-)flagfile foo. In this case the
1207 # next arg really is part of this one.
1208 if current_arg == '--flagfile' or current_arg == '-flagfile':
1209 if not rest_of_args:
1210 raise _exceptions.IllegalFlagValueError(
1211 '--flagfile with no argument')
1212 flag_filename = os.path.expanduser(rest_of_args[0])
1213 rest_of_args = rest_of_args[1:]
1214 else:
1215 # This handles the case of (-)-flagfile=foo.
1216 flag_filename = self._extract_filename(current_arg)
1217 new_argv.extend(self._get_flag_file_lines(flag_filename))
1218 else:
1219 new_argv.append(current_arg)
1220 # Stop parsing after '--', like getopt and gnu_getopt.
1221 if current_arg == '--':
1222 break
1223 # Stop parsing after a non-flag, like getopt.
1224 if not current_arg.startswith('-'):
1225 if not force_gnu and not self.__dict__['__use_gnu_getopt']:
1226 break
1227 else:
1228 if ('=' not in current_arg and rest_of_args and
1229 not rest_of_args[0].startswith('-')):
1230 # If this is an occurrence of a legitimate --x y, skip the value
1231 # so that it won't be mistaken for a standalone arg.
1232 fl = self._flags()
1233 name = current_arg.lstrip('-')
1234 if name in fl and not fl[name].boolean:
1235 current_arg = rest_of_args[0]
1236 rest_of_args = rest_of_args[1:]
1237 new_argv.append(current_arg)
1239 if rest_of_args:
1240 new_argv.extend(rest_of_args)
1242 return new_argv
1244 def flags_into_string(self) -> str:
1245 """Returns a string with the flags assignments from this FlagValues object.
1247 This function ignores flags whose value is None. Each flag
1248 assignment is separated by a newline.
1250 NOTE: MUST mirror the behavior of the C++ CommandlineFlagsIntoString
1251 from https://github.com/gflags/gflags.
1253 Returns:
1254 str, the string with the flags assignments from this FlagValues object.
1255 The flags are ordered by (module_name, flag_name).
1256 """
1257 module_flags = sorted(self.flags_by_module_dict().items())
1258 s = ''
1259 for unused_module_name, flags in module_flags:
1260 flags = sorted(flags, key=lambda f: f.name)
1261 for flag in flags:
1262 if flag.value is not None:
1263 s += flag.serialize() + '\n'
1264 return s
1266 def append_flags_into_file(self, filename: str) -> None:
1267 """Appends all flags assignments from this FlagInfo object to a file.
1269 Output will be in the format of a flagfile.
1271 NOTE: MUST mirror the behavior of the C++ AppendFlagsIntoFile
1272 from https://github.com/gflags/gflags.
1274 Args:
1275 filename: str, name of the file.
1276 """
1277 with open(filename, 'a') as out_file:
1278 out_file.write(self.flags_into_string())
1280 def write_help_in_xml_format(self, outfile: Optional[TextIO] = None) -> None:
1281 """Outputs flag documentation in XML format.
1283 NOTE: We use element names that are consistent with those used by
1284 the C++ command-line flag library, from
1285 https://github.com/gflags/gflags.
1286 We also use a few new elements (e.g., <key>), but we do not
1287 interfere / overlap with existing XML elements used by the C++
1288 library. Please maintain this consistency.
1290 Args:
1291 outfile: File object we write to. Default None means sys.stdout.
1292 """
1293 doc = minidom.Document()
1294 all_flag = doc.createElement('AllFlags')
1295 doc.appendChild(all_flag)
1297 all_flag.appendChild(
1298 _helpers.create_xml_dom_element(doc, 'program',
1299 os.path.basename(sys.argv[0])))
1301 usage_doc = sys.modules['__main__'].__doc__
1302 if not usage_doc:
1303 usage_doc = '\nUSAGE: %s [flags]\n' % sys.argv[0]
1304 else:
1305 usage_doc = usage_doc.replace('%s', sys.argv[0])
1306 all_flag.appendChild(
1307 _helpers.create_xml_dom_element(doc, 'usage', usage_doc))
1309 # Get list of key flags for the main module.
1310 key_flags = self.get_key_flags_for_module(sys.argv[0])
1312 flags_by_module = self.flags_by_module_dict()
1313 # Sort flags by declaring module name and next by flag name.
1314 for module_name in sorted(flags_by_module.keys()):
1315 flag_list = [(f.name, f) for f in flags_by_module[module_name]]
1316 flag_list.sort()
1317 for unused_flag_name, flag in flag_list:
1318 is_key = flag in key_flags
1319 all_flag.appendChild(
1320 flag._create_xml_dom_element( # pylint: disable=protected-access
1321 doc,
1322 module_name,
1323 is_key=is_key))
1325 outfile = outfile or sys.stdout
1326 outfile.write(
1327 doc.toprettyxml(indent=' ', encoding='utf-8').decode('utf-8'))
1328 outfile.flush()
1330 def _check_method_name_conflicts(self, name: str, flag: Flag):
1331 if flag.allow_using_method_names:
1332 return
1333 short_name = flag.short_name
1334 flag_names = {name} if short_name is None else {name, short_name}
1335 for flag_name in flag_names:
1336 if flag_name in self.__dict__['__banned_flag_names']:
1337 raise _exceptions.FlagNameConflictsWithMethodError(
1338 'Cannot define a flag named "{name}". It conflicts with a method '
1339 'on class "{class_name}". To allow defining it, use '
1340 'allow_using_method_names and access the flag value with '
1341 "FLAGS['{name}'].value. FLAGS.{name} returns the method, "
1342 'not the flag value.'.format(
1343 name=flag_name, class_name=type(self).__name__))
1346FLAGS = FlagValues()
1349class FlagHolder(Generic[_T_co]):
1350 """Holds a defined flag.
1352 This facilitates a cleaner api around global state. Instead of::
1354 flags.DEFINE_integer('foo', ...)
1355 flags.DEFINE_integer('bar', ...)
1357 def method():
1358 # prints parsed value of 'bar' flag
1359 print(flags.FLAGS.foo)
1360 # runtime error due to typo or possibly bad coding style.
1361 print(flags.FLAGS.baz)
1363 it encourages code like::
1365 _FOO_FLAG = flags.DEFINE_integer('foo', ...)
1366 _BAR_FLAG = flags.DEFINE_integer('bar', ...)
1368 def method():
1369 print(_FOO_FLAG.value)
1370 print(_BAR_FLAG.value)
1372 since the name of the flag appears only once in the source code.
1373 """
1375 value: _T_co
1377 def __init__(
1378 self,
1379 flag_values: FlagValues,
1380 flag: Flag[_T_co],
1381 ensure_non_none_value: bool = False,
1382 ):
1383 """Constructs a FlagHolder instance providing typesafe access to flag.
1385 Args:
1386 flag_values: The container the flag is registered to.
1387 flag: The flag object for this flag.
1388 ensure_non_none_value: Is the value of the flag allowed to be None.
1389 """
1390 self._flagvalues = flag_values
1391 # We take the entire flag object, but only keep the name. Why?
1392 # - We want FlagHolder[T] to be generic container
1393 # - flag_values contains all flags, so has no reference to T.
1394 # - typecheckers don't like to see a generic class where none of the ctor
1395 # arguments refer to the generic type.
1396 self._name = flag.name
1397 # We intentionally do NOT check if the default value is None.
1398 # This allows future use of this for "required flags with None default"
1399 self._ensure_non_none_value = ensure_non_none_value
1401 def __eq__(self, other):
1402 raise TypeError(
1403 "unsupported operand type(s) for ==: '{0}' and '{1}' "
1404 "(did you mean to use '{0}.value' instead?)".format(
1405 type(self).__name__, type(other).__name__))
1407 def __bool__(self):
1408 raise TypeError(
1409 "bool() not supported for instances of type '{0}' "
1410 "(did you mean to use '{0}.value' instead?)".format(
1411 type(self).__name__))
1413 __nonzero__ = __bool__
1415 @property
1416 def name(self) -> str:
1417 return self._name
1419 @property # type: ignore[no-redef]
1420 def value(self) -> _T_co:
1421 """Returns the value of the flag.
1423 If ``_ensure_non_none_value`` is ``True``, then return value is not
1424 ``None``.
1426 Raises:
1427 UnparsedFlagAccessError: if flag parsing has not finished.
1428 IllegalFlagValueError: if value is None unexpectedly.
1429 """
1430 val = getattr(self._flagvalues, self._name)
1431 if self._ensure_non_none_value and val is None:
1432 raise _exceptions.IllegalFlagValueError(
1433 'Unexpected None value for flag %s' % self._name)
1434 return val
1436 @property
1437 def default(self) -> _T_co:
1438 """Returns the default value of the flag."""
1439 return self._flagvalues[self._name].default # type: ignore[return-value]
1441 @property
1442 def present(self) -> bool:
1443 """Returns True if the flag was parsed from command-line flags."""
1444 return bool(self._flagvalues[self._name].present)
1446 def serialize(self) -> str:
1447 """Returns a serialized representation of the flag."""
1448 return self._flagvalues[self._name].serialize()
1451def resolve_flag_ref(
1452 flag_ref: Union[str, FlagHolder], flag_values: FlagValues
1453) -> Tuple[str, FlagValues]:
1454 """Helper to validate and resolve a flag reference argument."""
1455 if isinstance(flag_ref, FlagHolder):
1456 new_flag_values = flag_ref._flagvalues # pylint: disable=protected-access
1457 if flag_values != FLAGS and flag_values != new_flag_values:
1458 raise ValueError(
1459 'flag_values must not be customized when operating on a FlagHolder')
1460 return flag_ref.name, new_flag_values
1461 return flag_ref, flag_values
1464def resolve_flag_refs(
1465 flag_refs: Sequence[Union[str, FlagHolder]], flag_values: FlagValues
1466) -> Tuple[List[str], FlagValues]:
1467 """Helper to validate and resolve flag reference list arguments."""
1468 fv = None
1469 names = []
1470 for ref in flag_refs:
1471 if isinstance(ref, FlagHolder):
1472 newfv = ref._flagvalues # pylint: disable=protected-access
1473 name = ref.name
1474 else:
1475 newfv = flag_values
1476 name = ref
1477 if fv and fv != newfv:
1478 raise ValueError(
1479 'multiple FlagValues instances used in invocation. '
1480 'FlagHolders must be registered to the same FlagValues instance as '
1481 'do flag names, if provided.')
1482 fv = newfv
1483 names.append(name)
1484 if fv is None:
1485 raise ValueError('flag_refs argument must not be empty')
1486 return names, fv