Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/absl/flags/_defines.py: 63%
287 statements
« prev ^ index » next coverage.py v7.4.0, created at 2024-01-03 07:57 +0000
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
23import typing
24from typing import Text, List, Any, TypeVar, Optional, Union, Type, Iterable, overload
26from absl.flags import _argument_parser
27from absl.flags import _exceptions
28from absl.flags import _flag
29from absl.flags import _flagvalues
30from absl.flags import _helpers
31from absl.flags import _validators
33_helpers.disclaim_module_ids.add(id(sys.modules[__name__]))
35_T = TypeVar('_T')
36_ET = TypeVar('_ET', bound=enum.Enum)
39def _register_bounds_validator_if_needed(parser, name, flag_values):
40 """Enforces lower and upper bounds for numeric flags.
42 Args:
43 parser: NumericParser (either FloatParser or IntegerParser), provides lower
44 and upper bounds, and help text to display.
45 name: str, name of the flag
46 flag_values: FlagValues.
47 """
48 if parser.lower_bound is not None or parser.upper_bound is not None:
50 def checker(value):
51 if value is not None and parser.is_outside_bounds(value):
52 message = '%s is not %s' % (value, parser.syntactic_help)
53 raise _exceptions.ValidationError(message)
54 return True
56 _validators.register_validator(name, checker, flag_values=flag_values)
59@overload
60def DEFINE( # pylint: disable=invalid-name
61 parser: _argument_parser.ArgumentParser[_T],
62 name: Text,
63 default: Any,
64 help: Optional[Text], # pylint: disable=redefined-builtin
65 flag_values: _flagvalues.FlagValues = ...,
66 serializer: Optional[_argument_parser.ArgumentSerializer[_T]] = ...,
67 module_name: Optional[Text] = ...,
68 required: 'typing.Literal[True]' = ...,
69 **args: Any
70) -> _flagvalues.FlagHolder[_T]:
71 ...
74@overload
75def DEFINE( # pylint: disable=invalid-name
76 parser: _argument_parser.ArgumentParser[_T],
77 name: Text,
78 default: Optional[Any],
79 help: Optional[Text], # pylint: disable=redefined-builtin
80 flag_values: _flagvalues.FlagValues = ...,
81 serializer: Optional[_argument_parser.ArgumentSerializer[_T]] = ...,
82 module_name: Optional[Text] = ...,
83 required: bool = ...,
84 **args: Any
85) -> _flagvalues.FlagHolder[Optional[_T]]:
86 ...
89def DEFINE( # pylint: disable=invalid-name
90 parser,
91 name,
92 default,
93 help, # pylint: disable=redefined-builtin
94 flag_values=_flagvalues.FLAGS,
95 serializer=None,
96 module_name=None,
97 required=False,
98 **args):
99 """Registers a generic Flag object.
101 NOTE: in the docstrings of all DEFINE* functions, "registers" is short
102 for "creates a new flag and registers it".
104 Auxiliary function: clients should use the specialized ``DEFINE_<type>``
105 function instead.
107 Args:
108 parser: :class:`ArgumentParser`, used to parse the flag arguments.
109 name: str, the flag name.
110 default: The default value of the flag.
111 help: str, the help message.
112 flag_values: :class:`FlagValues`, the FlagValues instance with which the
113 flag will be registered. This should almost never need to be overridden.
114 serializer: :class:`ArgumentSerializer`, the flag serializer instance.
115 module_name: str, the name of the Python module declaring this flag. If not
116 provided, it will be computed using the stack trace of this call.
117 required: bool, is this a required flag. This must be used as a keyword
118 argument.
119 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
121 Returns:
122 a handle to defined flag.
123 """
124 return DEFINE_flag(
125 _flag.Flag(parser, serializer, name, default, help, **args),
126 flag_values,
127 module_name,
128 required=True if required else False,
129 )
132@overload
133def DEFINE_flag( # pylint: disable=invalid-name
134 flag: _flag.Flag[_T],
135 flag_values: _flagvalues.FlagValues = ...,
136 module_name: Optional[Text] = ...,
137 required: 'typing.Literal[True]' = ...,
138) -> _flagvalues.FlagHolder[_T]:
139 ...
142@overload
143def DEFINE_flag( # pylint: disable=invalid-name
144 flag: _flag.Flag[_T],
145 flag_values: _flagvalues.FlagValues = ...,
146 module_name: Optional[Text] = ...,
147 required: bool = ...,
148) -> _flagvalues.FlagHolder[Optional[_T]]:
149 ...
152def DEFINE_flag( # pylint: disable=invalid-name
153 flag,
154 flag_values=_flagvalues.FLAGS,
155 module_name=None,
156 required=False):
157 """Registers a :class:`Flag` object with a :class:`FlagValues` object.
159 By default, the global :const:`FLAGS` ``FlagValue`` object is used.
161 Typical users will use one of the more specialized DEFINE_xxx
162 functions, such as :func:`DEFINE_string` or :func:`DEFINE_integer`. But
163 developers who need to create :class:`Flag` objects themselves should use
164 this function to register their flags.
166 Args:
167 flag: :class:`Flag`, a flag that is key to the module.
168 flag_values: :class:`FlagValues`, the ``FlagValues`` instance with which the
169 flag will be registered. This should almost never need to be overridden.
170 module_name: str, the name of the Python module declaring this flag. If not
171 provided, it will be computed using the stack trace of this call.
172 required: bool, is this a required flag. This must be used as a keyword
173 argument.
175 Returns:
176 a handle to defined flag.
177 """
178 if required and flag.default is not None:
179 raise ValueError('Required flag --%s cannot have a non-None default' %
180 flag.name)
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 _internal_declare_key_flags(
216 flag_names: List[str],
217 flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS,
218 key_flag_values: Optional[_flagvalues.FlagValues] = None,
219) -> None:
220 """Declares a flag as key for the calling module.
222 Internal function. User code should call declare_key_flag or
223 adopt_module_key_flags instead.
225 Args:
226 flag_names: [str], a list of names of already-registered Flag objects.
227 flag_values: :class:`FlagValues`, the FlagValues instance with which the
228 flags listed in flag_names have registered (the value of the flag_values
229 argument from the ``DEFINE_*`` calls that defined those flags). This
230 should almost never need to be overridden.
231 key_flag_values: :class:`FlagValues`, the FlagValues instance that (among
232 possibly many other things) keeps track of the key flags for each module.
233 Default ``None`` means "same as flag_values". This should almost never
234 need to be overridden.
236 Raises:
237 UnrecognizedFlagError: Raised when the flag is not defined.
238 """
239 key_flag_values = key_flag_values or flag_values
241 module = _helpers.get_calling_module()
243 for flag_name in flag_names:
244 key_flag_values.register_key_flag_for_module(module, flag_values[flag_name])
247def declare_key_flag(
248 flag_name: Union[Text, _flagvalues.FlagHolder],
249 flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS,
250) -> None:
251 """Declares one flag as key to the current module.
253 Key flags are flags that are deemed really important for a module.
254 They are important when listing help messages; e.g., if the
255 --helpshort command-line flag is used, then only the key flags of the
256 main module are listed (instead of all flags, as in the case of
257 --helpfull).
259 Sample usage::
261 flags.declare_key_flag('flag_1')
263 Args:
264 flag_name: str | :class:`FlagHolder`, the name or holder of an already
265 declared flag. (Redeclaring flags as key, including flags implicitly key
266 because they were declared in this module, is a no-op.)
267 Positional-only parameter.
268 flag_values: :class:`FlagValues`, the FlagValues instance in which the
269 flag will be declared as a key flag. This should almost never need to be
270 overridden.
272 Raises:
273 ValueError: Raised if flag_name not defined as a Python flag.
274 """
275 flag_name, flag_values = _flagvalues.resolve_flag_ref(flag_name, flag_values)
276 if flag_name in _helpers.SPECIAL_FLAGS:
277 # Take care of the special flags, e.g., --flagfile, --undefok.
278 # These flags are defined in SPECIAL_FLAGS, and are treated
279 # specially during flag parsing, taking precedence over the
280 # user-defined flags.
281 _internal_declare_key_flags([flag_name],
282 flag_values=_helpers.SPECIAL_FLAGS,
283 key_flag_values=flag_values)
284 return
285 try:
286 _internal_declare_key_flags([flag_name], flag_values=flag_values)
287 except KeyError:
288 raise ValueError('Flag --%s is undefined. To set a flag as a key flag '
289 'first define it in Python.' % flag_name)
292def adopt_module_key_flags(
293 module: Any, flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS
294) -> None:
295 """Declares that all flags key to a module are key to the current module.
297 Args:
298 module: module, the module object from which all key flags will be declared
299 as key flags to the current module.
300 flag_values: :class:`FlagValues`, the FlagValues instance in which the
301 flags will be declared as key flags. This should almost never need to be
302 overridden.
304 Raises:
305 Error: Raised when given an argument that is a module name (a string),
306 instead of a module object.
307 """
308 if not isinstance(module, types.ModuleType):
309 raise _exceptions.Error('Expected a module object, not %r.' % (module,))
310 _internal_declare_key_flags(
311 [f.name for f in flag_values.get_key_flags_for_module(module.__name__)],
312 flag_values=flag_values)
313 # If module is this flag module, take _helpers.SPECIAL_FLAGS into account.
314 if module == _helpers.FLAGS_MODULE:
315 _internal_declare_key_flags(
316 # As we associate flags with get_calling_module_object_and_name(), the
317 # special flags defined in this module are incorrectly registered with
318 # a different module. So, we can't use get_key_flags_for_module.
319 # Instead, we take all flags from _helpers.SPECIAL_FLAGS (a private
320 # FlagValues, where no other module should register flags).
321 [_helpers.SPECIAL_FLAGS[name].name for name in _helpers.SPECIAL_FLAGS],
322 flag_values=_helpers.SPECIAL_FLAGS,
323 key_flag_values=flag_values)
326def disclaim_key_flags() -> None:
327 """Declares that the current module will not define any more key flags.
329 Normally, the module that calls the DEFINE_xxx functions claims the
330 flag to be its key flag. This is undesirable for modules that
331 define additional DEFINE_yyy functions with its own flag parsers and
332 serializers, since that module will accidentally claim flags defined
333 by DEFINE_yyy as its key flags. After calling this function, the
334 module disclaims flag definitions thereafter, so the key flags will
335 be correctly attributed to the caller of DEFINE_yyy.
337 After calling this function, the module will not be able to define
338 any more flags. This function will affect all FlagValues objects.
339 """
340 globals_for_caller = sys._getframe(1).f_globals # pylint: disable=protected-access
341 module, _ = _helpers.get_module_object_and_name(globals_for_caller)
342 _helpers.disclaim_module_ids.add(id(module))
345@overload
346def DEFINE_string( # pylint: disable=invalid-name
347 name: Text,
348 default: Optional[Text],
349 help: Optional[Text], # pylint: disable=redefined-builtin
350 flag_values: _flagvalues.FlagValues = ...,
351 *,
352 required: 'typing.Literal[True]',
353 **args: Any
354) -> _flagvalues.FlagHolder[Text]:
355 ...
358@overload
359def DEFINE_string( # pylint: disable=invalid-name
360 name: Text,
361 default: None,
362 help: Optional[Text], # pylint: disable=redefined-builtin
363 flag_values: _flagvalues.FlagValues = ...,
364 required: bool = ...,
365 **args: Any
366) -> _flagvalues.FlagHolder[Optional[Text]]:
367 ...
370@overload
371def DEFINE_string( # pylint: disable=invalid-name
372 name: Text,
373 default: Text,
374 help: Optional[Text], # pylint: disable=redefined-builtin
375 flag_values: _flagvalues.FlagValues = ...,
376 required: bool = ...,
377 **args: Any
378) -> _flagvalues.FlagHolder[Text]:
379 ...
382def DEFINE_string( # pylint: disable=invalid-name,redefined-builtin
383 name,
384 default,
385 help,
386 flag_values=_flagvalues.FLAGS,
387 required=False,
388 **args):
389 """Registers a flag whose value can be any string."""
390 parser = _argument_parser.ArgumentParser[str]()
391 serializer = _argument_parser.ArgumentSerializer[str]()
392 return DEFINE(
393 parser,
394 name,
395 default,
396 help,
397 flag_values,
398 serializer,
399 required=True if required else False,
400 **args,
401 )
404@overload
405def DEFINE_boolean( # pylint: disable=invalid-name
406 name: Text,
407 default: Union[None, Text, bool, int],
408 help: Optional[Text], # pylint: disable=redefined-builtin
409 flag_values: _flagvalues.FlagValues = ...,
410 module_name: Optional[Text] = ...,
411 *,
412 required: 'typing.Literal[True]',
413 **args: Any
414) -> _flagvalues.FlagHolder[bool]:
415 ...
418@overload
419def DEFINE_boolean( # pylint: disable=invalid-name
420 name: Text,
421 default: None,
422 help: Optional[Text], # pylint: disable=redefined-builtin
423 flag_values: _flagvalues.FlagValues = ...,
424 module_name: Optional[Text] = ...,
425 required: bool = ...,
426 **args: Any
427) -> _flagvalues.FlagHolder[Optional[bool]]:
428 ...
431@overload
432def DEFINE_boolean( # pylint: disable=invalid-name
433 name: Text,
434 default: Union[Text, bool, int],
435 help: Optional[Text], # pylint: disable=redefined-builtin
436 flag_values: _flagvalues.FlagValues = ...,
437 module_name: Optional[Text] = ...,
438 required: bool = ...,
439 **args: Any
440) -> _flagvalues.FlagHolder[bool]:
441 ...
444def DEFINE_boolean( # pylint: disable=invalid-name,redefined-builtin
445 name,
446 default,
447 help,
448 flag_values=_flagvalues.FLAGS,
449 module_name=None,
450 required=False,
451 **args):
452 """Registers a boolean flag.
454 Such a boolean flag does not take an argument. If a user wants to
455 specify a false value explicitly, the long option beginning with 'no'
456 must be used: i.e. --noflag
458 This flag will have a value of None, True or False. None is possible
459 if default=None and the user does not specify the flag on the command
460 line.
462 Args:
463 name: str, the flag name.
464 default: bool|str|None, the default value of the flag.
465 help: str, the help message.
466 flag_values: :class:`FlagValues`, the FlagValues instance with which the
467 flag will be registered. This should almost never need to be overridden.
468 module_name: str, the name of the Python module declaring this flag. If not
469 provided, it will be computed using the stack trace of this call.
470 required: bool, is this a required flag. This must be used as a keyword
471 argument.
472 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
474 Returns:
475 a handle to defined flag.
476 """
477 return DEFINE_flag(
478 _flag.BooleanFlag(name, default, help, **args),
479 flag_values,
480 module_name,
481 required=True if required else False,
482 )
485@overload
486def DEFINE_float( # pylint: disable=invalid-name
487 name: Text,
488 default: Union[None, float, Text],
489 help: Optional[Text], # pylint: disable=redefined-builtin
490 lower_bound: Optional[float] = ...,
491 upper_bound: Optional[float] = ...,
492 flag_values: _flagvalues.FlagValues = ...,
493 *,
494 required: 'typing.Literal[True]',
495 **args: Any
496) -> _flagvalues.FlagHolder[float]:
497 ...
500@overload
501def DEFINE_float( # pylint: disable=invalid-name
502 name: Text,
503 default: None,
504 help: Optional[Text], # pylint: disable=redefined-builtin
505 lower_bound: Optional[float] = ...,
506 upper_bound: Optional[float] = ...,
507 flag_values: _flagvalues.FlagValues = ...,
508 required: bool = ...,
509 **args: Any
510) -> _flagvalues.FlagHolder[Optional[float]]:
511 ...
514@overload
515def DEFINE_float( # pylint: disable=invalid-name
516 name: Text,
517 default: Union[float, Text],
518 help: Optional[Text], # pylint: disable=redefined-builtin
519 lower_bound: Optional[float] = ...,
520 upper_bound: Optional[float] = ...,
521 flag_values: _flagvalues.FlagValues = ...,
522 required: bool = ...,
523 **args: Any
524) -> _flagvalues.FlagHolder[float]:
525 ...
528def DEFINE_float( # pylint: disable=invalid-name,redefined-builtin
529 name,
530 default,
531 help,
532 lower_bound=None,
533 upper_bound=None,
534 flag_values=_flagvalues.FLAGS,
535 required=False,
536 **args):
537 """Registers a flag whose value must be a float.
539 If ``lower_bound`` or ``upper_bound`` are set, then this flag must be
540 within the given range.
542 Args:
543 name: str, the flag name.
544 default: float|str|None, the default value of the flag.
545 help: str, the help message.
546 lower_bound: float, min value of the flag.
547 upper_bound: float, max value of the flag.
548 flag_values: :class:`FlagValues`, the FlagValues instance with which the
549 flag will be registered. This should almost never need to be overridden.
550 required: bool, is this a required flag. This must be used as a keyword
551 argument.
552 **args: dict, the extra keyword args that are passed to :func:`DEFINE`.
554 Returns:
555 a handle to defined flag.
556 """
557 parser = _argument_parser.FloatParser(lower_bound, upper_bound)
558 serializer = _argument_parser.ArgumentSerializer()
559 result = DEFINE(
560 parser,
561 name,
562 default,
563 help,
564 flag_values,
565 serializer,
566 required=True if required else False,
567 **args,
568 )
569 _register_bounds_validator_if_needed(parser, name, flag_values=flag_values)
570 return result
573@overload
574def DEFINE_integer( # pylint: disable=invalid-name
575 name: Text,
576 default: Union[None, int, Text],
577 help: Optional[Text], # pylint: disable=redefined-builtin
578 lower_bound: Optional[int] = ...,
579 upper_bound: Optional[int] = ...,
580 flag_values: _flagvalues.FlagValues = ...,
581 *,
582 required: 'typing.Literal[True]',
583 **args: Any
584) -> _flagvalues.FlagHolder[int]:
585 ...
588@overload
589def DEFINE_integer( # pylint: disable=invalid-name
590 name: Text,
591 default: None,
592 help: Optional[Text], # pylint: disable=redefined-builtin
593 lower_bound: Optional[int] = ...,
594 upper_bound: Optional[int] = ...,
595 flag_values: _flagvalues.FlagValues = ...,
596 required: bool = ...,
597 **args: Any
598) -> _flagvalues.FlagHolder[Optional[int]]:
599 ...
602@overload
603def DEFINE_integer( # pylint: disable=invalid-name
604 name: Text,
605 default: Union[int, Text],
606 help: Optional[Text], # pylint: disable=redefined-builtin
607 lower_bound: Optional[int] = ...,
608 upper_bound: Optional[int] = ...,
609 flag_values: _flagvalues.FlagValues = ...,
610 required: bool = ...,
611 **args: Any
612) -> _flagvalues.FlagHolder[int]:
613 ...
616def DEFINE_integer( # pylint: disable=invalid-name,redefined-builtin
617 name,
618 default,
619 help,
620 lower_bound=None,
621 upper_bound=None,
622 flag_values=_flagvalues.FLAGS,
623 required=False,
624 **args):
625 """Registers a flag whose value must be an integer.
627 If ``lower_bound``, or ``upper_bound`` are set, then this flag must be
628 within the given range.
630 Args:
631 name: str, the flag name.
632 default: int|str|None, the default value of the flag.
633 help: str, the help message.
634 lower_bound: int, min value of the flag.
635 upper_bound: int, max value of the flag.
636 flag_values: :class:`FlagValues`, the FlagValues instance with which the
637 flag will be registered. This should almost never need to be overridden.
638 required: bool, is this a required flag. This must be used as a keyword
639 argument.
640 **args: dict, the extra keyword args that are passed to :func:`DEFINE`.
642 Returns:
643 a handle to defined flag.
644 """
645 parser = _argument_parser.IntegerParser(lower_bound, upper_bound)
646 serializer = _argument_parser.ArgumentSerializer()
647 result = DEFINE(
648 parser,
649 name,
650 default,
651 help,
652 flag_values,
653 serializer,
654 required=True if required else False,
655 **args,
656 )
657 _register_bounds_validator_if_needed(parser, name, flag_values=flag_values)
658 return result
661@overload
662def DEFINE_enum( # pylint: disable=invalid-name
663 name: Text,
664 default: Optional[Text],
665 enum_values: Iterable[Text],
666 help: Optional[Text], # pylint: disable=redefined-builtin
667 flag_values: _flagvalues.FlagValues = ...,
668 module_name: Optional[Text] = ...,
669 *,
670 required: 'typing.Literal[True]',
671 **args: Any
672) -> _flagvalues.FlagHolder[Text]:
673 ...
676@overload
677def DEFINE_enum( # pylint: disable=invalid-name
678 name: Text,
679 default: None,
680 enum_values: Iterable[Text],
681 help: Optional[Text], # pylint: disable=redefined-builtin
682 flag_values: _flagvalues.FlagValues = ...,
683 module_name: Optional[Text] = ...,
684 required: bool = ...,
685 **args: Any
686) -> _flagvalues.FlagHolder[Optional[Text]]:
687 ...
690@overload
691def DEFINE_enum( # pylint: disable=invalid-name
692 name: Text,
693 default: Text,
694 enum_values: Iterable[Text],
695 help: Optional[Text], # pylint: disable=redefined-builtin
696 flag_values: _flagvalues.FlagValues = ...,
697 module_name: Optional[Text] = ...,
698 required: bool = ...,
699 **args: Any
700) -> _flagvalues.FlagHolder[Text]:
701 ...
704def DEFINE_enum( # pylint: disable=invalid-name,redefined-builtin
705 name,
706 default,
707 enum_values,
708 help,
709 flag_values=_flagvalues.FLAGS,
710 module_name=None,
711 required=False,
712 **args):
713 """Registers a flag whose value can be any string from enum_values.
715 Instead of a string enum, prefer `DEFINE_enum_class`, which allows
716 defining enums from an `enum.Enum` class.
718 Args:
719 name: str, the flag name.
720 default: str|None, the default value of the flag.
721 enum_values: [str], a non-empty list of strings with the possible values for
722 the flag.
723 help: str, the help message.
724 flag_values: :class:`FlagValues`, the FlagValues instance with which the
725 flag will be registered. This should almost never need to be overridden.
726 module_name: str, the name of the Python module declaring this flag. If not
727 provided, it will be computed using the stack trace of this call.
728 required: bool, is this a required flag. This must be used as a keyword
729 argument.
730 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
732 Returns:
733 a handle to defined flag.
734 """
735 result = DEFINE_flag(
736 _flag.EnumFlag(name, default, help, enum_values, **args),
737 flag_values,
738 module_name,
739 required=True if required else False,
740 )
741 return result
744@overload
745def DEFINE_enum_class( # pylint: disable=invalid-name
746 name: Text,
747 default: Union[None, _ET, Text],
748 enum_class: Type[_ET],
749 help: Optional[Text], # pylint: disable=redefined-builtin
750 flag_values: _flagvalues.FlagValues = ...,
751 module_name: Optional[Text] = ...,
752 case_sensitive: bool = ...,
753 *,
754 required: 'typing.Literal[True]',
755 **args: Any
756) -> _flagvalues.FlagHolder[_ET]:
757 ...
760@overload
761def DEFINE_enum_class( # pylint: disable=invalid-name
762 name: Text,
763 default: None,
764 enum_class: Type[_ET],
765 help: Optional[Text], # pylint: disable=redefined-builtin
766 flag_values: _flagvalues.FlagValues = ...,
767 module_name: Optional[Text] = ...,
768 case_sensitive: bool = ...,
769 required: bool = ...,
770 **args: Any
771) -> _flagvalues.FlagHolder[Optional[_ET]]:
772 ...
775@overload
776def DEFINE_enum_class( # pylint: disable=invalid-name
777 name: Text,
778 default: Union[_ET, Text],
779 enum_class: Type[_ET],
780 help: Optional[Text], # pylint: disable=redefined-builtin
781 flag_values: _flagvalues.FlagValues = ...,
782 module_name: Optional[Text] = ...,
783 case_sensitive: bool = ...,
784 required: bool = ...,
785 **args: Any
786) -> _flagvalues.FlagHolder[_ET]:
787 ...
790def DEFINE_enum_class( # pylint: disable=invalid-name,redefined-builtin
791 name,
792 default,
793 enum_class,
794 help,
795 flag_values=_flagvalues.FLAGS,
796 module_name=None,
797 case_sensitive=False,
798 required=False,
799 **args):
800 """Registers a flag whose value can be the name of enum members.
802 Args:
803 name: str, the flag name.
804 default: Enum|str|None, the default value of the flag.
805 enum_class: class, the Enum class with all the possible values for the flag.
806 help: str, the help message.
807 flag_values: :class:`FlagValues`, the FlagValues instance with which the
808 flag will be registered. This should almost never need to be overridden.
809 module_name: str, the name of the Python module declaring this flag. If not
810 provided, it will be computed using the stack trace of this call.
811 case_sensitive: bool, whether to map strings to members of the enum_class
812 without considering case.
813 required: bool, is this a required flag. This must be used as a keyword
814 argument.
815 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
817 Returns:
818 a handle to defined flag.
819 """
820 # NOTE: pytype fails if this is a direct return.
821 result = DEFINE_flag(
822 _flag.EnumClassFlag(
823 name, default, help, enum_class, case_sensitive=case_sensitive, **args
824 ),
825 flag_values,
826 module_name,
827 required=True if required else False,
828 )
829 return result
832@overload
833def DEFINE_list( # pylint: disable=invalid-name
834 name: Text,
835 default: Union[None, Iterable[Text], Text],
836 help: Text, # pylint: disable=redefined-builtin
837 flag_values: _flagvalues.FlagValues = ...,
838 *,
839 required: 'typing.Literal[True]',
840 **args: Any
841) -> _flagvalues.FlagHolder[List[Text]]:
842 ...
845@overload
846def DEFINE_list( # pylint: disable=invalid-name
847 name: Text,
848 default: None,
849 help: Text, # pylint: disable=redefined-builtin
850 flag_values: _flagvalues.FlagValues = ...,
851 required: bool = ...,
852 **args: Any
853) -> _flagvalues.FlagHolder[Optional[List[Text]]]:
854 ...
857@overload
858def DEFINE_list( # pylint: disable=invalid-name
859 name: Text,
860 default: Union[Iterable[Text], Text],
861 help: Text, # pylint: disable=redefined-builtin
862 flag_values: _flagvalues.FlagValues = ...,
863 required: bool = ...,
864 **args: Any
865) -> _flagvalues.FlagHolder[List[Text]]:
866 ...
869def DEFINE_list( # pylint: disable=invalid-name,redefined-builtin
870 name,
871 default,
872 help,
873 flag_values=_flagvalues.FLAGS,
874 required=False,
875 **args):
876 """Registers a flag whose value is a comma-separated list of strings.
878 The flag value is parsed with a CSV parser.
880 Args:
881 name: str, the flag name.
882 default: list|str|None, the default value of the flag.
883 help: str, the help message.
884 flag_values: :class:`FlagValues`, the FlagValues instance with which the
885 flag will be registered. This should almost never need to be overridden.
886 required: bool, is this a required flag. This must be used as a keyword
887 argument.
888 **args: Dictionary with extra keyword args that are passed to the
889 ``Flag.__init__``.
891 Returns:
892 a handle to defined flag.
893 """
894 parser = _argument_parser.ListParser()
895 serializer = _argument_parser.CsvListSerializer(',')
896 return DEFINE(
897 parser,
898 name,
899 default,
900 help,
901 flag_values,
902 serializer,
903 required=True if required else False,
904 **args,
905 )
908@overload
909def DEFINE_spaceseplist( # pylint: disable=invalid-name
910 name: Text,
911 default: Union[None, Iterable[Text], Text],
912 help: Text, # pylint: disable=redefined-builtin
913 comma_compat: bool = ...,
914 flag_values: _flagvalues.FlagValues = ...,
915 *,
916 required: 'typing.Literal[True]',
917 **args: Any
918) -> _flagvalues.FlagHolder[List[Text]]:
919 ...
922@overload
923def DEFINE_spaceseplist( # pylint: disable=invalid-name
924 name: Text,
925 default: None,
926 help: Text, # pylint: disable=redefined-builtin
927 comma_compat: bool = ...,
928 flag_values: _flagvalues.FlagValues = ...,
929 required: bool = ...,
930 **args: Any
931) -> _flagvalues.FlagHolder[Optional[List[Text]]]:
932 ...
935@overload
936def DEFINE_spaceseplist( # pylint: disable=invalid-name
937 name: Text,
938 default: Union[Iterable[Text], Text],
939 help: Text, # pylint: disable=redefined-builtin
940 comma_compat: bool = ...,
941 flag_values: _flagvalues.FlagValues = ...,
942 required: bool = ...,
943 **args: Any
944) -> _flagvalues.FlagHolder[List[Text]]:
945 ...
948def DEFINE_spaceseplist( # pylint: disable=invalid-name,redefined-builtin
949 name,
950 default,
951 help,
952 comma_compat=False,
953 flag_values=_flagvalues.FLAGS,
954 required=False,
955 **args):
956 """Registers a flag whose value is a whitespace-separated list of strings.
958 Any whitespace can be used as a separator.
960 Args:
961 name: str, the flag name.
962 default: list|str|None, the default value of the flag.
963 help: str, the help message.
964 comma_compat: bool - Whether to support comma as an additional separator. If
965 false then only whitespace is supported. This is intended only for
966 backwards compatibility with flags that used to be comma-separated.
967 flag_values: :class:`FlagValues`, the FlagValues instance with which the
968 flag will be registered. This should almost never need to be overridden.
969 required: bool, is this a required flag. This must be used as a keyword
970 argument.
971 **args: Dictionary with extra keyword args that are passed to the
972 ``Flag.__init__``.
974 Returns:
975 a handle to defined flag.
976 """
977 parser = _argument_parser.WhitespaceSeparatedListParser(
978 comma_compat=comma_compat)
979 serializer = _argument_parser.ListSerializer(' ')
980 return DEFINE(
981 parser,
982 name,
983 default,
984 help,
985 flag_values,
986 serializer,
987 required=True if required else False,
988 **args,
989 )
992@overload
993def DEFINE_multi( # pylint: disable=invalid-name
994 parser: _argument_parser.ArgumentParser[_T],
995 serializer: _argument_parser.ArgumentSerializer[_T],
996 name: Text,
997 default: Iterable[_T],
998 help: Text, # pylint: disable=redefined-builtin
999 flag_values: _flagvalues.FlagValues = ...,
1000 module_name: Optional[Text] = ...,
1001 *,
1002 required: 'typing.Literal[True]',
1003 **args: Any
1004) -> _flagvalues.FlagHolder[List[_T]]:
1005 ...
1008@overload
1009def DEFINE_multi( # pylint: disable=invalid-name
1010 parser: _argument_parser.ArgumentParser[_T],
1011 serializer: _argument_parser.ArgumentSerializer[_T],
1012 name: Text,
1013 default: Union[None, _T],
1014 help: Text, # pylint: disable=redefined-builtin
1015 flag_values: _flagvalues.FlagValues = ...,
1016 module_name: Optional[Text] = ...,
1017 *,
1018 required: 'typing.Literal[True]',
1019 **args: Any
1020) -> _flagvalues.FlagHolder[List[_T]]:
1021 ...
1024@overload
1025def DEFINE_multi( # pylint: disable=invalid-name
1026 parser: _argument_parser.ArgumentParser[_T],
1027 serializer: _argument_parser.ArgumentSerializer[_T],
1028 name: Text,
1029 default: None,
1030 help: Text, # pylint: disable=redefined-builtin
1031 flag_values: _flagvalues.FlagValues = ...,
1032 module_name: Optional[Text] = ...,
1033 required: bool = ...,
1034 **args: Any
1035) -> _flagvalues.FlagHolder[Optional[List[_T]]]:
1036 ...
1039@overload
1040def DEFINE_multi( # pylint: disable=invalid-name
1041 parser: _argument_parser.ArgumentParser[_T],
1042 serializer: _argument_parser.ArgumentSerializer[_T],
1043 name: Text,
1044 default: Iterable[_T],
1045 help: Text, # pylint: disable=redefined-builtin
1046 flag_values: _flagvalues.FlagValues = ...,
1047 module_name: Optional[Text] = ...,
1048 required: bool = ...,
1049 **args: Any
1050) -> _flagvalues.FlagHolder[List[_T]]:
1051 ...
1054@overload
1055def DEFINE_multi( # pylint: disable=invalid-name
1056 parser: _argument_parser.ArgumentParser[_T],
1057 serializer: _argument_parser.ArgumentSerializer[_T],
1058 name: Text,
1059 default: _T,
1060 help: Text, # pylint: disable=redefined-builtin
1061 flag_values: _flagvalues.FlagValues = ...,
1062 module_name: Optional[Text] = ...,
1063 required: bool = ...,
1064 **args: Any
1065) -> _flagvalues.FlagHolder[List[_T]]:
1066 ...
1069def DEFINE_multi( # pylint: disable=invalid-name,redefined-builtin
1070 parser,
1071 serializer,
1072 name,
1073 default,
1074 help,
1075 flag_values=_flagvalues.FLAGS,
1076 module_name=None,
1077 required=False,
1078 **args):
1079 """Registers a generic MultiFlag that parses its args with a given parser.
1081 Auxiliary function. Normal users should NOT use it directly.
1083 Developers who need to create their own 'Parser' classes for options
1084 which can appear multiple times can call this module function to
1085 register their flags.
1087 Args:
1088 parser: ArgumentParser, used to parse the flag arguments.
1089 serializer: ArgumentSerializer, the flag serializer instance.
1090 name: str, the flag name.
1091 default: Union[Iterable[T], Text, None], the default value of the flag. If
1092 the value is text, it will be parsed as if it was provided from the
1093 command line. If the value is a non-string iterable, it will be iterated
1094 over to create a shallow copy of the values. If it is None, it is left
1095 as-is.
1096 help: str, the help message.
1097 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1098 flag will be registered. This should almost never need to be overridden.
1099 module_name: A string, the name of the Python module declaring this flag. If
1100 not provided, it will be computed using the stack trace of this call.
1101 required: bool, is this a required flag. This must be used as a keyword
1102 argument.
1103 **args: Dictionary with extra keyword args that are passed to the
1104 ``Flag.__init__``.
1106 Returns:
1107 a handle to defined flag.
1108 """
1109 result = DEFINE_flag(
1110 _flag.MultiFlag(parser, serializer, name, default, help, **args),
1111 flag_values,
1112 module_name,
1113 required=True if required else False,
1114 )
1115 return result
1118@overload
1119def DEFINE_multi_string( # pylint: disable=invalid-name
1120 name: Text,
1121 default: Union[None, Iterable[Text], Text],
1122 help: Text, # pylint: disable=redefined-builtin
1123 flag_values: _flagvalues.FlagValues = ...,
1124 *,
1125 required: 'typing.Literal[True]',
1126 **args: Any
1127) -> _flagvalues.FlagHolder[List[Text]]:
1128 ...
1131@overload
1132def DEFINE_multi_string( # pylint: disable=invalid-name
1133 name: Text,
1134 default: None,
1135 help: Text, # pylint: disable=redefined-builtin
1136 flag_values: _flagvalues.FlagValues = ...,
1137 required: bool = ...,
1138 **args: Any
1139) -> _flagvalues.FlagHolder[Optional[List[Text]]]:
1140 ...
1143@overload
1144def DEFINE_multi_string( # pylint: disable=invalid-name
1145 name: Text,
1146 default: Union[Iterable[Text], Text],
1147 help: Text, # pylint: disable=redefined-builtin
1148 flag_values: _flagvalues.FlagValues = ...,
1149 required: bool = ...,
1150 **args: Any
1151) -> _flagvalues.FlagHolder[List[Text]]:
1152 ...
1155def DEFINE_multi_string( # pylint: disable=invalid-name,redefined-builtin
1156 name,
1157 default,
1158 help,
1159 flag_values=_flagvalues.FLAGS,
1160 required=False,
1161 **args):
1162 """Registers a flag whose value can be a list of any strings.
1164 Use the flag on the command line multiple times to place multiple
1165 string values into the list. The 'default' may be a single string
1166 (which will be converted into a single-element list) or a list of
1167 strings.
1170 Args:
1171 name: str, the flag name.
1172 default: Union[Iterable[Text], Text, None], the default value of the flag;
1173 see :func:`DEFINE_multi`.
1174 help: str, the help message.
1175 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1176 flag will be registered. This should almost never need to be overridden.
1177 required: bool, is this a required flag. This must be used as a keyword
1178 argument.
1179 **args: Dictionary with extra keyword args that are passed to the
1180 ``Flag.__init__``.
1182 Returns:
1183 a handle to defined flag.
1184 """
1185 parser = _argument_parser.ArgumentParser()
1186 serializer = _argument_parser.ArgumentSerializer()
1187 return DEFINE_multi(
1188 parser,
1189 serializer,
1190 name,
1191 default,
1192 help,
1193 flag_values,
1194 required=True if required else False,
1195 **args,
1196 )
1199@overload
1200def DEFINE_multi_integer( # pylint: disable=invalid-name
1201 name: Text,
1202 default: Union[None, Iterable[int], int, Text],
1203 help: Text, # pylint: disable=redefined-builtin
1204 lower_bound: Optional[int] = ...,
1205 upper_bound: Optional[int] = ...,
1206 flag_values: _flagvalues.FlagValues = ...,
1207 *,
1208 required: 'typing.Literal[True]',
1209 **args: Any
1210) -> _flagvalues.FlagHolder[List[int]]:
1211 ...
1214@overload
1215def DEFINE_multi_integer( # pylint: disable=invalid-name
1216 name: Text,
1217 default: None,
1218 help: Text, # pylint: disable=redefined-builtin
1219 lower_bound: Optional[int] = ...,
1220 upper_bound: Optional[int] = ...,
1221 flag_values: _flagvalues.FlagValues = ...,
1222 required: bool = ...,
1223 **args: Any
1224) -> _flagvalues.FlagHolder[Optional[List[int]]]:
1225 ...
1228@overload
1229def DEFINE_multi_integer( # pylint: disable=invalid-name
1230 name: Text,
1231 default: Union[Iterable[int], int, Text],
1232 help: Text, # pylint: disable=redefined-builtin
1233 lower_bound: Optional[int] = ...,
1234 upper_bound: Optional[int] = ...,
1235 flag_values: _flagvalues.FlagValues = ...,
1236 required: bool = ...,
1237 **args: Any
1238) -> _flagvalues.FlagHolder[List[int]]:
1239 ...
1242def DEFINE_multi_integer( # pylint: disable=invalid-name,redefined-builtin
1243 name,
1244 default,
1245 help,
1246 lower_bound=None,
1247 upper_bound=None,
1248 flag_values=_flagvalues.FLAGS,
1249 required=False,
1250 **args):
1251 """Registers a flag whose value can be a list of arbitrary integers.
1253 Use the flag on the command line multiple times to place multiple
1254 integer values into the list. The 'default' may be a single integer
1255 (which will be converted into a single-element list) or a list of
1256 integers.
1258 Args:
1259 name: str, the flag name.
1260 default: Union[Iterable[int], Text, None], the default value of the flag;
1261 see `DEFINE_multi`.
1262 help: str, the help message.
1263 lower_bound: int, min values of the flag.
1264 upper_bound: int, max values of the flag.
1265 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1266 flag will be registered. This should almost never need to be overridden.
1267 required: bool, is this a required flag. This must be used as a keyword
1268 argument.
1269 **args: Dictionary with extra keyword args that are passed to the
1270 ``Flag.__init__``.
1272 Returns:
1273 a handle to defined flag.
1274 """
1275 parser = _argument_parser.IntegerParser(lower_bound, upper_bound)
1276 serializer = _argument_parser.ArgumentSerializer()
1277 return DEFINE_multi(
1278 parser,
1279 serializer,
1280 name,
1281 default,
1282 help,
1283 flag_values,
1284 required=True if required else False,
1285 **args,
1286 )
1289@overload
1290def DEFINE_multi_float( # pylint: disable=invalid-name
1291 name: Text,
1292 default: Union[None, Iterable[float], float, Text],
1293 help: Text, # pylint: disable=redefined-builtin
1294 lower_bound: Optional[float] = ...,
1295 upper_bound: Optional[float] = ...,
1296 flag_values: _flagvalues.FlagValues = ...,
1297 *,
1298 required: 'typing.Literal[True]',
1299 **args: Any
1300) -> _flagvalues.FlagHolder[List[float]]:
1301 ...
1304@overload
1305def DEFINE_multi_float( # pylint: disable=invalid-name
1306 name: Text,
1307 default: None,
1308 help: Text, # pylint: disable=redefined-builtin
1309 lower_bound: Optional[float] = ...,
1310 upper_bound: Optional[float] = ...,
1311 flag_values: _flagvalues.FlagValues = ...,
1312 required: bool = ...,
1313 **args: Any
1314) -> _flagvalues.FlagHolder[Optional[List[float]]]:
1315 ...
1318@overload
1319def DEFINE_multi_float( # pylint: disable=invalid-name
1320 name: Text,
1321 default: Union[Iterable[float], float, Text],
1322 help: Text, # pylint: disable=redefined-builtin
1323 lower_bound: Optional[float] = ...,
1324 upper_bound: Optional[float] = ...,
1325 flag_values: _flagvalues.FlagValues = ...,
1326 required: bool = ...,
1327 **args: Any
1328) -> _flagvalues.FlagHolder[List[float]]:
1329 ...
1332def DEFINE_multi_float( # pylint: disable=invalid-name,redefined-builtin
1333 name,
1334 default,
1335 help,
1336 lower_bound=None,
1337 upper_bound=None,
1338 flag_values=_flagvalues.FLAGS,
1339 required=False,
1340 **args):
1341 """Registers a flag whose value can be a list of arbitrary floats.
1343 Use the flag on the command line multiple times to place multiple
1344 float values into the list. The 'default' may be a single float
1345 (which will be converted into a single-element list) or a list of
1346 floats.
1348 Args:
1349 name: str, the flag name.
1350 default: Union[Iterable[float], Text, None], the default value of the flag;
1351 see `DEFINE_multi`.
1352 help: str, the help message.
1353 lower_bound: float, min values of the flag.
1354 upper_bound: float, max values of the flag.
1355 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1356 flag will be registered. This should almost never need to be overridden.
1357 required: bool, is this a required flag. This must be used as a keyword
1358 argument.
1359 **args: Dictionary with extra keyword args that are passed to the
1360 ``Flag.__init__``.
1362 Returns:
1363 a handle to defined flag.
1364 """
1365 parser = _argument_parser.FloatParser(lower_bound, upper_bound)
1366 serializer = _argument_parser.ArgumentSerializer()
1367 return DEFINE_multi(
1368 parser,
1369 serializer,
1370 name,
1371 default,
1372 help,
1373 flag_values,
1374 required=True if required else False,
1375 **args,
1376 )
1379@overload
1380def DEFINE_multi_enum( # pylint: disable=invalid-name
1381 name: Text,
1382 default: Union[None, Iterable[Text], Text],
1383 enum_values: Iterable[Text],
1384 help: Text, # pylint: disable=redefined-builtin
1385 flag_values: _flagvalues.FlagValues = ...,
1386 *,
1387 required: 'typing.Literal[True]',
1388 **args: Any
1389) -> _flagvalues.FlagHolder[List[Text]]:
1390 ...
1393@overload
1394def DEFINE_multi_enum( # pylint: disable=invalid-name
1395 name: Text,
1396 default: None,
1397 enum_values: Iterable[Text],
1398 help: Text, # pylint: disable=redefined-builtin
1399 flag_values: _flagvalues.FlagValues = ...,
1400 required: bool = ...,
1401 **args: Any
1402) -> _flagvalues.FlagHolder[Optional[List[Text]]]:
1403 ...
1406@overload
1407def DEFINE_multi_enum( # pylint: disable=invalid-name
1408 name: Text,
1409 default: Union[Iterable[Text], Text],
1410 enum_values: Iterable[Text],
1411 help: Text, # pylint: disable=redefined-builtin
1412 flag_values: _flagvalues.FlagValues = ...,
1413 required: bool = ...,
1414 **args: Any
1415) -> _flagvalues.FlagHolder[List[Text]]:
1416 ...
1419def DEFINE_multi_enum( # pylint: disable=invalid-name,redefined-builtin
1420 name,
1421 default,
1422 enum_values,
1423 help,
1424 flag_values=_flagvalues.FLAGS,
1425 case_sensitive=True,
1426 required=False,
1427 **args):
1428 """Registers a flag whose value can be a list strings from enum_values.
1430 Use the flag on the command line multiple times to place multiple
1431 enum values into the list. The 'default' may be a single string
1432 (which will be converted into a single-element list) or a list of
1433 strings.
1435 Args:
1436 name: str, the flag name.
1437 default: Union[Iterable[Text], Text, None], the default value of the flag;
1438 see `DEFINE_multi`.
1439 enum_values: [str], a non-empty list of strings with the possible values for
1440 the flag.
1441 help: str, the help message.
1442 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1443 flag will be registered. This should almost never need to be overridden.
1444 case_sensitive: Whether or not the enum is to be case-sensitive.
1445 required: bool, is this a required flag. This must be used as a keyword
1446 argument.
1447 **args: Dictionary with extra keyword args that are passed to the
1448 ``Flag.__init__``.
1450 Returns:
1451 a handle to defined flag.
1452 """
1453 parser = _argument_parser.EnumParser(enum_values, case_sensitive)
1454 serializer = _argument_parser.ArgumentSerializer()
1455 return DEFINE_multi(
1456 parser,
1457 serializer,
1458 name,
1459 default,
1460 '<%s>: %s' % ('|'.join(enum_values), help),
1461 flag_values,
1462 required=True if required else False,
1463 **args,
1464 )
1467@overload
1468def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1469 name: Text,
1470 # This is separate from `Union[None, _ET, Iterable[Text], Text]` to avoid a
1471 # Pytype issue inferring the return value to
1472 # FlagHolder[List[Union[_ET, enum.Enum]]] when an iterable of concrete enum
1473 # subclasses are used.
1474 default: Iterable[_ET],
1475 enum_class: Type[_ET],
1476 help: Text, # pylint: disable=redefined-builtin
1477 flag_values: _flagvalues.FlagValues = ...,
1478 module_name: Optional[Text] = ...,
1479 *,
1480 required: 'typing.Literal[True]',
1481 **args: Any
1482) -> _flagvalues.FlagHolder[List[_ET]]:
1483 ...
1486@overload
1487def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1488 name: Text,
1489 default: Union[None, _ET, Iterable[Text], Text],
1490 enum_class: Type[_ET],
1491 help: Text, # pylint: disable=redefined-builtin
1492 flag_values: _flagvalues.FlagValues = ...,
1493 module_name: Optional[Text] = ...,
1494 *,
1495 required: 'typing.Literal[True]',
1496 **args: Any
1497) -> _flagvalues.FlagHolder[List[_ET]]:
1498 ...
1501@overload
1502def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1503 name: Text,
1504 default: None,
1505 enum_class: Type[_ET],
1506 help: Text, # pylint: disable=redefined-builtin
1507 flag_values: _flagvalues.FlagValues = ...,
1508 module_name: Optional[Text] = ...,
1509 required: bool = ...,
1510 **args: Any
1511) -> _flagvalues.FlagHolder[Optional[List[_ET]]]:
1512 ...
1515@overload
1516def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1517 name: Text,
1518 # This is separate from `Union[None, _ET, Iterable[Text], Text]` to avoid a
1519 # Pytype issue inferring the return value to
1520 # FlagHolder[List[Union[_ET, enum.Enum]]] when an iterable of concrete enum
1521 # subclasses are used.
1522 default: Iterable[_ET],
1523 enum_class: Type[_ET],
1524 help: Text, # pylint: disable=redefined-builtin
1525 flag_values: _flagvalues.FlagValues = ...,
1526 module_name: Optional[Text] = ...,
1527 required: bool = ...,
1528 **args: Any
1529) -> _flagvalues.FlagHolder[List[_ET]]:
1530 ...
1533@overload
1534def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1535 name: Text,
1536 default: Union[_ET, Iterable[Text], Text],
1537 enum_class: Type[_ET],
1538 help: Text, # pylint: disable=redefined-builtin
1539 flag_values: _flagvalues.FlagValues = ...,
1540 module_name: Optional[Text] = ...,
1541 required: bool = ...,
1542 **args: Any
1543) -> _flagvalues.FlagHolder[List[_ET]]:
1544 ...
1547def DEFINE_multi_enum_class( # pylint: disable=invalid-name,redefined-builtin
1548 name,
1549 default,
1550 enum_class,
1551 help,
1552 flag_values=_flagvalues.FLAGS,
1553 module_name=None,
1554 case_sensitive=False,
1555 required=False,
1556 **args):
1557 """Registers a flag whose value can be a list of enum members.
1559 Use the flag on the command line multiple times to place multiple
1560 enum values into the list.
1562 Args:
1563 name: str, the flag name.
1564 default: Union[Iterable[Enum], Iterable[Text], Enum, Text, None], the
1565 default value of the flag; see `DEFINE_multi`; only differences are
1566 documented here. If the value is a single Enum, it is treated as a
1567 single-item list of that Enum value. If it is an iterable, text values
1568 within the iterable will be converted to the equivalent Enum objects.
1569 enum_class: class, the Enum class with all the possible values for the flag.
1570 help: str, the help message.
1571 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1572 flag will be registered. This should almost never need to be overridden.
1573 module_name: A string, the name of the Python module declaring this flag. If
1574 not provided, it will be computed using the stack trace of this call.
1575 case_sensitive: bool, whether to map strings to members of the enum_class
1576 without considering case.
1577 required: bool, is this a required flag. This must be used as a keyword
1578 argument.
1579 **args: Dictionary with extra keyword args that are passed to the
1580 ``Flag.__init__``.
1582 Returns:
1583 a handle to defined flag.
1584 """
1585 # NOTE: pytype fails if this is a direct return.
1586 result = DEFINE_flag(
1587 _flag.MultiEnumClassFlag(
1588 name,
1589 default,
1590 help,
1591 enum_class,
1592 case_sensitive=case_sensitive,
1593 **args,
1594 ),
1595 flag_values,
1596 module_name,
1597 required=True if required else False,
1598 )
1599 return result
1602def DEFINE_alias( # pylint: disable=invalid-name
1603 name: Text,
1604 original_name: Text,
1605 flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS,
1606 module_name: Optional[Text] = None,
1607) -> _flagvalues.FlagHolder[Any]:
1608 """Defines an alias flag for an existing one.
1610 Args:
1611 name: str, the flag name.
1612 original_name: str, the original flag name.
1613 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1614 flag will be registered. This should almost never need to be overridden.
1615 module_name: A string, the name of the module that defines this flag.
1617 Returns:
1618 a handle to defined flag.
1620 Raises:
1621 flags.FlagError:
1622 UnrecognizedFlagError: if the referenced flag doesn't exist.
1623 DuplicateFlagError: if the alias name has been used by some existing flag.
1624 """
1625 if original_name not in flag_values:
1626 raise _exceptions.UnrecognizedFlagError(original_name)
1627 flag = flag_values[original_name]
1629 class _FlagAlias(_flag.Flag):
1630 """Overrides Flag class so alias value is copy of original flag value."""
1632 def parse(self, argument):
1633 flag.parse(argument)
1634 self.present += 1
1636 def _parse_from_default(self, value):
1637 # The value was already parsed by the aliased flag, so there is no
1638 # need to call the parser on it a second time.
1639 # Additionally, because of how MultiFlag parses and merges values,
1640 # it isn't possible to delegate to the aliased flag and still get
1641 # the correct values.
1642 return value
1644 @property
1645 def value(self):
1646 return flag.value
1648 @value.setter
1649 def value(self, value):
1650 flag.value = value
1652 help_msg = 'Alias for --%s.' % flag.name
1653 # If alias_name has been used, flags.DuplicatedFlag will be raised.
1654 return DEFINE_flag(
1655 _FlagAlias(
1656 flag.parser,
1657 flag.serializer,
1658 name,
1659 flag.default,
1660 help_msg,
1661 boolean=flag.boolean), flag_values, module_name)