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 itertools
22import logging
23import os
24import sys
25from typing import Any, Callable, Dict, Generic, Iterable, Iterator, List, Optional, Sequence, Set, TextIO, Tuple, TypeVar, Union
26from xml.dom import minidom
28from absl.flags import _exceptions
29from absl.flags import _flag
30from absl.flags import _helpers
31from absl.flags import _validators_classes
32from absl.flags._flag import Flag
34# Add flagvalues module to disclaimed module ids.
35_helpers.disclaim_module_ids.add(id(sys.modules[__name__]))
37_T = TypeVar('_T')
38_T_co = TypeVar('_T_co', covariant=True) # pytype: disable=not-supported-yet
41class FlagValues:
42 """Registry of :class:`~absl.flags.Flag` objects.
44 A :class:`FlagValues` can then scan command line arguments, passing flag
45 arguments through to the 'Flag' objects that it owns. It also
46 provides easy access to the flag values. Typically only one
47 :class:`FlagValues` object is needed by an application:
48 :const:`FLAGS`.
50 This class is heavily overloaded:
52 :class:`Flag` objects are registered via ``__setitem__``::
54 FLAGS['longname'] = x # register a new flag
56 The ``.value`` attribute of the registered :class:`~absl.flags.Flag` objects
57 can be accessed as attributes of this :class:`FlagValues` object, through
58 ``__getattr__``. Both the long and short name of the original
59 :class:`~absl.flags.Flag` objects can be used to access its value::
61 FLAGS.longname # parsed flag value
62 FLAGS.x # parsed flag value (short name)
64 Command line arguments are scanned and passed to the registered
65 :class:`~absl.flags.Flag` objects through the ``__call__`` method. Unparsed
66 arguments, including ``argv[0]`` (e.g. the program name) are returned::
68 argv = FLAGS(sys.argv) # scan command line arguments
70 The original registered :class:`~absl.flags.Flag` objects can be retrieved
71 through the use of the dictionary-like operator, ``__getitem__``::
73 x = FLAGS['longname'] # access the registered Flag object
75 The ``str()`` operator of a :class:`absl.flags.FlagValues` object provides
76 help for all of the registered :class:`~absl.flags.Flag` objects.
77 """
79 _HAS_DYNAMIC_ATTRIBUTES = True
81 # A note on collections.abc.Mapping:
82 # FlagValues defines __getitem__, __iter__, and __len__. It makes perfect
83 # sense to let it be a collections.abc.Mapping class. However, we are not
84 # able to do so. The mixin methods, e.g. keys, values, are not uncommon flag
85 # names. Those flag values would not be accessible via the FLAGS.xxx form.
87 __dict__: Dict[str, Any]
89 def __init__(self):
90 # Since everything in this class is so heavily overloaded, the only
91 # way of defining and using fields is to access __dict__ directly.
93 # Dictionary: flag name (string) -> Flag object.
94 self.__dict__['__flags'] = {}
96 # Set: name of hidden flag (string).
97 # Holds flags that should not be directly accessible from Python.
98 self.__dict__['__hiddenflags'] = set()
100 # Dictionary: module name (string) -> list of Flag objects that are defined
101 # by that module.
102 self.__dict__['__flags_by_module'] = {}
103 # Dictionary: module id (int) -> list of Flag objects that are defined by
104 # that module.
105 self.__dict__['__flags_by_module_id'] = {}
106 # Dictionary: module name (string) -> list of Flag objects that are
107 # key for that module.
108 self.__dict__['__key_flags_by_module'] = {}
110 # Bool: True if flags were parsed.
111 self.__dict__['__flags_parsed'] = False
113 # Bool: True if unparse_flags() was called.
114 self.__dict__['__unparse_flags_called'] = False
116 # None or Method(name, value) to call from __setattr__ for an unknown flag.
117 self.__dict__['__set_unknown'] = None
119 # A set of banned flag names. This is to prevent users from accidentally
120 # defining a flag that has the same name as a method on this class.
121 # Users can still allow defining the flag by passing
122 # allow_using_method_names=True in DEFINE_xxx functions.
123 self.__dict__['__banned_flag_names'] = frozenset(dir(FlagValues))
125 # Bool: Whether to use GNU style scanning.
126 self.__dict__['__use_gnu_getopt'] = True
128 # Bool: Whether use_gnu_getopt has been explicitly set by the user.
129 self.__dict__['__use_gnu_getopt_explicitly_set'] = False
131 # Function: Takes a flag name as parameter, returns a tuple
132 # (is_retired, type_is_bool).
133 self.__dict__['__is_retired_flag_func'] = None
135 def set_gnu_getopt(self, gnu_getopt: bool = True) -> None:
136 """Sets whether or not to use GNU style scanning.
138 GNU style allows mixing of flag and non-flag arguments. See
139 http://docs.python.org/library/getopt.html#getopt.gnu_getopt
141 Args:
142 gnu_getopt: bool, whether or not to use GNU style scanning.
143 """
144 self.__dict__['__use_gnu_getopt'] = gnu_getopt
145 self.__dict__['__use_gnu_getopt_explicitly_set'] = True
147 def is_gnu_getopt(self) -> bool:
148 return self.__dict__['__use_gnu_getopt']
150 def _flags(self) -> Dict[str, Flag]:
151 return self.__dict__['__flags']
153 def flags_by_module_dict(self) -> Dict[str, List[Flag]]:
154 """Returns the dictionary of module_name -> list of defined flags.
156 Returns:
157 A dictionary. Its keys are module names (strings). Its values
158 are lists of Flag objects.
159 """
160 return self.__dict__['__flags_by_module']
162 def flags_by_module_id_dict(self) -> Dict[int, List[Flag]]:
163 """Returns the dictionary of module_id -> list of defined flags.
165 Returns:
166 A dictionary. Its keys are module IDs (ints). Its values
167 are lists of Flag objects.
168 """
169 return self.__dict__['__flags_by_module_id']
171 def key_flags_by_module_dict(self) -> Dict[str, List[Flag]]:
172 """Returns the dictionary of module_name -> list of key flags.
174 Returns:
175 A dictionary. Its keys are module names (strings). Its values
176 are lists of Flag objects.
177 """
178 return self.__dict__['__key_flags_by_module']
180 def register_flag_by_module(self, module_name: str, flag: Flag) -> None:
181 """Records the module that defines a specific flag.
183 We keep track of which flag is defined by which module so that we
184 can later sort the flags by module.
186 Args:
187 module_name: str, the name of a Python module.
188 flag: Flag, the Flag instance that is key to the module.
189 """
190 flags_by_module = self.flags_by_module_dict()
191 flags_by_module.setdefault(module_name, []).append(flag)
193 def register_flag_by_module_id(self, module_id: int, flag: Flag) -> None:
194 """Records the module that defines a specific flag.
196 Args:
197 module_id: int, the ID of the Python module.
198 flag: Flag, the Flag instance that is key to the module.
199 """
200 flags_by_module_id = self.flags_by_module_id_dict()
201 flags_by_module_id.setdefault(module_id, []).append(flag)
203 def register_key_flag_for_module(self, module_name: str, flag: Flag) -> None:
204 """Specifies that a flag is a key flag for a module.
206 Args:
207 module_name: str, the name of a Python module.
208 flag: Flag, the Flag instance that is key to the module.
209 """
210 key_flags_by_module = self.key_flags_by_module_dict()
211 # The list of key flags for the module named module_name.
212 key_flags = key_flags_by_module.setdefault(module_name, [])
213 # Add flag, but avoid duplicates.
214 if flag not in key_flags:
215 key_flags.append(flag)
217 def _flag_is_registered(self, flag_obj: Flag) -> bool:
218 """Checks whether a Flag object is registered under long name or short name.
220 Args:
221 flag_obj: Flag, the Flag instance to check for.
223 Returns:
224 bool, True iff flag_obj is registered under long name or short name.
225 """
226 flag_dict = self._flags()
227 # Check whether flag_obj is registered under its long name.
228 name = flag_obj.name
229 if flag_dict.get(name, None) == flag_obj:
230 return True
231 # Check whether flag_obj is registered under its short name.
232 short_name = flag_obj.short_name
233 if (short_name is not None and flag_dict.get(short_name, None) == flag_obj):
234 return True
235 return False
237 def _cleanup_unregistered_flag_from_module_dicts(
238 self, flag_obj: Flag
239 ) -> None:
240 """Cleans up unregistered flags from all module -> [flags] dictionaries.
242 If flag_obj is registered under either its long name or short name, it
243 won't be removed from the dictionaries.
245 Args:
246 flag_obj: Flag, the Flag instance to clean up for.
247 """
248 if self._flag_is_registered(flag_obj):
249 return
250 # Materialize dict values to list to avoid concurrent modification.
251 for flags_in_module in [
252 *self.flags_by_module_dict().values(),
253 *self.flags_by_module_id_dict().values(),
254 *self.key_flags_by_module_dict().values(),
255 ]:
256 # While (as opposed to if) takes care of multiple occurrences of a
257 # flag in the list for the same module.
258 while flag_obj in flags_in_module:
259 flags_in_module.remove(flag_obj)
261 def get_flags_for_module(self, module: Union[str, Any]) -> List[Flag]:
262 """Returns the list of flags defined by a module.
264 Args:
265 module: module|str, the module to get flags from.
267 Returns:
268 [Flag], a new list of Flag instances. Caller may update this list as
269 desired: none of those changes will affect the internals of this
270 FlagValue instance.
271 """
272 if not isinstance(module, str):
273 module = module.__name__
274 if module == '__main__':
275 module = sys.argv[0]
277 return list(self.flags_by_module_dict().get(module, []))
279 def get_key_flags_for_module(self, module: Union[str, Any]) -> List[Flag]:
280 """Returns the list of key flags for a module.
282 Args:
283 module: module|str, the module to get key flags from.
285 Returns:
286 [Flag], a new list of Flag instances. Caller may update this list as
287 desired: none of those changes will affect the internals of this
288 FlagValue instance.
289 """
290 if not isinstance(module, str):
291 module = module.__name__
292 if module == '__main__':
293 module = sys.argv[0]
295 # Any flag is a key flag for the module that defined it. NOTE:
296 # key_flags is a fresh list: we can update it without affecting the
297 # internals of this FlagValues object.
298 key_flags = self.get_flags_for_module(module)
300 # Take into account flags explicitly declared as key for a module.
301 for flag in self.key_flags_by_module_dict().get(module, []):
302 if flag not in key_flags:
303 key_flags.append(flag)
304 return key_flags
306 # TODO(yileiyang): Restrict default to Optional[str].
307 def find_module_defining_flag(
308 self, flagname: str, default: Optional[_T] = None
309 ) -> Union[str, Optional[_T]]:
310 """Return the name of the module defining this flag, or default.
312 Args:
313 flagname: str, name of the flag to lookup.
314 default: Value to return if flagname is not defined. Defaults to None.
316 Returns:
317 The name of the module which registered the flag with this name.
318 If no such module exists (i.e. no flag with this name exists),
319 we return default.
320 """
321 registered_flag = self._flags().get(flagname)
322 if registered_flag is None:
323 return default
324 for module, flags in self.flags_by_module_dict().items():
325 for flag in flags:
326 # It must compare the flag with the one in _flags. This is because a
327 # flag might be overridden only for its long name (or short name),
328 # and only its short name (or long name) is considered registered.
329 if (flag.name == registered_flag.name and
330 flag.short_name == registered_flag.short_name):
331 return module
332 return default
334 # TODO(yileiyang): Restrict default to Optional[str].
335 def find_module_id_defining_flag(
336 self, flagname: str, default: Optional[_T] = None
337 ) -> Union[int, Optional[_T]]:
338 """Return the ID of the module defining this flag, or default.
340 Args:
341 flagname: str, name of the flag to lookup.
342 default: Value to return if flagname is not defined. Defaults to None.
344 Returns:
345 The ID of the module which registered the flag with this name.
346 If no such module exists (i.e. no flag with this name exists),
347 we return default.
348 """
349 registered_flag = self._flags().get(flagname)
350 if registered_flag is None:
351 return default
352 for module_id, flags in self.flags_by_module_id_dict().items():
353 for flag in flags:
354 # It must compare the flag with the one in _flags. This is because a
355 # flag might be overridden only for its long name (or short name),
356 # and only its short name (or long name) is considered registered.
357 if (flag.name == registered_flag.name and
358 flag.short_name == registered_flag.short_name):
359 return module_id
360 return default
362 def _register_unknown_flag_setter(
363 self, setter: Callable[[str, Any], None]
364 ) -> None:
365 """Allow set default values for undefined flags.
367 Args:
368 setter: Method(name, value) to call to __setattr__ an unknown flag. Must
369 raise NameError or ValueError for invalid name/value.
370 """
371 self.__dict__['__set_unknown'] = setter
373 def _set_unknown_flag(self, name: str, value: _T) -> _T:
374 """Returns value if setting flag |name| to |value| returned True.
376 Args:
377 name: str, name of the flag to set.
378 value: Value to set.
380 Returns:
381 Flag value on successful call.
383 Raises:
384 UnrecognizedFlagError
385 IllegalFlagValueError
386 """
387 setter = self.__dict__['__set_unknown']
388 if setter:
389 try:
390 setter(name, value)
391 return value
392 except (TypeError, ValueError): # Flag value is not valid.
393 raise _exceptions.IllegalFlagValueError(
394 f'"{value}" is not valid for --{name}'
395 )
396 except NameError: # Flag name is not valid.
397 pass
398 raise _exceptions.UnrecognizedFlagError(name, value)
400 def append_flag_values(self, flag_values: 'FlagValues') -> None:
401 """Appends flags registered in another FlagValues instance.
403 Args:
404 flag_values: FlagValues, the FlagValues instance from which to copy flags.
405 """
406 for flag_name, flag in flag_values._flags().items(): # pylint: disable=protected-access
407 # Each flags with short_name appears here twice (once under its
408 # normal name, and again with its short name). To prevent
409 # problems (DuplicateFlagError) with double flag registration, we
410 # perform a check to make sure that the entry we're looking at is
411 # for its normal name.
412 if flag_name == flag.name:
413 try:
414 self[flag_name] = flag
415 except _exceptions.DuplicateFlagError:
416 raise _exceptions.DuplicateFlagError.from_flag(
417 flag_name, self, other_flag_values=flag_values)
419 def remove_flag_values(
420 self, flag_values: 'Union[FlagValues, Iterable[str]]'
421 ) -> None:
422 """Remove flags that were previously appended from another FlagValues.
424 Args:
425 flag_values: FlagValues, the FlagValues instance containing flags to
426 remove.
427 """
428 for flag_name in flag_values:
429 self.__delattr__(flag_name)
431 def __setitem__(self, name: str, flag: Flag) -> None:
432 """Registers a new flag variable."""
433 fl = self._flags()
434 if not isinstance(flag, _flag.Flag):
435 raise _exceptions.IllegalFlagValueError(
436 f'Expect Flag instances, found type {type(flag)}. '
437 "Maybe you didn't mean to use FlagValue.__setitem__?")
438 if not isinstance(name, str):
439 raise _exceptions.Error('Flag name must be a string')
440 if not name:
441 raise _exceptions.Error('Flag name cannot be empty')
442 if ' ' in name:
443 raise _exceptions.Error('Flag name cannot contain a space')
444 self._check_method_name_conflicts(name, flag)
445 if name in fl and not flag.allow_override and not fl[name].allow_override:
446 module, module_name = _helpers.get_calling_module_object_and_name()
447 if (self.find_module_defining_flag(name) == module_name and
448 id(module) != self.find_module_id_defining_flag(name)):
449 # If the flag has already been defined by a module with the same name,
450 # but a different ID, we can stop here because it indicates that the
451 # module is simply being imported a subsequent time.
452 return
453 raise _exceptions.DuplicateFlagError.from_flag(name, self)
454 # If a new flag overrides an old one, we need to cleanup the old flag's
455 # modules if it's not registered.
456 flags_to_cleanup = set()
457 short_name: Optional[str] = flag.short_name
458 if short_name is not None:
459 if (short_name in fl and not flag.allow_override and
460 not fl[short_name].allow_override):
461 raise _exceptions.DuplicateFlagError.from_flag(short_name, self)
462 if short_name in fl and fl[short_name] != flag:
463 flags_to_cleanup.add(fl[short_name])
464 fl[short_name] = flag
465 if (name not in fl # new flag
466 or fl[name].using_default_value or not flag.using_default_value):
467 if name in fl and fl[name] != flag:
468 flags_to_cleanup.add(fl[name])
469 fl[name] = flag
470 for f in flags_to_cleanup:
471 self._cleanup_unregistered_flag_from_module_dicts(f)
473 def __dir__(self) -> List[str]:
474 """Returns list of names of all defined flags.
476 Useful for TAB-completion in ipython.
478 Returns:
479 [str], a list of names of all defined flags.
480 """
481 return sorted(self.__dict__['__flags'])
483 def __getitem__(self, name: str) -> Flag:
484 """Returns the Flag object for the flag --name."""
485 return self._flags()[name]
487 def _hide_flag(self, name):
488 """Marks the flag --name as hidden."""
489 self.__dict__['__hiddenflags'].add(name)
491 def __getattr__(self, name: str) -> Any:
492 """Retrieves the 'value' attribute of the flag --name."""
493 fl = self._flags()
494 if name not in fl:
495 raise AttributeError(name)
496 if name in self.__dict__['__hiddenflags']:
497 raise AttributeError(name)
499 if self.__dict__['__flags_parsed'] or fl[name].present:
500 return fl[name].value
501 else:
502 raise _exceptions.UnparsedFlagAccessError(
503 'Trying to access flag --%s before flags were parsed.' % name)
505 def __setattr__(self, name: str, value: _T) -> _T:
506 """Sets the 'value' attribute of the flag --name."""
507 self._set_attributes(**{name: value})
508 return value
510 def _set_attributes(self, **attributes: Any) -> None:
511 """Sets multiple flag values together, triggers validators afterwards."""
512 fl = self._flags()
513 known_flag_vals = {}
514 known_flag_used_defaults = {}
515 try:
516 for name, value in attributes.items():
517 if name in self.__dict__['__hiddenflags']:
518 raise AttributeError(name)
519 if name in fl:
520 orig = fl[name].value
521 fl[name].value = value
522 known_flag_vals[name] = orig
523 else:
524 self._set_unknown_flag(name, value)
525 for name in known_flag_vals:
526 self._assert_validators(fl[name].validators)
527 known_flag_used_defaults[name] = fl[name].using_default_value
528 fl[name].using_default_value = False
529 except:
530 for name, orig in known_flag_vals.items():
531 fl[name].value = orig
532 for name, orig in known_flag_used_defaults.items():
533 fl[name].using_default_value = orig
534 # NOTE: We do not attempt to undo unknown flag side effects because we
535 # cannot reliably undo the user-configured behavior.
536 raise
538 def validate_all_flags(self) -> None:
539 """Verifies whether all flags pass validation.
541 Raises:
542 AttributeError: Raised if validators work with a non-existing flag.
543 IllegalFlagValueError: Raised if validation fails for at least one
544 validator.
545 """
546 all_validators = set()
547 for flag in self._flags().values():
548 all_validators.update(flag.validators)
549 self._assert_validators(all_validators)
551 def _assert_validators(
552 self, validators: Iterable[_validators_classes.Validator]
553 ) -> None:
554 """Asserts if all validators in the list are satisfied.
556 It asserts validators in the order they were created.
558 Args:
559 validators: Iterable(validators.Validator), validators to be verified.
561 Raises:
562 AttributeError: Raised if validators work with a non-existing flag.
563 IllegalFlagValueError: Raised if validation fails for at least one
564 validator.
565 """
566 messages = []
567 bad_flags: Set[str] = set()
568 for validator in sorted(
569 validators, key=lambda validator: validator.insertion_index):
570 try:
571 if isinstance(validator, _validators_classes.SingleFlagValidator):
572 if validator.flag_name in bad_flags:
573 continue
574 elif isinstance(validator, _validators_classes.MultiFlagsValidator):
575 if bad_flags & set(validator.flag_names):
576 continue
577 validator.verify(self)
578 except _exceptions.ValidationError as e:
579 if isinstance(validator, _validators_classes.SingleFlagValidator):
580 bad_flags.add(validator.flag_name)
581 elif isinstance(validator, _validators_classes.MultiFlagsValidator):
582 bad_flags.update(set(validator.flag_names))
583 message = validator.print_flags_with_values(self)
584 messages.append('%s: %s' % (message, str(e)))
585 if messages:
586 raise _exceptions.IllegalFlagValueError('\n'.join(messages))
588 def __delattr__(self, flag_name: str) -> None:
589 """Deletes a previously-defined flag from a flag object.
591 This method makes sure we can delete a flag by using
593 del FLAGS.<flag_name>
595 E.g.,
597 flags.DEFINE_integer('foo', 1, 'Integer flag.')
598 del flags.FLAGS.foo
600 If a flag is also registered by its the other name (long name or short
601 name), the other name won't be deleted.
603 Args:
604 flag_name: str, the name of the flag to be deleted.
606 Raises:
607 AttributeError: Raised when there is no registered flag named flag_name.
608 """
609 fl = self._flags()
610 if flag_name not in fl:
611 raise AttributeError(flag_name)
613 flag_obj = fl[flag_name]
614 del fl[flag_name]
616 self._cleanup_unregistered_flag_from_module_dicts(flag_obj)
618 def set_default(self, name: str, value: Any) -> None:
619 """Changes the default value of the named flag object.
621 The flag's current value is also updated if the flag is currently using
622 the default value, i.e. not specified in the command line, and not set
623 by FLAGS.name = value.
625 Args:
626 name: str, the name of the flag to modify.
627 value: The new default value.
629 Raises:
630 UnrecognizedFlagError: Raised when there is no registered flag named name.
631 IllegalFlagValueError: Raised when value is not valid.
632 """
633 fl = self._flags()
634 if name not in fl:
635 self._set_unknown_flag(name, value)
636 return
637 fl[name]._set_default(value) # pylint: disable=protected-access
638 self._assert_validators(fl[name].validators)
640 def __contains__(self, name: str) -> bool:
641 """Returns True if name is a value (flag) in the dict."""
642 return name in self._flags()
644 def __len__(self) -> int:
645 return len(self.__dict__['__flags'])
647 def __iter__(self) -> Iterator[str]:
648 return iter(self._flags())
650 def __call__(
651 self, argv: Sequence[str], known_only: bool = False
652 ) -> List[str]:
653 """Parses flags from argv; stores parsed flags into this FlagValues object.
655 All unparsed arguments are returned.
657 Args:
658 argv: a tuple/list of strings.
659 known_only: bool, if True, parse and remove known flags; return the rest
660 untouched. Unknown flags specified by --undefok are not returned.
662 Returns:
663 The list of arguments not parsed as options, including argv[0].
665 Raises:
666 Error: Raised on any parsing error.
667 TypeError: Raised on passing wrong type of arguments.
668 ValueError: Raised on flag value parsing error.
669 """
670 if isinstance(argv, (str, bytes)):
671 raise TypeError(
672 'argv should be a tuple/list of strings, not bytes or string.')
673 if not argv:
674 raise ValueError(
675 'argv cannot be an empty list, and must contain the program name as '
676 'the first element.')
678 # This pre parses the argv list for --flagfile=<> options.
679 program_name = argv[0]
680 args = self.read_flags_from_files(argv[1:], force_gnu=False)
682 # Parse the arguments.
683 unknown_flags, unparsed_args = self._parse_args(args, known_only)
685 # Handle unknown flags by raising UnrecognizedFlagError.
686 # Note some users depend on us raising this particular error.
687 for name, value in unknown_flags:
688 suggestions = _helpers.get_flag_suggestions(name, list(self))
689 raise _exceptions.UnrecognizedFlagError(
690 name, value, suggestions=suggestions)
692 self.mark_as_parsed()
693 self.validate_all_flags()
694 return [program_name] + unparsed_args
696 def __getstate__(self) -> Any:
697 raise TypeError("can't pickle FlagValues")
699 def __copy__(self) -> Any:
700 raise TypeError('FlagValues does not support shallow copies. '
701 'Use absl.testing.flagsaver or copy.deepcopy instead.')
703 def __deepcopy__(self, memo) -> Any:
704 result = object.__new__(type(self))
705 result.__dict__.update(copy.deepcopy(self.__dict__, memo))
706 return result
708 def _set_is_retired_flag_func(self, is_retired_flag_func):
709 """Sets a function for checking retired flags.
711 Do not use it. This is a private absl API used to check retired flags
712 registered by the absl C++ flags library.
714 Args:
715 is_retired_flag_func: Callable(str) -> (bool, bool), a function takes flag
716 name as parameter, returns a tuple (is_retired, type_is_bool).
717 """
718 self.__dict__['__is_retired_flag_func'] = is_retired_flag_func
720 def _parse_args(
721 self, args: List[str], known_only: bool
722 ) -> Tuple[List[Tuple[str, Any]], List[str]]:
723 """Helper function to do the main argument parsing.
725 This function goes through args and does the bulk of the flag parsing.
726 It will find the corresponding flag in our flag dictionary, and call its
727 .parse() method on the flag value.
729 Args:
730 args: [str], a list of strings with the arguments to parse.
731 known_only: bool, if True, parse and remove known flags; return the rest
732 untouched. Unknown flags specified by --undefok are not returned.
734 Returns:
735 A tuple with the following:
736 unknown_flags: List of (flag name, arg) for flags we don't know about.
737 unparsed_args: List of arguments we did not parse.
739 Raises:
740 Error: Raised on any parsing error.
741 ValueError: Raised on flag value parsing error.
742 """
743 unparsed_names_and_args: List[Tuple[Optional[str], str]] = []
744 undefok: Set[str] = set()
745 retired_flag_func = self.__dict__['__is_retired_flag_func']
747 flag_dict = self._flags()
748 args_it = iter(args)
749 del args
750 for arg in args_it:
751 value = None
753 def get_value() -> str:
754 try:
755 return next(args_it) if value is None else value # pylint: disable=cell-var-from-loop
756 except StopIteration:
757 raise _exceptions.Error('Missing value for flag ' + arg) from None # pylint: disable=cell-var-from-loop
759 if not arg.startswith('-'):
760 # A non-argument: default is break, GNU is skip.
761 unparsed_names_and_args.append((None, arg))
762 if self.is_gnu_getopt():
763 continue
764 else:
765 break
767 if arg == '--':
768 if known_only:
769 unparsed_names_and_args.append((None, arg))
770 break
772 # At this point, arg must start with '-'.
773 if arg.startswith('--'):
774 arg_without_dashes = arg[2:]
775 else:
776 arg_without_dashes = arg[1:]
778 if '=' in arg_without_dashes:
779 name, value = arg_without_dashes.split('=', 1)
780 else:
781 name, value = arg_without_dashes, None
783 if not name:
784 # The argument is all dashes (including one dash).
785 unparsed_names_and_args.append((None, arg))
786 if self.is_gnu_getopt():
787 continue
788 else:
789 break
791 # --undefok is a special case.
792 if name == 'undefok':
793 value = get_value()
794 undefok.update(v.strip() for v in value.split(','))
795 undefok.update('no' + v.strip() for v in value.split(','))
796 continue
798 flag = flag_dict.get(name)
799 if flag is not None:
800 if flag.boolean and value is None:
801 value = 'true'
802 else:
803 value = get_value()
804 elif name.startswith('no') and len(name) > 2:
805 # Boolean flags can take the form of --noflag, with no value.
806 noflag = flag_dict.get(name[2:])
807 if noflag is not None and noflag.boolean:
808 if value is not None:
809 raise ValueError(arg + ' does not take an argument')
810 flag = noflag
811 value = 'false'
813 if retired_flag_func and flag is None:
814 is_retired, is_bool = retired_flag_func(name)
816 # If we didn't recognize that flag, but it starts with
817 # "no" then maybe it was a boolean flag specified in the
818 # --nofoo form.
819 if not is_retired and name.startswith('no'):
820 is_retired, is_bool = retired_flag_func(name[2:])
821 is_retired = is_retired and is_bool
823 if is_retired:
824 if not is_bool and value is None:
825 # This happens when a non-bool retired flag is specified
826 # in format of "--flag value".
827 get_value()
828 logging.error(
829 'Flag "%s" is retired and should no longer be specified. See '
830 'https://abseil.io/tips/90.',
831 name,
832 )
833 continue
835 if flag is not None:
836 # LINT.IfChange
837 flag.parse(value)
838 flag.using_default_value = False
839 # LINT.ThenChange(../testing/flagsaver.py:flag_override_parsing)
840 else:
841 unparsed_names_and_args.append((name, arg))
843 unknown_flags = []
844 unparsed_args = []
845 for arg_name, arg in unparsed_names_and_args:
846 if arg_name is None:
847 # Positional arguments.
848 unparsed_args.append(arg)
849 elif arg_name in undefok:
850 # Remove undefok flags.
851 continue
852 else:
853 # This is an unknown flag.
854 if known_only:
855 unparsed_args.append(arg)
856 else:
857 unknown_flags.append((arg_name, arg))
859 unparsed_args.extend(list(args_it))
860 return unknown_flags, unparsed_args
862 def is_parsed(self) -> bool:
863 """Returns whether flags were parsed."""
864 return self.__dict__['__flags_parsed']
866 def mark_as_parsed(self) -> None:
867 """Explicitly marks flags as parsed.
869 Use this when the caller knows that this FlagValues has been parsed as if
870 a ``__call__()`` invocation has happened. This is only a public method for
871 use by things like appcommands which do additional command like parsing.
872 """
873 self.__dict__['__flags_parsed'] = True
875 def unparse_flags(self) -> None:
876 """Unparses all flags to the point before any FLAGS(argv) was called."""
877 for f in self._flags().values():
878 f.unparse()
879 # We log this message before marking flags as unparsed to avoid a
880 # problem when the logging library causes flags access.
881 logging.info('unparse_flags() called; flags access will now raise errors.')
882 self.__dict__['__flags_parsed'] = False
883 self.__dict__['__unparse_flags_called'] = True
885 def flag_values_dict(self) -> Dict[str, Any]:
886 """Returns a dictionary that maps flag names to flag values."""
887 return {name: flag.value for name, flag in self._flags().items()}
889 def __str__(self):
890 """Returns a help string for all known flags."""
891 return self.get_help()
893 def get_help(
894 self, prefix: str = '', include_special_flags: bool = True
895 ) -> str:
896 """Returns a help string for all known flags.
898 Args:
899 prefix: str, per-line output prefix.
900 include_special_flags: bool, whether to include description of
901 SPECIAL_FLAGS, i.e. --flagfile and --undefok.
903 Returns:
904 str, formatted help message.
905 """
906 flags_by_module = self.flags_by_module_dict()
907 if flags_by_module:
908 modules = sorted(flags_by_module)
909 # Print the help for the main module first, if possible.
910 main_module = sys.argv[0]
911 if main_module in modules:
912 modules.remove(main_module)
913 modules = [main_module] + modules
914 return self._get_help_for_modules(modules, prefix, include_special_flags)
915 else:
916 output_lines: List[str] = []
917 # Just print one long list of flags.
918 values: Iterable[Flag] = self._flags().values()
919 if include_special_flags:
920 values = itertools.chain(
921 values, _helpers.SPECIAL_FLAGS._flags().values() # pylint: disable=protected-access
922 )
923 self._render_flag_list(values, output_lines, prefix)
924 return '\n'.join(output_lines)
926 def _get_help_for_modules(self, modules, prefix, include_special_flags):
927 """Returns the help string for a list of modules.
929 Private to absl.flags package.
931 Args:
932 modules: List[str], a list of modules to get the help string for.
933 prefix: str, a string that is prepended to each generated help line.
934 include_special_flags: bool, whether to include description of
935 SPECIAL_FLAGS, i.e. --flagfile and --undefok.
936 """
937 output_lines = []
938 for module in modules:
939 self._render_our_module_flags(module, output_lines, prefix)
940 if include_special_flags:
941 self._render_module_flags(
942 'absl.flags',
943 _helpers.SPECIAL_FLAGS._flags().values(), # pylint: disable=protected-access # pytype: disable=attribute-error
944 output_lines,
945 prefix,
946 )
947 return '\n'.join(output_lines)
949 def _render_module_flags(self, module, flags, output_lines, prefix=''):
950 """Returns a help string for a given module."""
951 if not isinstance(module, str):
952 module = module.__name__
953 output_lines.append('\n%s%s:' % (prefix, module))
954 self._render_flag_list(flags, output_lines, prefix + ' ')
956 def _render_our_module_flags(self, module, output_lines, prefix=''):
957 """Returns a help string for a given module."""
958 flags = self.get_flags_for_module(module)
959 if flags:
960 self._render_module_flags(module, flags, output_lines, prefix)
962 def _render_our_module_key_flags(self, module, output_lines, prefix=''):
963 """Returns a help string for the key flags of a given module.
965 Args:
966 module: module|str, the module to render key flags for.
967 output_lines: [str], a list of strings. The generated help message lines
968 will be appended to this list.
969 prefix: str, a string that is prepended to each generated help line.
970 """
971 key_flags = self.get_key_flags_for_module(module)
972 if key_flags:
973 self._render_module_flags(module, key_flags, output_lines, prefix)
975 def module_help(self, module: Any) -> str:
976 """Describes the key flags of a module.
978 Args:
979 module: module|str, the module to describe the key flags for.
981 Returns:
982 str, describing the key flags of a module.
983 """
984 helplist: List[str] = []
985 self._render_our_module_key_flags(module, helplist)
986 return '\n'.join(helplist)
988 def main_module_help(self) -> str:
989 """Describes the key flags of the main module.
991 Returns:
992 str, describing the key flags of the main module.
993 """
994 return self.module_help(sys.argv[0])
996 def _render_flag_list(self, flaglist, output_lines, prefix=' '):
997 fl = self._flags()
998 special_fl = _helpers.SPECIAL_FLAGS._flags() # pylint: disable=protected-access # pytype: disable=attribute-error
999 flaglist = [(flag.name, flag) for flag in flaglist]
1000 flaglist.sort()
1001 flagset = {}
1002 for (name, flag) in flaglist:
1003 # It's possible this flag got deleted or overridden since being
1004 # registered in the per-module flaglist. Check now against the
1005 # canonical source of current flag information, the _flags.
1006 if fl.get(name, None) != flag and special_fl.get(name, None) != flag:
1007 # a different flag is using this name now
1008 continue
1009 # only print help once
1010 if flag in flagset:
1011 continue
1012 flagset[flag] = 1
1013 flaghelp = ''
1014 if flag.short_name:
1015 flaghelp += '-%s,' % flag.short_name
1016 if flag.boolean:
1017 flaghelp += '--[no]%s:' % flag.name
1018 else:
1019 flaghelp += '--%s:' % flag.name
1020 flaghelp += ' '
1021 if flag.help:
1022 flaghelp += flag.help
1023 flaghelp = _helpers.text_wrap(
1024 flaghelp, indent=prefix + ' ', firstline_indent=prefix)
1025 if flag.default_as_str:
1026 flaghelp += '\n'
1027 flaghelp += _helpers.text_wrap(
1028 '(default: %s)' % flag.default_as_str, indent=prefix + ' ')
1029 if flag.parser.syntactic_help:
1030 flaghelp += '\n'
1031 flaghelp += _helpers.text_wrap(
1032 '(%s)' % flag.parser.syntactic_help, indent=prefix + ' ')
1033 output_lines.append(flaghelp)
1035 def get_flag_value(self, name: str, default: Any) -> Any: # pylint: disable=invalid-name
1036 """Returns the value of a flag (if not None) or a default value.
1038 Args:
1039 name: str, the name of a flag.
1040 default: Default value to use if the flag value is None.
1042 Returns:
1043 Requested flag value or default.
1044 """
1046 value = self.__getattr__(name)
1047 if value is not None: # Can't do if not value, b/c value might be '0' or ""
1048 return value
1049 else:
1050 return default
1052 def _is_flag_file_directive(self, flag_string):
1053 """Checks whether flag_string contain a --flagfile=<foo> directive."""
1054 if isinstance(flag_string, str):
1055 if flag_string.startswith('--flagfile='):
1056 return 1
1057 elif flag_string == '--flagfile':
1058 return 1
1059 elif flag_string.startswith('-flagfile='):
1060 return 1
1061 elif flag_string == '-flagfile':
1062 return 1
1063 else:
1064 return 0
1065 return 0
1067 def _extract_filename(self, flagfile_str):
1068 """Returns filename from a flagfile_str of form -[-]flagfile=filename.
1070 The cases of --flagfile foo and -flagfile foo shouldn't be hitting
1071 this function, as they are dealt with in the level above this
1072 function.
1074 Args:
1075 flagfile_str: str, the flagfile string.
1077 Returns:
1078 str, the filename from a flagfile_str of form -[-]flagfile=filename.
1080 Raises:
1081 Error: Raised when illegal --flagfile is provided.
1082 """
1083 if flagfile_str.startswith('--flagfile='):
1084 return os.path.expanduser((flagfile_str[(len('--flagfile=')):]).strip())
1085 elif flagfile_str.startswith('-flagfile='):
1086 return os.path.expanduser((flagfile_str[(len('-flagfile=')):]).strip())
1087 else:
1088 raise _exceptions.Error('Hit illegal --flagfile type: %s' % flagfile_str)
1090 def _get_flag_file_lines(self, filename, parsed_file_stack=None):
1091 """Returns the useful (!=comments, etc) lines from a file with flags.
1093 Args:
1094 filename: str, the name of the flag file.
1095 parsed_file_stack: [str], a list of the names of the files that we have
1096 recursively encountered at the current depth. MUTATED BY THIS FUNCTION
1097 (but the original value is preserved upon successfully returning from
1098 function call).
1100 Returns:
1101 List of strings. See the note below.
1103 NOTE(springer): This function checks for a nested --flagfile=<foo>
1104 tag and handles the lower file recursively. It returns a list of
1105 all the lines that _could_ contain command flags. This is
1106 EVERYTHING except whitespace lines and comments (lines starting
1107 with '#' or '//').
1108 """
1109 # For consistency with the cpp version, ignore empty values.
1110 if not filename:
1111 return []
1112 if parsed_file_stack is None:
1113 parsed_file_stack = []
1114 # We do a little safety check for reparsing a file we've already encountered
1115 # at a previous depth.
1116 if filename in parsed_file_stack:
1117 sys.stderr.write('Warning: Hit circular flagfile dependency. Ignoring'
1118 ' flagfile: %s\n' % (filename,))
1119 return []
1120 else:
1121 parsed_file_stack.append(filename)
1123 line_list = [] # All line from flagfile.
1124 flag_line_list = [] # Subset of lines w/o comments, blanks, flagfile= tags.
1125 try:
1126 file_obj = open(filename)
1127 except OSError as e_msg:
1128 raise _exceptions.CantOpenFlagFileError(
1129 'ERROR:: Unable to open flagfile: %s' % e_msg)
1131 with file_obj:
1132 line_list = file_obj.readlines()
1134 # This is where we check each line in the file we just read.
1135 for line in line_list:
1136 if line.isspace():
1137 pass
1138 # Checks for comment (a line that starts with '#').
1139 elif line.startswith('#') or line.startswith('//'):
1140 pass
1141 # Checks for a nested "--flagfile=<bar>" flag in the current file.
1142 # If we find one, recursively parse down into that file.
1143 elif self._is_flag_file_directive(line):
1144 sub_filename = self._extract_filename(line)
1145 included_flags = self._get_flag_file_lines(
1146 sub_filename, parsed_file_stack=parsed_file_stack)
1147 flag_line_list.extend(included_flags)
1148 else:
1149 # Any line that's not a comment or a nested flagfile should get
1150 # copied into 2nd position. This leaves earlier arguments
1151 # further back in the list, thus giving them higher priority.
1152 flag_line_list.append(line.strip())
1154 parsed_file_stack.pop()
1155 return flag_line_list
1157 def read_flags_from_files(
1158 self, argv: Sequence[str], force_gnu: bool = True
1159 ) -> List[str]:
1160 """Processes command line args, but also allow args to be read from file.
1162 Args:
1163 argv: [str], a list of strings, usually sys.argv[1:], which may contain
1164 one or more flagfile directives of the form --flagfile="./filename".
1165 Note that the name of the program (sys.argv[0]) should be omitted.
1166 force_gnu: bool, if False, --flagfile parsing obeys the
1167 FLAGS.is_gnu_getopt() value. If True, ignore the value and always follow
1168 gnu_getopt semantics.
1170 Returns:
1171 A new list which has the original list combined with what we read
1172 from any flagfile(s).
1174 Raises:
1175 IllegalFlagValueError: Raised when --flagfile is provided with no
1176 argument.
1178 This function is called by FLAGS(argv).
1179 It scans the input list for a flag that looks like:
1180 --flagfile=<somefile>. Then it opens <somefile>, reads all valid key
1181 and value pairs and inserts them into the input list in exactly the
1182 place where the --flagfile arg is found.
1184 Note that your application's flags are still defined the usual way
1185 using absl.flags DEFINE_flag() type functions.
1187 Notes (assuming we're getting a commandline of some sort as our input):
1189 * For duplicate flags, the last one we hit should "win".
1190 * Since flags that appear later win, a flagfile's settings can be "weak"
1191 if the --flagfile comes at the beginning of the argument sequence,
1192 and it can be "strong" if the --flagfile comes at the end.
1193 * A further "--flagfile=<otherfile.cfg>" CAN be nested in a flagfile.
1194 It will be expanded in exactly the spot where it is found.
1195 * In a flagfile, a line beginning with # or // is a comment.
1196 * Entirely blank lines _should_ be ignored.
1197 """
1198 rest_of_args = argv
1199 new_argv = []
1200 while rest_of_args:
1201 current_arg = rest_of_args[0]
1202 rest_of_args = rest_of_args[1:]
1203 if self._is_flag_file_directive(current_arg):
1204 # This handles the case of -(-)flagfile foo. In this case the
1205 # next arg really is part of this one.
1206 if current_arg == '--flagfile' or current_arg == '-flagfile':
1207 if not rest_of_args:
1208 raise _exceptions.IllegalFlagValueError(
1209 '--flagfile with no argument')
1210 flag_filename = os.path.expanduser(rest_of_args[0])
1211 rest_of_args = rest_of_args[1:]
1212 else:
1213 # This handles the case of (-)-flagfile=foo.
1214 flag_filename = self._extract_filename(current_arg)
1215 new_argv.extend(self._get_flag_file_lines(flag_filename))
1216 else:
1217 new_argv.append(current_arg)
1218 # Stop parsing after '--', like getopt and gnu_getopt.
1219 if current_arg == '--':
1220 break
1221 # Stop parsing after a non-flag, like getopt.
1222 if not current_arg.startswith('-'):
1223 if not force_gnu and not self.__dict__['__use_gnu_getopt']:
1224 break
1225 else:
1226 if ('=' not in current_arg and rest_of_args and
1227 not rest_of_args[0].startswith('-')):
1228 # If this is an occurrence of a legitimate --x y, skip the value
1229 # so that it won't be mistaken for a standalone arg.
1230 fl = self._flags()
1231 name = current_arg.lstrip('-')
1232 if name in fl and not fl[name].boolean:
1233 current_arg = rest_of_args[0]
1234 rest_of_args = rest_of_args[1:]
1235 new_argv.append(current_arg)
1237 if rest_of_args:
1238 new_argv.extend(rest_of_args)
1240 return new_argv
1242 def flags_into_string(self) -> str:
1243 """Returns a string with the flags assignments from this FlagValues object.
1245 This function ignores flags whose value is None. Each flag
1246 assignment is separated by a newline.
1248 NOTE: MUST mirror the behavior of the C++ CommandlineFlagsIntoString
1249 from https://github.com/gflags/gflags.
1251 Returns:
1252 str, the string with the flags assignments from this FlagValues object.
1253 The flags are ordered by (module_name, flag_name).
1254 """
1255 module_flags = sorted(self.flags_by_module_dict().items())
1256 s = ''
1257 for unused_module_name, flags in module_flags:
1258 flags = sorted(flags, key=lambda f: f.name)
1259 for flag in flags:
1260 if flag.value is not None:
1261 s += flag.serialize() + '\n'
1262 return s
1264 def append_flags_into_file(self, filename: str) -> None:
1265 """Appends all flags assignments from this FlagInfo object to a file.
1267 Output will be in the format of a flagfile.
1269 NOTE: MUST mirror the behavior of the C++ AppendFlagsIntoFile
1270 from https://github.com/gflags/gflags.
1272 Args:
1273 filename: str, name of the file.
1274 """
1275 with open(filename, 'a') as out_file:
1276 out_file.write(self.flags_into_string())
1278 def write_help_in_xml_format(self, outfile: Optional[TextIO] = None) -> None:
1279 """Outputs flag documentation in XML format.
1281 NOTE: We use element names that are consistent with those used by
1282 the C++ command-line flag library, from
1283 https://github.com/gflags/gflags.
1284 We also use a few new elements (e.g., <key>), but we do not
1285 interfere / overlap with existing XML elements used by the C++
1286 library. Please maintain this consistency.
1288 Args:
1289 outfile: File object we write to. Default None means sys.stdout.
1290 """
1291 doc = minidom.Document()
1292 all_flag = doc.createElement('AllFlags')
1293 doc.appendChild(all_flag)
1295 all_flag.appendChild(
1296 _helpers.create_xml_dom_element(doc, 'program',
1297 os.path.basename(sys.argv[0])))
1299 usage_doc = sys.modules['__main__'].__doc__
1300 if not usage_doc:
1301 usage_doc = '\nUSAGE: %s [flags]\n' % sys.argv[0]
1302 else:
1303 usage_doc = usage_doc.replace('%s', sys.argv[0])
1304 all_flag.appendChild(
1305 _helpers.create_xml_dom_element(doc, 'usage', usage_doc))
1307 # Get list of key flags for the main module.
1308 key_flags = self.get_key_flags_for_module(sys.argv[0])
1310 # Sort flags by declaring module name and next by flag name.
1311 flags_by_module = self.flags_by_module_dict()
1312 all_module_names = list(flags_by_module.keys())
1313 all_module_names.sort()
1314 for module_name in all_module_names:
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