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"""This modules contains flags DEFINE functions.
16Do NOT import this module directly. Import the flags package and use the
17aliases defined at the package level instead.
18"""
20import enum
21import sys
22import types
23from typing import Any, Iterable, List, Literal, Optional, Type, TypeVar, Union, overload
25from absl.flags import _argument_parser
26from absl.flags import _exceptions
27from absl.flags import _flag
28from absl.flags import _flagvalues
29from absl.flags import _helpers
30from absl.flags import _validators
32_helpers.disclaim_module_ids.add(id(sys.modules[__name__]))
34_T = TypeVar('_T')
35_ET = TypeVar('_ET', bound=enum.Enum)
38def _register_bounds_validator_if_needed(parser, name, flag_values):
39 """Enforces lower and upper bounds for numeric flags.
41 Args:
42 parser: NumericParser (either FloatParser or IntegerParser), provides lower
43 and upper bounds, and help text to display.
44 name: str, name of the flag
45 flag_values: FlagValues.
46 """
47 if parser.lower_bound is not None or parser.upper_bound is not None:
49 def checker(value):
50 if value is not None and parser.is_outside_bounds(value):
51 message = '%s is not %s' % (value, parser.syntactic_help)
52 raise _exceptions.ValidationError(message)
53 return True
55 _validators.register_validator(name, checker, flag_values=flag_values)
58@overload
59def DEFINE( # pylint: disable=invalid-name
60 parser: _argument_parser.ArgumentParser[_T],
61 name: str,
62 default: Any,
63 help: Optional[str], # pylint: disable=redefined-builtin
64 flag_values: _flagvalues.FlagValues = ...,
65 serializer: Optional[_argument_parser.ArgumentSerializer[_T]] = ...,
66 module_name: Optional[str] = ...,
67 required: Literal[True] = ...,
68 **args: Any
69) -> _flagvalues.FlagHolder[_T]:
70 ...
73@overload
74def DEFINE( # pylint: disable=invalid-name
75 parser: _argument_parser.ArgumentParser[_T],
76 name: str,
77 default: Optional[Any],
78 help: Optional[str], # pylint: disable=redefined-builtin
79 flag_values: _flagvalues.FlagValues = ...,
80 serializer: Optional[_argument_parser.ArgumentSerializer[_T]] = ...,
81 module_name: Optional[str] = ...,
82 required: bool = ...,
83 **args: Any
84) -> _flagvalues.FlagHolder[Optional[_T]]:
85 ...
88def DEFINE( # pylint: disable=invalid-name
89 parser,
90 name,
91 default,
92 help, # pylint: disable=redefined-builtin
93 flag_values=_flagvalues.FLAGS,
94 serializer=None,
95 module_name=None,
96 required=False,
97 **args):
98 """Registers a generic Flag object.
100 NOTE: in the docstrings of all DEFINE* functions, "registers" is short
101 for "creates a new flag and registers it".
103 Auxiliary function: clients should use the specialized ``DEFINE_<type>``
104 function instead.
106 Args:
107 parser: :class:`ArgumentParser`, used to parse the flag arguments.
108 name: str, the flag name.
109 default: The default value of the flag.
110 help: str, the help message.
111 flag_values: :class:`FlagValues`, the FlagValues instance with which the
112 flag will be registered. This should almost never need to be overridden.
113 serializer: :class:`ArgumentSerializer`, the flag serializer instance.
114 module_name: str, the name of the Python module declaring this flag. If not
115 provided, it will be computed using the stack trace of this call.
116 required: bool, is this a required flag. This must be used as a keyword
117 argument.
118 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
120 Returns:
121 a handle to defined flag.
122 """
123 return DEFINE_flag(
124 _flag.Flag(parser, serializer, name, default, help, **args),
125 flag_values,
126 module_name,
127 required=True if required else False,
128 )
131@overload
132def DEFINE_flag( # pylint: disable=invalid-name
133 flag: _flag.Flag[_T],
134 flag_values: _flagvalues.FlagValues = ...,
135 module_name: Optional[str] = ...,
136 required: Literal[True] = ...,
137) -> _flagvalues.FlagHolder[_T]:
138 ...
141@overload
142def DEFINE_flag( # pylint: disable=invalid-name
143 flag: _flag.Flag[_T],
144 flag_values: _flagvalues.FlagValues = ...,
145 module_name: Optional[str] = ...,
146 required: bool = ...,
147) -> _flagvalues.FlagHolder[Optional[_T]]:
148 ...
151def DEFINE_flag( # pylint: disable=invalid-name
152 flag,
153 flag_values=_flagvalues.FLAGS,
154 module_name=None,
155 required=False):
156 """Registers a :class:`Flag` object with a :class:`FlagValues` object.
158 By default, the global :const:`FLAGS` ``FlagValue`` object is used.
160 Typical users will use one of the more specialized DEFINE_xxx
161 functions, such as :func:`DEFINE_string` or :func:`DEFINE_integer`. But
162 developers who need to create :class:`Flag` objects themselves should use
163 this function to register their flags.
165 Args:
166 flag: :class:`Flag`, a flag that is key to the module.
167 flag_values: :class:`FlagValues`, the ``FlagValues`` instance with which the
168 flag will be registered. This should almost never need to be overridden.
169 module_name: str, the name of the Python module declaring this flag. If not
170 provided, it will be computed using the stack trace of this call.
171 required: bool, is this a required flag. This must be used as a keyword
172 argument.
174 Returns:
175 a handle to defined flag.
176 """
177 if required and flag.default is not None:
178 raise ValueError(
179 'Required flag --%s needs to have None as default' % flag.name
180 )
181 # Copying the reference to flag_values prevents pychecker warnings.
182 fv = flag_values
183 fv[flag.name] = flag
184 # Tell flag_values who's defining the flag.
185 if module_name:
186 module = sys.modules.get(module_name)
187 else:
188 module, module_name = _helpers.get_calling_module_object_and_name()
189 flag_values.register_flag_by_module(module_name, flag)
190 flag_values.register_flag_by_module_id(id(module), flag)
191 if required:
192 _validators.mark_flag_as_required(flag.name, fv)
193 ensure_non_none_value = (flag.default is not None) or required
194 return _flagvalues.FlagHolder(
195 fv, flag, ensure_non_none_value=ensure_non_none_value)
198def set_default(flag_holder: _flagvalues.FlagHolder[_T], value: _T) -> None:
199 """Changes the default value of the provided flag object.
201 The flag's current value is also updated if the flag is currently using
202 the default value, i.e. not specified in the command line, and not set
203 by FLAGS.name = value.
205 Args:
206 flag_holder: FlagHolder, the flag to modify.
207 value: The new default value.
209 Raises:
210 IllegalFlagValueError: Raised when value is not valid.
211 """
212 flag_holder._flagvalues.set_default(flag_holder.name, value) # pylint: disable=protected-access
215def override_value(flag_holder: _flagvalues.FlagHolder[_T], value: _T) -> None:
216 """Overrides the value of the provided flag.
218 This value takes precedent over the default value and, when called after flag
219 parsing, any value provided at the command line.
221 Args:
222 flag_holder: FlagHolder, the flag to modify.
223 value: The new value.
225 Raises:
226 IllegalFlagValueError: The value did not pass the flag parser or validators.
227 """
228 fv = flag_holder._flagvalues # pylint: disable=protected-access
229 # Ensure the new value satisfies the flag's parser while avoiding side
230 # effects of calling parse().
231 parsed = fv[flag_holder.name]._parse(value) # pylint: disable=protected-access
232 if parsed != value:
233 raise _exceptions.IllegalFlagValueError(
234 'flag %s: parsed value %r not equal to original %r'
235 % (flag_holder.name, parsed, value)
236 )
237 setattr(fv, flag_holder.name, value)
240def _internal_declare_key_flags(
241 flag_names: List[str],
242 flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS,
243 key_flag_values: Optional[_flagvalues.FlagValues] = None,
244) -> None:
245 """Declares a flag as key for the calling module.
247 Internal function. User code should call declare_key_flag or
248 adopt_module_key_flags instead.
250 Args:
251 flag_names: [str], a list of names of already-registered Flag objects.
252 flag_values: :class:`FlagValues`, the FlagValues instance with which the
253 flags listed in flag_names have registered (the value of the flag_values
254 argument from the ``DEFINE_*`` calls that defined those flags). This
255 should almost never need to be overridden.
256 key_flag_values: :class:`FlagValues`, the FlagValues instance that (among
257 possibly many other things) keeps track of the key flags for each module.
258 Default ``None`` means "same as flag_values". This should almost never
259 need to be overridden.
261 Raises:
262 UnrecognizedFlagError: Raised when the flag is not defined.
263 """
264 key_flag_values = key_flag_values or flag_values
266 module = _helpers.get_calling_module()
268 for flag_name in flag_names:
269 key_flag_values.register_key_flag_for_module(module, flag_values[flag_name])
272def declare_key_flag(
273 flag_name: Union[str, _flagvalues.FlagHolder],
274 flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS,
275) -> None:
276 """Declares one flag as key to the current module.
278 Key flags are flags that are deemed really important for a module.
279 They are important when listing help messages; e.g., if the
280 --helpshort command-line flag is used, then only the key flags of the
281 main module are listed (instead of all flags, as in the case of
282 --helpfull).
284 Sample usage::
286 flags.declare_key_flag('flag_1')
288 Args:
289 flag_name: str | :class:`FlagHolder`, the name or holder of an already
290 declared flag. (Redeclaring flags as key, including flags implicitly key
291 because they were declared in this module, is a no-op.)
292 Positional-only parameter.
293 flag_values: :class:`FlagValues`, the FlagValues instance in which the
294 flag will be declared as a key flag. This should almost never need to be
295 overridden.
297 Raises:
298 ValueError: Raised if flag_name not defined as a Python flag.
299 """
300 flag_name, flag_values = _flagvalues.resolve_flag_ref(flag_name, flag_values)
301 if flag_name in _helpers.SPECIAL_FLAGS:
302 # Take care of the special flags, e.g., --flagfile, --undefok.
303 # These flags are defined in SPECIAL_FLAGS, and are treated
304 # specially during flag parsing, taking precedence over the
305 # user-defined flags.
306 _internal_declare_key_flags([flag_name],
307 flag_values=_helpers.SPECIAL_FLAGS,
308 key_flag_values=flag_values)
309 return
310 try:
311 _internal_declare_key_flags([flag_name], flag_values=flag_values)
312 except KeyError:
313 raise ValueError('Flag --%s is undefined. To set a flag as a key flag '
314 'first define it in Python.' % flag_name)
317def adopt_module_key_flags(
318 module: Any, flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS
319) -> None:
320 """Declares that all flags key to a module are key to the current module.
322 Args:
323 module: module, the module object from which all key flags will be declared
324 as key flags to the current module.
325 flag_values: :class:`FlagValues`, the FlagValues instance in which the
326 flags will be declared as key flags. This should almost never need to be
327 overridden.
329 Raises:
330 Error: Raised when given an argument that is a module name (a string),
331 instead of a module object.
332 """
333 if not isinstance(module, types.ModuleType):
334 raise _exceptions.Error('Expected a module object, not %r.' % (module,))
335 _internal_declare_key_flags(
336 [f.name for f in flag_values.get_key_flags_for_module(module.__name__)],
337 flag_values=flag_values)
338 # If module is this flag module, take _helpers.SPECIAL_FLAGS into account.
339 if module == _helpers.FLAGS_MODULE:
340 _internal_declare_key_flags(
341 # As we associate flags with get_calling_module_object_and_name(), the
342 # special flags defined in this module are incorrectly registered with
343 # a different module. So, we can't use get_key_flags_for_module.
344 # Instead, we take all flags from _helpers.SPECIAL_FLAGS (a private
345 # FlagValues, where no other module should register flags).
346 [_helpers.SPECIAL_FLAGS[name].name for name in _helpers.SPECIAL_FLAGS],
347 flag_values=_helpers.SPECIAL_FLAGS,
348 key_flag_values=flag_values)
351def disclaim_key_flags() -> None:
352 """Declares that the current module will not define any more key flags.
354 Normally, the module that calls the DEFINE_xxx functions claims the
355 flag to be its key flag. This is undesirable for modules that
356 define additional DEFINE_yyy functions with its own flag parsers and
357 serializers, since that module will accidentally claim flags defined
358 by DEFINE_yyy as its key flags. After calling this function, the
359 module disclaims flag definitions thereafter, so the key flags will
360 be correctly attributed to the caller of DEFINE_yyy.
362 After calling this function, the module will not be able to define
363 any more flags. This function will affect all FlagValues objects.
364 """
365 globals_for_caller = sys._getframe(1).f_globals # pylint: disable=protected-access
366 module, _ = _helpers.get_module_object_and_name(globals_for_caller)
367 _helpers.disclaim_module_ids.add(id(module))
370@overload
371def DEFINE_string( # pylint: disable=invalid-name
372 name: str,
373 default: Optional[str],
374 help: Optional[str], # pylint: disable=redefined-builtin
375 flag_values: _flagvalues.FlagValues = ...,
376 *,
377 required: Literal[True],
378 **args: Any
379) -> _flagvalues.FlagHolder[str]:
380 ...
383@overload
384def DEFINE_string( # pylint: disable=invalid-name
385 name: str,
386 default: None,
387 help: Optional[str], # pylint: disable=redefined-builtin
388 flag_values: _flagvalues.FlagValues = ...,
389 required: bool = ...,
390 **args: Any
391) -> _flagvalues.FlagHolder[Optional[str]]:
392 ...
395@overload
396def DEFINE_string( # pylint: disable=invalid-name
397 name: str,
398 default: str,
399 help: Optional[str], # pylint: disable=redefined-builtin
400 flag_values: _flagvalues.FlagValues = ...,
401 required: bool = ...,
402 **args: Any
403) -> _flagvalues.FlagHolder[str]:
404 ...
407def DEFINE_string( # pylint: disable=invalid-name
408 name,
409 default,
410 help, # pylint: disable=redefined-builtin
411 flag_values=_flagvalues.FLAGS,
412 required=False,
413 **args
414):
415 """Registers a flag whose value can be any string."""
416 parser = _argument_parser.ArgumentParser[str]()
417 serializer = _argument_parser.ArgumentSerializer[str]()
418 return DEFINE(
419 parser,
420 name,
421 default,
422 help,
423 flag_values,
424 serializer,
425 required=True if required else False,
426 **args,
427 )
430@overload
431def DEFINE_boolean( # pylint: disable=invalid-name
432 name: str,
433 default: Union[None, str, bool, int],
434 help: Optional[str], # pylint: disable=redefined-builtin
435 flag_values: _flagvalues.FlagValues = ...,
436 module_name: Optional[str] = ...,
437 *,
438 required: Literal[True],
439 **args: Any
440) -> _flagvalues.FlagHolder[bool]:
441 ...
444@overload
445def DEFINE_boolean( # pylint: disable=invalid-name
446 name: str,
447 default: None,
448 help: Optional[str], # pylint: disable=redefined-builtin
449 flag_values: _flagvalues.FlagValues = ...,
450 module_name: Optional[str] = ...,
451 required: bool = ...,
452 **args: Any
453) -> _flagvalues.FlagHolder[Optional[bool]]:
454 ...
457@overload
458def DEFINE_boolean( # pylint: disable=invalid-name
459 name: str,
460 default: Union[str, bool, int],
461 help: Optional[str], # pylint: disable=redefined-builtin
462 flag_values: _flagvalues.FlagValues = ...,
463 module_name: Optional[str] = ...,
464 required: bool = ...,
465 **args: Any
466) -> _flagvalues.FlagHolder[bool]:
467 ...
470# pytype: disable=bad-return-type
471def DEFINE_boolean( # pylint: disable=invalid-name
472 name,
473 default,
474 help, # pylint: disable=redefined-builtin
475 flag_values=_flagvalues.FLAGS,
476 module_name=None,
477 required=False,
478 **args
479):
480 """Registers a boolean flag.
482 Such a boolean flag does not take an argument. If a user wants to
483 specify a false value explicitly, the long option beginning with 'no'
484 must be used: i.e. --noflag
486 This flag will have a value of None, True or False. None is possible
487 if default=None and the user does not specify the flag on the command
488 line.
490 Args:
491 name: str, the flag name.
492 default: bool|str|None, the default value of the flag.
493 help: str, the help message.
494 flag_values: :class:`FlagValues`, the FlagValues instance with which the
495 flag will be registered. This should almost never need to be overridden.
496 module_name: str, the name of the Python module declaring this flag. If not
497 provided, it will be computed using the stack trace of this call.
498 required: bool, is this a required flag. This must be used as a keyword
499 argument.
500 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
502 Returns:
503 a handle to defined flag.
504 """
505 return DEFINE_flag(
506 _flag.BooleanFlag(name, default, help, **args),
507 flag_values,
508 module_name,
509 required=True if required else False,
510 )
513@overload
514def DEFINE_float( # pylint: disable=invalid-name
515 name: str,
516 default: Union[None, float, str],
517 help: Optional[str], # pylint: disable=redefined-builtin
518 lower_bound: Optional[float] = ...,
519 upper_bound: Optional[float] = ...,
520 flag_values: _flagvalues.FlagValues = ...,
521 *,
522 required: Literal[True],
523 **args: Any
524) -> _flagvalues.FlagHolder[float]:
525 ...
528@overload
529def DEFINE_float( # pylint: disable=invalid-name
530 name: str,
531 default: None,
532 help: Optional[str], # pylint: disable=redefined-builtin
533 lower_bound: Optional[float] = ...,
534 upper_bound: Optional[float] = ...,
535 flag_values: _flagvalues.FlagValues = ...,
536 required: bool = ...,
537 **args: Any
538) -> _flagvalues.FlagHolder[Optional[float]]:
539 ...
542@overload
543def DEFINE_float( # pylint: disable=invalid-name
544 name: str,
545 default: Union[float, str],
546 help: Optional[str], # pylint: disable=redefined-builtin
547 lower_bound: Optional[float] = ...,
548 upper_bound: Optional[float] = ...,
549 flag_values: _flagvalues.FlagValues = ...,
550 required: bool = ...,
551 **args: Any
552) -> _flagvalues.FlagHolder[float]:
553 ...
556def DEFINE_float( # pylint: disable=invalid-name
557 name,
558 default,
559 help, # pylint: disable=redefined-builtin
560 lower_bound=None,
561 upper_bound=None,
562 flag_values=_flagvalues.FLAGS,
563 required=False,
564 **args
565):
566 """Registers a flag whose value must be a float.
568 If ``lower_bound`` or ``upper_bound`` are set, then this flag must be
569 within the given range.
571 Args:
572 name: str, the flag name.
573 default: float|str|None, the default value of the flag.
574 help: str, the help message.
575 lower_bound: float, min value of the flag.
576 upper_bound: float, max value of the flag.
577 flag_values: :class:`FlagValues`, the FlagValues instance with which the
578 flag will be registered. This should almost never need to be overridden.
579 required: bool, is this a required flag. This must be used as a keyword
580 argument.
581 **args: dict, the extra keyword args that are passed to :func:`DEFINE`.
583 Returns:
584 a handle to defined flag.
585 """
586 parser = _argument_parser.FloatParser(lower_bound, upper_bound)
587 serializer = _argument_parser.ArgumentSerializer()
588 result = DEFINE(
589 parser,
590 name,
591 default,
592 help, # pylint: disable=redefined-builtin
593 flag_values,
594 serializer,
595 required=True if required else False,
596 **args,
597 )
598 _register_bounds_validator_if_needed(parser, name, flag_values=flag_values)
599 return result
602@overload
603def DEFINE_integer( # pylint: disable=invalid-name
604 name: str,
605 default: Union[None, int, str],
606 help: Optional[str], # pylint: disable=redefined-builtin
607 lower_bound: Optional[int] = ...,
608 upper_bound: Optional[int] = ...,
609 flag_values: _flagvalues.FlagValues = ...,
610 *,
611 required: Literal[True],
612 **args: Any
613) -> _flagvalues.FlagHolder[int]:
614 ...
617@overload
618def DEFINE_integer( # pylint: disable=invalid-name
619 name: str,
620 default: None,
621 help: Optional[str], # pylint: disable=redefined-builtin
622 lower_bound: Optional[int] = ...,
623 upper_bound: Optional[int] = ...,
624 flag_values: _flagvalues.FlagValues = ...,
625 required: bool = ...,
626 **args: Any
627) -> _flagvalues.FlagHolder[Optional[int]]:
628 ...
631@overload
632def DEFINE_integer( # pylint: disable=invalid-name
633 name: str,
634 default: Union[int, str],
635 help: Optional[str], # pylint: disable=redefined-builtin
636 lower_bound: Optional[int] = ...,
637 upper_bound: Optional[int] = ...,
638 flag_values: _flagvalues.FlagValues = ...,
639 required: bool = ...,
640 **args: Any
641) -> _flagvalues.FlagHolder[int]:
642 ...
645def DEFINE_integer( # pylint: disable=invalid-name
646 name,
647 default,
648 help, # pylint: disable=redefined-builtin
649 lower_bound=None,
650 upper_bound=None,
651 flag_values=_flagvalues.FLAGS,
652 required=False,
653 **args
654):
655 """Registers a flag whose value must be an integer.
657 If ``lower_bound``, or ``upper_bound`` are set, then this flag must be
658 within the given range.
660 Args:
661 name: str, the flag name.
662 default: int|str|None, the default value of the flag.
663 help: str, the help message.
664 lower_bound: int, min value of the flag.
665 upper_bound: int, max value of the flag.
666 flag_values: :class:`FlagValues`, the FlagValues instance with which the
667 flag will be registered. This should almost never need to be overridden.
668 required: bool, is this a required flag. This must be used as a keyword
669 argument.
670 **args: dict, the extra keyword args that are passed to :func:`DEFINE`.
672 Returns:
673 a handle to defined flag.
674 """
675 parser = _argument_parser.IntegerParser(lower_bound, upper_bound)
676 serializer = _argument_parser.ArgumentSerializer()
677 result = DEFINE(
678 parser,
679 name,
680 default,
681 help, # pylint: disable=redefined-builtin
682 flag_values,
683 serializer,
684 required=True if required else False,
685 **args,
686 )
687 _register_bounds_validator_if_needed(parser, name, flag_values=flag_values)
688 return result
691@overload
692def DEFINE_enum( # pylint: disable=invalid-name
693 name: str,
694 default: Optional[str],
695 enum_values: Iterable[str],
696 help: Optional[str], # pylint: disable=redefined-builtin
697 flag_values: _flagvalues.FlagValues = ...,
698 module_name: Optional[str] = ...,
699 *,
700 required: Literal[True],
701 **args: Any
702) -> _flagvalues.FlagHolder[str]:
703 ...
706@overload
707def DEFINE_enum( # pylint: disable=invalid-name
708 name: str,
709 default: None,
710 enum_values: Iterable[str],
711 help: Optional[str], # pylint: disable=redefined-builtin
712 flag_values: _flagvalues.FlagValues = ...,
713 module_name: Optional[str] = ...,
714 required: bool = ...,
715 **args: Any
716) -> _flagvalues.FlagHolder[Optional[str]]:
717 ...
720@overload
721def DEFINE_enum( # pylint: disable=invalid-name
722 name: str,
723 default: str,
724 enum_values: Iterable[str],
725 help: Optional[str], # pylint: disable=redefined-builtin
726 flag_values: _flagvalues.FlagValues = ...,
727 module_name: Optional[str] = ...,
728 required: bool = ...,
729 **args: Any
730) -> _flagvalues.FlagHolder[str]:
731 ...
734def DEFINE_enum( # pylint: disable=invalid-name
735 name,
736 default,
737 enum_values,
738 help, # pylint: disable=redefined-builtin
739 flag_values=_flagvalues.FLAGS,
740 module_name=None,
741 required=False,
742 **args
743):
744 """Registers a flag whose value can be any string from enum_values.
746 Instead of a string enum, prefer `DEFINE_enum_class`, which allows
747 defining enums from an `enum.Enum` class.
749 Args:
750 name: str, the flag name.
751 default: str|None, the default value of the flag.
752 enum_values: [str], a non-empty list of strings with the possible values for
753 the flag.
754 help: str, the help message.
755 flag_values: :class:`FlagValues`, the FlagValues instance with which the
756 flag will be registered. This should almost never need to be overridden.
757 module_name: str, the name of the Python module declaring this flag. If not
758 provided, it will be computed using the stack trace of this call.
759 required: bool, is this a required flag. This must be used as a keyword
760 argument.
761 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
763 Returns:
764 a handle to defined flag.
765 """
766 result = DEFINE_flag(
767 _flag.EnumFlag(name, default, help, enum_values, **args),
768 flag_values,
769 module_name,
770 required=True if required else False,
771 )
772 return result
775@overload
776def DEFINE_enum_class( # pylint: disable=invalid-name
777 name: str,
778 default: Union[None, _ET, str],
779 enum_class: Type[_ET],
780 help: Optional[str], # pylint: disable=redefined-builtin
781 flag_values: _flagvalues.FlagValues = ...,
782 module_name: Optional[str] = ...,
783 case_sensitive: bool = ...,
784 *,
785 required: Literal[True],
786 **args: Any
787) -> _flagvalues.FlagHolder[_ET]:
788 ...
791@overload
792def DEFINE_enum_class( # pylint: disable=invalid-name
793 name: str,
794 default: None,
795 enum_class: Type[_ET],
796 help: Optional[str], # pylint: disable=redefined-builtin
797 flag_values: _flagvalues.FlagValues = ...,
798 module_name: Optional[str] = ...,
799 case_sensitive: bool = ...,
800 required: bool = ...,
801 **args: Any
802) -> _flagvalues.FlagHolder[Optional[_ET]]:
803 ...
806@overload
807def DEFINE_enum_class( # pylint: disable=invalid-name
808 name: str,
809 default: Union[_ET, str],
810 enum_class: Type[_ET],
811 help: Optional[str], # pylint: disable=redefined-builtin
812 flag_values: _flagvalues.FlagValues = ...,
813 module_name: Optional[str] = ...,
814 case_sensitive: bool = ...,
815 required: bool = ...,
816 **args: Any
817) -> _flagvalues.FlagHolder[_ET]:
818 ...
821def DEFINE_enum_class( # pylint: disable=invalid-name
822 name,
823 default,
824 enum_class,
825 help, # pylint: disable=redefined-builtin
826 flag_values=_flagvalues.FLAGS,
827 module_name=None,
828 case_sensitive=False,
829 required=False,
830 **args
831):
832 """Registers a flag whose value can be the name of enum members.
834 Args:
835 name: str, the flag name.
836 default: Enum|str|None, the default value of the flag.
837 enum_class: class, the Enum class with all the possible values for the flag.
838 help: str, the help message.
839 flag_values: :class:`FlagValues`, the FlagValues instance with which the
840 flag will be registered. This should almost never need to be overridden.
841 module_name: str, the name of the Python module declaring this flag. If not
842 provided, it will be computed using the stack trace of this call.
843 case_sensitive: bool, whether to map strings to members of the enum_class
844 without considering case.
845 required: bool, is this a required flag. This must be used as a keyword
846 argument.
847 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
849 Returns:
850 a handle to defined flag.
851 """
852 # NOTE: pytype fails if this is a direct return.
853 result = DEFINE_flag(
854 _flag.EnumClassFlag(
855 name, default, help, enum_class, case_sensitive=case_sensitive, **args
856 ),
857 flag_values,
858 module_name,
859 required=True if required else False,
860 )
861 return result
864@overload
865def DEFINE_list( # pylint: disable=invalid-name
866 name: str,
867 default: Union[None, Iterable[str], str],
868 help: str, # pylint: disable=redefined-builtin
869 flag_values: _flagvalues.FlagValues = ...,
870 *,
871 required: Literal[True],
872 **args: Any
873) -> _flagvalues.FlagHolder[List[str]]:
874 ...
877@overload
878def DEFINE_list( # pylint: disable=invalid-name
879 name: str,
880 default: None,
881 help: str, # pylint: disable=redefined-builtin
882 flag_values: _flagvalues.FlagValues = ...,
883 required: bool = ...,
884 **args: Any
885) -> _flagvalues.FlagHolder[Optional[List[str]]]:
886 ...
889@overload
890def DEFINE_list( # pylint: disable=invalid-name
891 name: str,
892 default: Union[Iterable[str], str],
893 help: str, # pylint: disable=redefined-builtin
894 flag_values: _flagvalues.FlagValues = ...,
895 required: bool = ...,
896 **args: Any
897) -> _flagvalues.FlagHolder[List[str]]:
898 ...
901def DEFINE_list( # pylint: disable=invalid-name
902 name,
903 default,
904 help, # pylint: disable=redefined-builtin
905 flag_values=_flagvalues.FLAGS,
906 required=False,
907 **args
908):
909 """Registers a flag whose value is a comma-separated list of strings.
911 The flag value is parsed with a CSV parser.
913 Args:
914 name: str, the flag name.
915 default: list|str|None, the default value of the flag.
916 help: str, the help message.
917 flag_values: :class:`FlagValues`, the FlagValues instance with which the
918 flag will be registered. This should almost never need to be overridden.
919 required: bool, is this a required flag. This must be used as a keyword
920 argument.
921 **args: Dictionary with extra keyword args that are passed to the
922 ``Flag.__init__``.
924 Returns:
925 a handle to defined flag.
926 """
927 parser = _argument_parser.ListParser()
928 serializer = _argument_parser.CsvListSerializer(',')
929 return DEFINE(
930 parser,
931 name,
932 default,
933 help,
934 flag_values,
935 serializer,
936 required=True if required else False,
937 **args,
938 )
941@overload
942def DEFINE_spaceseplist( # pylint: disable=invalid-name
943 name: str,
944 default: Union[None, Iterable[str], str],
945 help: str, # pylint: disable=redefined-builtin
946 comma_compat: bool = ...,
947 flag_values: _flagvalues.FlagValues = ...,
948 *,
949 required: Literal[True],
950 **args: Any
951) -> _flagvalues.FlagHolder[List[str]]:
952 ...
955@overload
956def DEFINE_spaceseplist( # pylint: disable=invalid-name
957 name: str,
958 default: None,
959 help: str, # pylint: disable=redefined-builtin
960 comma_compat: bool = ...,
961 flag_values: _flagvalues.FlagValues = ...,
962 required: bool = ...,
963 **args: Any
964) -> _flagvalues.FlagHolder[Optional[List[str]]]:
965 ...
968@overload
969def DEFINE_spaceseplist( # pylint: disable=invalid-name
970 name: str,
971 default: Union[Iterable[str], str],
972 help: str, # pylint: disable=redefined-builtin
973 comma_compat: bool = ...,
974 flag_values: _flagvalues.FlagValues = ...,
975 required: bool = ...,
976 **args: Any
977) -> _flagvalues.FlagHolder[List[str]]:
978 ...
981def DEFINE_spaceseplist( # pylint: disable=invalid-name
982 name,
983 default,
984 help, # pylint: disable=redefined-builtin
985 comma_compat=False,
986 flag_values=_flagvalues.FLAGS,
987 required=False,
988 **args
989):
990 """Registers a flag whose value is a whitespace-separated list of strings.
992 Any whitespace can be used as a separator.
994 Args:
995 name: str, the flag name.
996 default: list|str|None, the default value of the flag.
997 help: str, the help message.
998 comma_compat: bool - Whether to support comma as an additional separator. If
999 false then only whitespace is supported. This is intended only for
1000 backwards compatibility with flags that used to be comma-separated.
1001 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1002 flag will be registered. This should almost never need to be overridden.
1003 required: bool, is this a required flag. This must be used as a keyword
1004 argument.
1005 **args: Dictionary with extra keyword args that are passed to the
1006 ``Flag.__init__``.
1008 Returns:
1009 a handle to defined flag.
1010 """
1011 parser = _argument_parser.WhitespaceSeparatedListParser(
1012 comma_compat=comma_compat)
1013 serializer = _argument_parser.ListSerializer(' ')
1014 return DEFINE(
1015 parser,
1016 name,
1017 default,
1018 help,
1019 flag_values,
1020 serializer,
1021 required=True if required else False,
1022 **args,
1023 )
1026@overload
1027def DEFINE_multi( # pylint: disable=invalid-name
1028 parser: _argument_parser.ArgumentParser[_T],
1029 serializer: _argument_parser.ArgumentSerializer[_T],
1030 name: str,
1031 default: Iterable[_T],
1032 help: str, # pylint: disable=redefined-builtin
1033 flag_values: _flagvalues.FlagValues = ...,
1034 module_name: Optional[str] = ...,
1035 *,
1036 required: Literal[True],
1037 **args: Any
1038) -> _flagvalues.FlagHolder[List[_T]]:
1039 ...
1042@overload
1043def DEFINE_multi( # pylint: disable=invalid-name
1044 parser: _argument_parser.ArgumentParser[_T],
1045 serializer: _argument_parser.ArgumentSerializer[_T],
1046 name: str,
1047 default: Union[None, _T],
1048 help: str, # pylint: disable=redefined-builtin
1049 flag_values: _flagvalues.FlagValues = ...,
1050 module_name: Optional[str] = ...,
1051 *,
1052 required: Literal[True],
1053 **args: Any
1054) -> _flagvalues.FlagHolder[List[_T]]:
1055 ...
1058@overload
1059def DEFINE_multi( # pylint: disable=invalid-name
1060 parser: _argument_parser.ArgumentParser[_T],
1061 serializer: _argument_parser.ArgumentSerializer[_T],
1062 name: str,
1063 default: None,
1064 help: str, # pylint: disable=redefined-builtin
1065 flag_values: _flagvalues.FlagValues = ...,
1066 module_name: Optional[str] = ...,
1067 required: bool = ...,
1068 **args: Any
1069) -> _flagvalues.FlagHolder[Optional[List[_T]]]:
1070 ...
1073@overload
1074def DEFINE_multi( # pylint: disable=invalid-name
1075 parser: _argument_parser.ArgumentParser[_T],
1076 serializer: _argument_parser.ArgumentSerializer[_T],
1077 name: str,
1078 default: Iterable[_T],
1079 help: str, # pylint: disable=redefined-builtin
1080 flag_values: _flagvalues.FlagValues = ...,
1081 module_name: Optional[str] = ...,
1082 required: bool = ...,
1083 **args: Any
1084) -> _flagvalues.FlagHolder[List[_T]]:
1085 ...
1088@overload
1089def DEFINE_multi( # pylint: disable=invalid-name
1090 parser: _argument_parser.ArgumentParser[_T],
1091 serializer: _argument_parser.ArgumentSerializer[_T],
1092 name: str,
1093 default: _T,
1094 help: str, # pylint: disable=redefined-builtin
1095 flag_values: _flagvalues.FlagValues = ...,
1096 module_name: Optional[str] = ...,
1097 required: bool = ...,
1098 **args: Any
1099) -> _flagvalues.FlagHolder[List[_T]]:
1100 ...
1103def DEFINE_multi( # pylint: disable=invalid-name
1104 parser,
1105 serializer,
1106 name,
1107 default,
1108 help, # pylint: disable=redefined-builtin
1109 flag_values=_flagvalues.FLAGS,
1110 module_name=None,
1111 required=False,
1112 **args
1113):
1114 """Registers a generic MultiFlag that parses its args with a given parser.
1116 Auxiliary function. Normal users should NOT use it directly.
1118 Developers who need to create their own 'Parser' classes for options
1119 which can appear multiple times can call this module function to
1120 register their flags.
1122 Args:
1123 parser: ArgumentParser, used to parse the flag arguments.
1124 serializer: ArgumentSerializer, the flag serializer instance.
1125 name: str, the flag name.
1126 default: Union[Iterable[T], str, None], the default value of the flag. If
1127 the value is text, it will be parsed as if it was provided from the
1128 command line. If the value is a non-string iterable, it will be iterated
1129 over to create a shallow copy of the values. If it is None, it is left
1130 as-is.
1131 help: str, the help message.
1132 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1133 flag will be registered. This should almost never need to be overridden.
1134 module_name: A string, the name of the Python module declaring this flag. If
1135 not provided, it will be computed using the stack trace of this call.
1136 required: bool, is this a required flag. This must be used as a keyword
1137 argument.
1138 **args: Dictionary with extra keyword args that are passed to the
1139 ``Flag.__init__``.
1141 Returns:
1142 a handle to defined flag.
1143 """
1144 result = DEFINE_flag(
1145 _flag.MultiFlag(parser, serializer, name, default, help, **args),
1146 flag_values,
1147 module_name,
1148 required=True if required else False,
1149 )
1150 return result
1153@overload
1154def DEFINE_multi_string( # pylint: disable=invalid-name
1155 name: str,
1156 default: Union[None, Iterable[str], str],
1157 help: str, # pylint: disable=redefined-builtin
1158 flag_values: _flagvalues.FlagValues = ...,
1159 *,
1160 required: Literal[True],
1161 **args: Any
1162) -> _flagvalues.FlagHolder[List[str]]:
1163 ...
1166@overload
1167def DEFINE_multi_string( # pylint: disable=invalid-name
1168 name: str,
1169 default: None,
1170 help: str, # pylint: disable=redefined-builtin
1171 flag_values: _flagvalues.FlagValues = ...,
1172 required: bool = ...,
1173 **args: Any
1174) -> _flagvalues.FlagHolder[Optional[List[str]]]:
1175 ...
1178@overload
1179def DEFINE_multi_string( # pylint: disable=invalid-name
1180 name: str,
1181 default: Union[Iterable[str], str],
1182 help: str, # pylint: disable=redefined-builtin
1183 flag_values: _flagvalues.FlagValues = ...,
1184 required: bool = ...,
1185 **args: Any
1186) -> _flagvalues.FlagHolder[List[str]]:
1187 ...
1190def DEFINE_multi_string( # pylint: disable=invalid-name
1191 name,
1192 default,
1193 help, # pylint: disable=redefined-builtin
1194 flag_values=_flagvalues.FLAGS,
1195 required=False,
1196 **args
1197):
1198 """Registers a flag whose value can be a list of any strings.
1200 Use the flag on the command line multiple times to place multiple
1201 string values into the list. The 'default' may be a single string
1202 (which will be converted into a single-element list) or a list of
1203 strings.
1206 Args:
1207 name: str, the flag name.
1208 default: Union[Iterable[str], str, None], the default value of the flag; see
1209 :func:`DEFINE_multi`.
1210 help: str, the help message.
1211 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1212 flag will be registered. This should almost never need to be overridden.
1213 required: bool, is this a required flag. This must be used as a keyword
1214 argument.
1215 **args: Dictionary with extra keyword args that are passed to the
1216 ``Flag.__init__``.
1218 Returns:
1219 a handle to defined flag.
1220 """
1221 parser = _argument_parser.ArgumentParser()
1222 serializer = _argument_parser.ArgumentSerializer()
1223 return DEFINE_multi(
1224 parser,
1225 serializer,
1226 name,
1227 default,
1228 help, # pylint: disable=redefined-builtin
1229 flag_values,
1230 required=True if required else False,
1231 **args,
1232 )
1235@overload
1236def DEFINE_multi_integer( # pylint: disable=invalid-name
1237 name: str,
1238 default: Union[None, Iterable[int], int, str],
1239 help: str, # pylint: disable=redefined-builtin
1240 lower_bound: Optional[int] = ...,
1241 upper_bound: Optional[int] = ...,
1242 flag_values: _flagvalues.FlagValues = ...,
1243 *,
1244 required: Literal[True],
1245 **args: Any
1246) -> _flagvalues.FlagHolder[List[int]]:
1247 ...
1250@overload
1251def DEFINE_multi_integer( # pylint: disable=invalid-name
1252 name: str,
1253 default: None,
1254 help: str, # pylint: disable=redefined-builtin
1255 lower_bound: Optional[int] = ...,
1256 upper_bound: Optional[int] = ...,
1257 flag_values: _flagvalues.FlagValues = ...,
1258 required: bool = ...,
1259 **args: Any
1260) -> _flagvalues.FlagHolder[Optional[List[int]]]:
1261 ...
1264@overload
1265def DEFINE_multi_integer( # pylint: disable=invalid-name
1266 name: str,
1267 default: Union[Iterable[int], int, str],
1268 help: str, # pylint: disable=redefined-builtin
1269 lower_bound: Optional[int] = ...,
1270 upper_bound: Optional[int] = ...,
1271 flag_values: _flagvalues.FlagValues = ...,
1272 required: bool = ...,
1273 **args: Any
1274) -> _flagvalues.FlagHolder[List[int]]:
1275 ...
1278def DEFINE_multi_integer( # pylint: disable=invalid-name
1279 name,
1280 default,
1281 help, # pylint: disable=redefined-builtin
1282 lower_bound=None,
1283 upper_bound=None,
1284 flag_values=_flagvalues.FLAGS,
1285 required=False,
1286 **args
1287):
1288 """Registers a flag whose value can be a list of arbitrary integers.
1290 Use the flag on the command line multiple times to place multiple
1291 integer values into the list. The 'default' may be a single integer
1292 (which will be converted into a single-element list) or a list of
1293 integers.
1295 Args:
1296 name: str, the flag name.
1297 default: Union[Iterable[int], str, None], the default value of the flag; see
1298 `DEFINE_multi`.
1299 help: str, the help message.
1300 lower_bound: int, min values of the flag.
1301 upper_bound: int, max values of the flag.
1302 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1303 flag will be registered. This should almost never need to be overridden.
1304 required: bool, is this a required flag. This must be used as a keyword
1305 argument.
1306 **args: Dictionary with extra keyword args that are passed to the
1307 ``Flag.__init__``.
1309 Returns:
1310 a handle to defined flag.
1311 """
1312 parser = _argument_parser.IntegerParser(lower_bound, upper_bound)
1313 serializer = _argument_parser.ArgumentSerializer()
1314 return DEFINE_multi(
1315 parser,
1316 serializer,
1317 name,
1318 default,
1319 help, # pylint: disable=redefined-builtin
1320 flag_values,
1321 required=True if required else False,
1322 **args,
1323 )
1326@overload
1327def DEFINE_multi_float( # pylint: disable=invalid-name
1328 name: str,
1329 default: Union[None, Iterable[float], float, str],
1330 help: str, # pylint: disable=redefined-builtin
1331 lower_bound: Optional[float] = ...,
1332 upper_bound: Optional[float] = ...,
1333 flag_values: _flagvalues.FlagValues = ...,
1334 *,
1335 required: Literal[True],
1336 **args: Any
1337) -> _flagvalues.FlagHolder[List[float]]:
1338 ...
1341@overload
1342def DEFINE_multi_float( # pylint: disable=invalid-name
1343 name: str,
1344 default: None,
1345 help: str, # pylint: disable=redefined-builtin
1346 lower_bound: Optional[float] = ...,
1347 upper_bound: Optional[float] = ...,
1348 flag_values: _flagvalues.FlagValues = ...,
1349 required: bool = ...,
1350 **args: Any
1351) -> _flagvalues.FlagHolder[Optional[List[float]]]:
1352 ...
1355@overload
1356def DEFINE_multi_float( # pylint: disable=invalid-name
1357 name: str,
1358 default: Union[Iterable[float], float, str],
1359 help: str, # pylint: disable=redefined-builtin
1360 lower_bound: Optional[float] = ...,
1361 upper_bound: Optional[float] = ...,
1362 flag_values: _flagvalues.FlagValues = ...,
1363 required: bool = ...,
1364 **args: Any
1365) -> _flagvalues.FlagHolder[List[float]]:
1366 ...
1369def DEFINE_multi_float( # pylint: disable=invalid-name
1370 name,
1371 default,
1372 help, # pylint: disable=redefined-builtin
1373 lower_bound=None,
1374 upper_bound=None,
1375 flag_values=_flagvalues.FLAGS,
1376 required=False,
1377 **args
1378):
1379 """Registers a flag whose value can be a list of arbitrary floats.
1381 Use the flag on the command line multiple times to place multiple
1382 float values into the list. The 'default' may be a single float
1383 (which will be converted into a single-element list) or a list of
1384 floats.
1386 Args:
1387 name: str, the flag name.
1388 default: Union[Iterable[float], str, None], the default value of the flag;
1389 see `DEFINE_multi`.
1390 help: str, the help message.
1391 lower_bound: float, min values of the flag.
1392 upper_bound: float, max values of the flag.
1393 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1394 flag will be registered. This should almost never need to be overridden.
1395 required: bool, is this a required flag. This must be used as a keyword
1396 argument.
1397 **args: Dictionary with extra keyword args that are passed to the
1398 ``Flag.__init__``.
1400 Returns:
1401 a handle to defined flag.
1402 """
1403 parser = _argument_parser.FloatParser(lower_bound, upper_bound)
1404 serializer = _argument_parser.ArgumentSerializer()
1405 return DEFINE_multi(
1406 parser,
1407 serializer,
1408 name,
1409 default,
1410 help,
1411 flag_values,
1412 required=True if required else False,
1413 **args,
1414 )
1417@overload
1418def DEFINE_multi_enum( # pylint: disable=invalid-name
1419 name: str,
1420 default: Union[None, Iterable[str], str],
1421 enum_values: Iterable[str],
1422 help: str, # pylint: disable=redefined-builtin
1423 flag_values: _flagvalues.FlagValues = ...,
1424 *,
1425 required: Literal[True],
1426 **args: Any
1427) -> _flagvalues.FlagHolder[List[str]]:
1428 ...
1431@overload
1432def DEFINE_multi_enum( # pylint: disable=invalid-name
1433 name: str,
1434 default: None,
1435 enum_values: Iterable[str],
1436 help: str, # pylint: disable=redefined-builtin
1437 flag_values: _flagvalues.FlagValues = ...,
1438 required: bool = ...,
1439 **args: Any
1440) -> _flagvalues.FlagHolder[Optional[List[str]]]:
1441 ...
1444@overload
1445def DEFINE_multi_enum( # pylint: disable=invalid-name
1446 name: str,
1447 default: Union[Iterable[str], str],
1448 enum_values: Iterable[str],
1449 help: str, # pylint: disable=redefined-builtin
1450 flag_values: _flagvalues.FlagValues = ...,
1451 required: bool = ...,
1452 **args: Any
1453) -> _flagvalues.FlagHolder[List[str]]:
1454 ...
1457def DEFINE_multi_enum( # pylint: disable=invalid-name
1458 name,
1459 default,
1460 enum_values,
1461 help, # pylint: disable=redefined-builtin
1462 flag_values=_flagvalues.FLAGS,
1463 case_sensitive=True,
1464 required=False,
1465 **args
1466):
1467 """Registers a flag whose value can be a list strings from enum_values.
1469 Use the flag on the command line multiple times to place multiple
1470 enum values into the list. The 'default' may be a single string
1471 (which will be converted into a single-element list) or a list of
1472 strings.
1474 Args:
1475 name: str, the flag name.
1476 default: Union[Iterable[str], str, None], the default value of the flag; see
1477 `DEFINE_multi`.
1478 enum_values: [str], a non-empty list of strings with the possible values for
1479 the flag.
1480 help: str, the help message.
1481 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1482 flag will be registered. This should almost never need to be overridden.
1483 case_sensitive: Whether or not the enum is to be case-sensitive.
1484 required: bool, is this a required flag. This must be used as a keyword
1485 argument.
1486 **args: Dictionary with extra keyword args that are passed to the
1487 ``Flag.__init__``.
1489 Returns:
1490 a handle to defined flag.
1491 """
1492 parser = _argument_parser.EnumParser(enum_values, case_sensitive)
1493 serializer = _argument_parser.ArgumentSerializer()
1494 return DEFINE_multi(
1495 parser,
1496 serializer,
1497 name,
1498 default,
1499 '<%s>: %s' % ('|'.join(enum_values), help),
1500 flag_values,
1501 required=True if required else False,
1502 **args,
1503 )
1506@overload
1507def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1508 name: str,
1509 # This is separate from `Union[None, _ET, Iterable[str], str]` to avoid a
1510 # Pytype issue inferring the return value to
1511 # FlagHolder[List[Union[_ET, enum.Enum]]] when an iterable of concrete enum
1512 # subclasses are used.
1513 default: Iterable[_ET],
1514 enum_class: Type[_ET],
1515 help: str, # pylint: disable=redefined-builtin
1516 flag_values: _flagvalues.FlagValues = ...,
1517 module_name: Optional[str] = ...,
1518 *,
1519 required: Literal[True],
1520 **args: Any
1521) -> _flagvalues.FlagHolder[List[_ET]]:
1522 ...
1525@overload
1526def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1527 name: str,
1528 default: Union[None, _ET, Iterable[str], str],
1529 enum_class: Type[_ET],
1530 help: str, # pylint: disable=redefined-builtin
1531 flag_values: _flagvalues.FlagValues = ...,
1532 module_name: Optional[str] = ...,
1533 *,
1534 required: Literal[True],
1535 **args: Any
1536) -> _flagvalues.FlagHolder[List[_ET]]:
1537 ...
1540@overload
1541def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1542 name: str,
1543 default: None,
1544 enum_class: Type[_ET],
1545 help: str, # pylint: disable=redefined-builtin
1546 flag_values: _flagvalues.FlagValues = ...,
1547 module_name: Optional[str] = ...,
1548 required: bool = ...,
1549 **args: Any
1550) -> _flagvalues.FlagHolder[Optional[List[_ET]]]:
1551 ...
1554@overload
1555def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1556 name: str,
1557 # This is separate from `Union[None, _ET, Iterable[str], str]` to avoid a
1558 # Pytype issue inferring the return value to
1559 # FlagHolder[List[Union[_ET, enum.Enum]]] when an iterable of concrete enum
1560 # subclasses are used.
1561 default: Iterable[_ET],
1562 enum_class: Type[_ET],
1563 help: str, # pylint: disable=redefined-builtin
1564 flag_values: _flagvalues.FlagValues = ...,
1565 module_name: Optional[str] = ...,
1566 required: bool = ...,
1567 **args: Any
1568) -> _flagvalues.FlagHolder[List[_ET]]:
1569 ...
1572@overload
1573def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1574 name: str,
1575 default: Union[_ET, Iterable[str], str],
1576 enum_class: Type[_ET],
1577 help: str, # pylint: disable=redefined-builtin
1578 flag_values: _flagvalues.FlagValues = ...,
1579 module_name: Optional[str] = ...,
1580 required: bool = ...,
1581 **args: Any
1582) -> _flagvalues.FlagHolder[List[_ET]]:
1583 ...
1586def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1587 name,
1588 default,
1589 enum_class,
1590 help, # pylint: disable=redefined-builtin
1591 flag_values=_flagvalues.FLAGS,
1592 module_name=None,
1593 case_sensitive=False,
1594 required=False,
1595 **args
1596):
1597 """Registers a flag whose value can be a list of enum members.
1599 Use the flag on the command line multiple times to place multiple
1600 enum values into the list.
1602 Args:
1603 name: str, the flag name.
1604 default: Union[Iterable[Enum], Iterable[str], Enum, str, None], the default
1605 value of the flag; see `DEFINE_multi`; only differences are documented
1606 here. If the value is a single Enum, it is treated as a single-item list
1607 of that Enum value. If it is an iterable, text values within the iterable
1608 will be converted to the equivalent Enum objects.
1609 enum_class: class, the Enum class with all the possible values for the flag.
1610 help: str, the help message.
1611 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1612 flag will be registered. This should almost never need to be overridden.
1613 module_name: A string, the name of the Python module declaring this flag. If
1614 not provided, it will be computed using the stack trace of this call.
1615 case_sensitive: bool, whether to map strings to members of the enum_class
1616 without considering case.
1617 required: bool, is this a required flag. This must be used as a keyword
1618 argument.
1619 **args: Dictionary with extra keyword args that are passed to the
1620 ``Flag.__init__``.
1622 Returns:
1623 a handle to defined flag.
1624 """
1625 # NOTE: pytype fails if this is a direct return.
1626 result = DEFINE_flag(
1627 _flag.MultiEnumClassFlag(
1628 name,
1629 default,
1630 help,
1631 enum_class,
1632 case_sensitive=case_sensitive,
1633 **args,
1634 ),
1635 flag_values,
1636 module_name,
1637 required=True if required else False,
1638 )
1639 return result
1642def DEFINE_alias( # pylint: disable=invalid-name
1643 name: str,
1644 original_name: str,
1645 flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS,
1646 module_name: Optional[str] = None,
1647) -> _flagvalues.FlagHolder[Any]:
1648 """Defines an alias flag for an existing one.
1650 Args:
1651 name: str, the flag name.
1652 original_name: str, the original flag name.
1653 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1654 flag will be registered. This should almost never need to be overridden.
1655 module_name: A string, the name of the module that defines this flag.
1657 Returns:
1658 a handle to defined flag.
1660 Raises:
1661 flags.FlagError:
1662 UnrecognizedFlagError: if the referenced flag doesn't exist.
1663 DuplicateFlagError: if the alias name has been used by some existing flag.
1664 """
1665 if original_name not in flag_values:
1666 raise _exceptions.UnrecognizedFlagError(original_name)
1667 flag = flag_values[original_name]
1669 class _FlagAlias(_flag.Flag):
1670 """Overrides Flag class so alias value is copy of original flag value."""
1672 def parse(self, argument):
1673 flag.parse(argument)
1674 self.present += 1
1676 def _parse_from_default(self, value):
1677 # The value was already parsed by the aliased flag, so there is no
1678 # need to call the parser on it a second time.
1679 # Additionally, because of how MultiFlag parses and merges values,
1680 # it isn't possible to delegate to the aliased flag and still get
1681 # the correct values.
1682 return value
1684 @property
1685 def value(self):
1686 return flag.value
1688 @value.setter
1689 def value(self, value):
1690 flag.value = value
1692 help_msg = 'Alias for --%s.' % flag.name
1693 # If alias_name has been used, flags.DuplicatedFlag will be raised.
1694 return DEFINE_flag(
1695 _FlagAlias(
1696 flag.parser,
1697 flag.serializer,
1698 name,
1699 flag.default,
1700 help_msg,
1701 boolean=flag.boolean), flag_values, module_name)