Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/absl_py-2.0.0-py3.8.egg/absl/flags/_defines.py: 57%
293 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-08 06:13 +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 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[Text, _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: Text,
373 default: Optional[Text],
374 help: Optional[Text], # pylint: disable=redefined-builtin
375 flag_values: _flagvalues.FlagValues = ...,
376 *,
377 required: 'typing.Literal[True]',
378 **args: Any
379) -> _flagvalues.FlagHolder[Text]:
380 ...
383@overload
384def DEFINE_string( # pylint: disable=invalid-name
385 name: Text,
386 default: None,
387 help: Optional[Text], # pylint: disable=redefined-builtin
388 flag_values: _flagvalues.FlagValues = ...,
389 required: bool = ...,
390 **args: Any
391) -> _flagvalues.FlagHolder[Optional[Text]]:
392 ...
395@overload
396def DEFINE_string( # pylint: disable=invalid-name
397 name: Text,
398 default: Text,
399 help: Optional[Text], # pylint: disable=redefined-builtin
400 flag_values: _flagvalues.FlagValues = ...,
401 required: bool = ...,
402 **args: Any
403) -> _flagvalues.FlagHolder[Text]:
404 ...
407def DEFINE_string( # pylint: disable=invalid-name,redefined-builtin
408 name,
409 default,
410 help,
411 flag_values=_flagvalues.FLAGS,
412 required=False,
413 **args):
414 """Registers a flag whose value can be any string."""
415 parser = _argument_parser.ArgumentParser[str]()
416 serializer = _argument_parser.ArgumentSerializer[str]()
417 return DEFINE(
418 parser,
419 name,
420 default,
421 help,
422 flag_values,
423 serializer,
424 required=True if required else False,
425 **args,
426 )
429@overload
430def DEFINE_boolean( # pylint: disable=invalid-name
431 name: Text,
432 default: Union[None, Text, bool, int],
433 help: Optional[Text], # pylint: disable=redefined-builtin
434 flag_values: _flagvalues.FlagValues = ...,
435 module_name: Optional[Text] = ...,
436 *,
437 required: 'typing.Literal[True]',
438 **args: Any
439) -> _flagvalues.FlagHolder[bool]:
440 ...
443@overload
444def DEFINE_boolean( # pylint: disable=invalid-name
445 name: Text,
446 default: None,
447 help: Optional[Text], # pylint: disable=redefined-builtin
448 flag_values: _flagvalues.FlagValues = ...,
449 module_name: Optional[Text] = ...,
450 required: bool = ...,
451 **args: Any
452) -> _flagvalues.FlagHolder[Optional[bool]]:
453 ...
456@overload
457def DEFINE_boolean( # pylint: disable=invalid-name
458 name: Text,
459 default: Union[Text, bool, int],
460 help: Optional[Text], # pylint: disable=redefined-builtin
461 flag_values: _flagvalues.FlagValues = ...,
462 module_name: Optional[Text] = ...,
463 required: bool = ...,
464 **args: Any
465) -> _flagvalues.FlagHolder[bool]:
466 ...
469def DEFINE_boolean( # pylint: disable=invalid-name,redefined-builtin
470 name,
471 default,
472 help,
473 flag_values=_flagvalues.FLAGS,
474 module_name=None,
475 required=False,
476 **args):
477 """Registers a boolean flag.
479 Such a boolean flag does not take an argument. If a user wants to
480 specify a false value explicitly, the long option beginning with 'no'
481 must be used: i.e. --noflag
483 This flag will have a value of None, True or False. None is possible
484 if default=None and the user does not specify the flag on the command
485 line.
487 Args:
488 name: str, the flag name.
489 default: bool|str|None, the default value of the flag.
490 help: str, the help message.
491 flag_values: :class:`FlagValues`, the FlagValues instance with which the
492 flag will be registered. This should almost never need to be overridden.
493 module_name: str, the name of the Python module declaring this flag. If not
494 provided, it will be computed using the stack trace of this call.
495 required: bool, is this a required flag. This must be used as a keyword
496 argument.
497 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
499 Returns:
500 a handle to defined flag.
501 """
502 return DEFINE_flag(
503 _flag.BooleanFlag(name, default, help, **args),
504 flag_values,
505 module_name,
506 required=True if required else False,
507 )
510@overload
511def DEFINE_float( # pylint: disable=invalid-name
512 name: Text,
513 default: Union[None, float, Text],
514 help: Optional[Text], # pylint: disable=redefined-builtin
515 lower_bound: Optional[float] = ...,
516 upper_bound: Optional[float] = ...,
517 flag_values: _flagvalues.FlagValues = ...,
518 *,
519 required: 'typing.Literal[True]',
520 **args: Any
521) -> _flagvalues.FlagHolder[float]:
522 ...
525@overload
526def DEFINE_float( # pylint: disable=invalid-name
527 name: Text,
528 default: None,
529 help: Optional[Text], # pylint: disable=redefined-builtin
530 lower_bound: Optional[float] = ...,
531 upper_bound: Optional[float] = ...,
532 flag_values: _flagvalues.FlagValues = ...,
533 required: bool = ...,
534 **args: Any
535) -> _flagvalues.FlagHolder[Optional[float]]:
536 ...
539@overload
540def DEFINE_float( # pylint: disable=invalid-name
541 name: Text,
542 default: Union[float, Text],
543 help: Optional[Text], # pylint: disable=redefined-builtin
544 lower_bound: Optional[float] = ...,
545 upper_bound: Optional[float] = ...,
546 flag_values: _flagvalues.FlagValues = ...,
547 required: bool = ...,
548 **args: Any
549) -> _flagvalues.FlagHolder[float]:
550 ...
553def DEFINE_float( # pylint: disable=invalid-name,redefined-builtin
554 name,
555 default,
556 help,
557 lower_bound=None,
558 upper_bound=None,
559 flag_values=_flagvalues.FLAGS,
560 required=False,
561 **args):
562 """Registers a flag whose value must be a float.
564 If ``lower_bound`` or ``upper_bound`` are set, then this flag must be
565 within the given range.
567 Args:
568 name: str, the flag name.
569 default: float|str|None, the default value of the flag.
570 help: str, the help message.
571 lower_bound: float, min value of the flag.
572 upper_bound: float, max value of the flag.
573 flag_values: :class:`FlagValues`, the FlagValues instance with which the
574 flag will be registered. This should almost never need to be overridden.
575 required: bool, is this a required flag. This must be used as a keyword
576 argument.
577 **args: dict, the extra keyword args that are passed to :func:`DEFINE`.
579 Returns:
580 a handle to defined flag.
581 """
582 parser = _argument_parser.FloatParser(lower_bound, upper_bound)
583 serializer = _argument_parser.ArgumentSerializer()
584 result = DEFINE(
585 parser,
586 name,
587 default,
588 help,
589 flag_values,
590 serializer,
591 required=True if required else False,
592 **args,
593 )
594 _register_bounds_validator_if_needed(parser, name, flag_values=flag_values)
595 return result
598@overload
599def DEFINE_integer( # pylint: disable=invalid-name
600 name: Text,
601 default: Union[None, int, Text],
602 help: Optional[Text], # pylint: disable=redefined-builtin
603 lower_bound: Optional[int] = ...,
604 upper_bound: Optional[int] = ...,
605 flag_values: _flagvalues.FlagValues = ...,
606 *,
607 required: 'typing.Literal[True]',
608 **args: Any
609) -> _flagvalues.FlagHolder[int]:
610 ...
613@overload
614def DEFINE_integer( # pylint: disable=invalid-name
615 name: Text,
616 default: None,
617 help: Optional[Text], # pylint: disable=redefined-builtin
618 lower_bound: Optional[int] = ...,
619 upper_bound: Optional[int] = ...,
620 flag_values: _flagvalues.FlagValues = ...,
621 required: bool = ...,
622 **args: Any
623) -> _flagvalues.FlagHolder[Optional[int]]:
624 ...
627@overload
628def DEFINE_integer( # pylint: disable=invalid-name
629 name: Text,
630 default: Union[int, Text],
631 help: Optional[Text], # pylint: disable=redefined-builtin
632 lower_bound: Optional[int] = ...,
633 upper_bound: Optional[int] = ...,
634 flag_values: _flagvalues.FlagValues = ...,
635 required: bool = ...,
636 **args: Any
637) -> _flagvalues.FlagHolder[int]:
638 ...
641def DEFINE_integer( # pylint: disable=invalid-name,redefined-builtin
642 name,
643 default,
644 help,
645 lower_bound=None,
646 upper_bound=None,
647 flag_values=_flagvalues.FLAGS,
648 required=False,
649 **args):
650 """Registers a flag whose value must be an integer.
652 If ``lower_bound``, or ``upper_bound`` are set, then this flag must be
653 within the given range.
655 Args:
656 name: str, the flag name.
657 default: int|str|None, the default value of the flag.
658 help: str, the help message.
659 lower_bound: int, min value of the flag.
660 upper_bound: int, max value of the flag.
661 flag_values: :class:`FlagValues`, the FlagValues instance with which the
662 flag will be registered. This should almost never need to be overridden.
663 required: bool, is this a required flag. This must be used as a keyword
664 argument.
665 **args: dict, the extra keyword args that are passed to :func:`DEFINE`.
667 Returns:
668 a handle to defined flag.
669 """
670 parser = _argument_parser.IntegerParser(lower_bound, upper_bound)
671 serializer = _argument_parser.ArgumentSerializer()
672 result = DEFINE(
673 parser,
674 name,
675 default,
676 help,
677 flag_values,
678 serializer,
679 required=True if required else False,
680 **args,
681 )
682 _register_bounds_validator_if_needed(parser, name, flag_values=flag_values)
683 return result
686@overload
687def DEFINE_enum( # pylint: disable=invalid-name
688 name: Text,
689 default: Optional[Text],
690 enum_values: Iterable[Text],
691 help: Optional[Text], # pylint: disable=redefined-builtin
692 flag_values: _flagvalues.FlagValues = ...,
693 module_name: Optional[Text] = ...,
694 *,
695 required: 'typing.Literal[True]',
696 **args: Any
697) -> _flagvalues.FlagHolder[Text]:
698 ...
701@overload
702def DEFINE_enum( # pylint: disable=invalid-name
703 name: Text,
704 default: None,
705 enum_values: Iterable[Text],
706 help: Optional[Text], # pylint: disable=redefined-builtin
707 flag_values: _flagvalues.FlagValues = ...,
708 module_name: Optional[Text] = ...,
709 required: bool = ...,
710 **args: Any
711) -> _flagvalues.FlagHolder[Optional[Text]]:
712 ...
715@overload
716def DEFINE_enum( # pylint: disable=invalid-name
717 name: Text,
718 default: Text,
719 enum_values: Iterable[Text],
720 help: Optional[Text], # pylint: disable=redefined-builtin
721 flag_values: _flagvalues.FlagValues = ...,
722 module_name: Optional[Text] = ...,
723 required: bool = ...,
724 **args: Any
725) -> _flagvalues.FlagHolder[Text]:
726 ...
729def DEFINE_enum( # pylint: disable=invalid-name,redefined-builtin
730 name,
731 default,
732 enum_values,
733 help,
734 flag_values=_flagvalues.FLAGS,
735 module_name=None,
736 required=False,
737 **args):
738 """Registers a flag whose value can be any string from enum_values.
740 Instead of a string enum, prefer `DEFINE_enum_class`, which allows
741 defining enums from an `enum.Enum` class.
743 Args:
744 name: str, the flag name.
745 default: str|None, the default value of the flag.
746 enum_values: [str], a non-empty list of strings with the possible values for
747 the flag.
748 help: str, the help message.
749 flag_values: :class:`FlagValues`, the FlagValues instance with which the
750 flag will be registered. This should almost never need to be overridden.
751 module_name: str, the name of the Python module declaring this flag. If not
752 provided, it will be computed using the stack trace of this call.
753 required: bool, is this a required flag. This must be used as a keyword
754 argument.
755 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
757 Returns:
758 a handle to defined flag.
759 """
760 result = DEFINE_flag(
761 _flag.EnumFlag(name, default, help, enum_values, **args),
762 flag_values,
763 module_name,
764 required=True if required else False,
765 )
766 return result
769@overload
770def DEFINE_enum_class( # pylint: disable=invalid-name
771 name: Text,
772 default: Union[None, _ET, Text],
773 enum_class: Type[_ET],
774 help: Optional[Text], # pylint: disable=redefined-builtin
775 flag_values: _flagvalues.FlagValues = ...,
776 module_name: Optional[Text] = ...,
777 case_sensitive: bool = ...,
778 *,
779 required: 'typing.Literal[True]',
780 **args: Any
781) -> _flagvalues.FlagHolder[_ET]:
782 ...
785@overload
786def DEFINE_enum_class( # pylint: disable=invalid-name
787 name: Text,
788 default: None,
789 enum_class: Type[_ET],
790 help: Optional[Text], # pylint: disable=redefined-builtin
791 flag_values: _flagvalues.FlagValues = ...,
792 module_name: Optional[Text] = ...,
793 case_sensitive: bool = ...,
794 required: bool = ...,
795 **args: Any
796) -> _flagvalues.FlagHolder[Optional[_ET]]:
797 ...
800@overload
801def DEFINE_enum_class( # pylint: disable=invalid-name
802 name: Text,
803 default: Union[_ET, Text],
804 enum_class: Type[_ET],
805 help: Optional[Text], # pylint: disable=redefined-builtin
806 flag_values: _flagvalues.FlagValues = ...,
807 module_name: Optional[Text] = ...,
808 case_sensitive: bool = ...,
809 required: bool = ...,
810 **args: Any
811) -> _flagvalues.FlagHolder[_ET]:
812 ...
815def DEFINE_enum_class( # pylint: disable=invalid-name,redefined-builtin
816 name,
817 default,
818 enum_class,
819 help,
820 flag_values=_flagvalues.FLAGS,
821 module_name=None,
822 case_sensitive=False,
823 required=False,
824 **args):
825 """Registers a flag whose value can be the name of enum members.
827 Args:
828 name: str, the flag name.
829 default: Enum|str|None, the default value of the flag.
830 enum_class: class, the Enum class with all the possible values for the flag.
831 help: str, the help message.
832 flag_values: :class:`FlagValues`, the FlagValues instance with which the
833 flag will be registered. This should almost never need to be overridden.
834 module_name: str, the name of the Python module declaring this flag. If not
835 provided, it will be computed using the stack trace of this call.
836 case_sensitive: bool, whether to map strings to members of the enum_class
837 without considering case.
838 required: bool, is this a required flag. This must be used as a keyword
839 argument.
840 **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
842 Returns:
843 a handle to defined flag.
844 """
845 # NOTE: pytype fails if this is a direct return.
846 result = DEFINE_flag(
847 _flag.EnumClassFlag(
848 name, default, help, enum_class, case_sensitive=case_sensitive, **args
849 ),
850 flag_values,
851 module_name,
852 required=True if required else False,
853 )
854 return result
857@overload
858def DEFINE_list( # pylint: disable=invalid-name
859 name: Text,
860 default: Union[None, Iterable[Text], Text],
861 help: Text, # pylint: disable=redefined-builtin
862 flag_values: _flagvalues.FlagValues = ...,
863 *,
864 required: 'typing.Literal[True]',
865 **args: Any
866) -> _flagvalues.FlagHolder[List[Text]]:
867 ...
870@overload
871def DEFINE_list( # pylint: disable=invalid-name
872 name: Text,
873 default: None,
874 help: Text, # pylint: disable=redefined-builtin
875 flag_values: _flagvalues.FlagValues = ...,
876 required: bool = ...,
877 **args: Any
878) -> _flagvalues.FlagHolder[Optional[List[Text]]]:
879 ...
882@overload
883def DEFINE_list( # pylint: disable=invalid-name
884 name: Text,
885 default: Union[Iterable[Text], Text],
886 help: Text, # pylint: disable=redefined-builtin
887 flag_values: _flagvalues.FlagValues = ...,
888 required: bool = ...,
889 **args: Any
890) -> _flagvalues.FlagHolder[List[Text]]:
891 ...
894def DEFINE_list( # pylint: disable=invalid-name,redefined-builtin
895 name,
896 default,
897 help,
898 flag_values=_flagvalues.FLAGS,
899 required=False,
900 **args):
901 """Registers a flag whose value is a comma-separated list of strings.
903 The flag value is parsed with a CSV parser.
905 Args:
906 name: str, the flag name.
907 default: list|str|None, the default value of the flag.
908 help: str, the help message.
909 flag_values: :class:`FlagValues`, the FlagValues instance with which the
910 flag will be registered. This should almost never need to be overridden.
911 required: bool, is this a required flag. This must be used as a keyword
912 argument.
913 **args: Dictionary with extra keyword args that are passed to the
914 ``Flag.__init__``.
916 Returns:
917 a handle to defined flag.
918 """
919 parser = _argument_parser.ListParser()
920 serializer = _argument_parser.CsvListSerializer(',')
921 return DEFINE(
922 parser,
923 name,
924 default,
925 help,
926 flag_values,
927 serializer,
928 required=True if required else False,
929 **args,
930 )
933@overload
934def DEFINE_spaceseplist( # pylint: disable=invalid-name
935 name: Text,
936 default: Union[None, Iterable[Text], Text],
937 help: Text, # pylint: disable=redefined-builtin
938 comma_compat: bool = ...,
939 flag_values: _flagvalues.FlagValues = ...,
940 *,
941 required: 'typing.Literal[True]',
942 **args: Any
943) -> _flagvalues.FlagHolder[List[Text]]:
944 ...
947@overload
948def DEFINE_spaceseplist( # pylint: disable=invalid-name
949 name: Text,
950 default: None,
951 help: Text, # pylint: disable=redefined-builtin
952 comma_compat: bool = ...,
953 flag_values: _flagvalues.FlagValues = ...,
954 required: bool = ...,
955 **args: Any
956) -> _flagvalues.FlagHolder[Optional[List[Text]]]:
957 ...
960@overload
961def DEFINE_spaceseplist( # pylint: disable=invalid-name
962 name: Text,
963 default: Union[Iterable[Text], Text],
964 help: Text, # pylint: disable=redefined-builtin
965 comma_compat: bool = ...,
966 flag_values: _flagvalues.FlagValues = ...,
967 required: bool = ...,
968 **args: Any
969) -> _flagvalues.FlagHolder[List[Text]]:
970 ...
973def DEFINE_spaceseplist( # pylint: disable=invalid-name,redefined-builtin
974 name,
975 default,
976 help,
977 comma_compat=False,
978 flag_values=_flagvalues.FLAGS,
979 required=False,
980 **args):
981 """Registers a flag whose value is a whitespace-separated list of strings.
983 Any whitespace can be used as a separator.
985 Args:
986 name: str, the flag name.
987 default: list|str|None, the default value of the flag.
988 help: str, the help message.
989 comma_compat: bool - Whether to support comma as an additional separator. If
990 false then only whitespace is supported. This is intended only for
991 backwards compatibility with flags that used to be comma-separated.
992 flag_values: :class:`FlagValues`, the FlagValues instance with which the
993 flag will be registered. This should almost never need to be overridden.
994 required: bool, is this a required flag. This must be used as a keyword
995 argument.
996 **args: Dictionary with extra keyword args that are passed to the
997 ``Flag.__init__``.
999 Returns:
1000 a handle to defined flag.
1001 """
1002 parser = _argument_parser.WhitespaceSeparatedListParser(
1003 comma_compat=comma_compat)
1004 serializer = _argument_parser.ListSerializer(' ')
1005 return DEFINE(
1006 parser,
1007 name,
1008 default,
1009 help,
1010 flag_values,
1011 serializer,
1012 required=True if required else False,
1013 **args,
1014 )
1017@overload
1018def DEFINE_multi( # pylint: disable=invalid-name
1019 parser: _argument_parser.ArgumentParser[_T],
1020 serializer: _argument_parser.ArgumentSerializer[_T],
1021 name: Text,
1022 default: Iterable[_T],
1023 help: Text, # pylint: disable=redefined-builtin
1024 flag_values: _flagvalues.FlagValues = ...,
1025 module_name: Optional[Text] = ...,
1026 *,
1027 required: 'typing.Literal[True]',
1028 **args: Any
1029) -> _flagvalues.FlagHolder[List[_T]]:
1030 ...
1033@overload
1034def DEFINE_multi( # pylint: disable=invalid-name
1035 parser: _argument_parser.ArgumentParser[_T],
1036 serializer: _argument_parser.ArgumentSerializer[_T],
1037 name: Text,
1038 default: Union[None, _T],
1039 help: Text, # pylint: disable=redefined-builtin
1040 flag_values: _flagvalues.FlagValues = ...,
1041 module_name: Optional[Text] = ...,
1042 *,
1043 required: 'typing.Literal[True]',
1044 **args: Any
1045) -> _flagvalues.FlagHolder[List[_T]]:
1046 ...
1049@overload
1050def DEFINE_multi( # pylint: disable=invalid-name
1051 parser: _argument_parser.ArgumentParser[_T],
1052 serializer: _argument_parser.ArgumentSerializer[_T],
1053 name: Text,
1054 default: None,
1055 help: Text, # pylint: disable=redefined-builtin
1056 flag_values: _flagvalues.FlagValues = ...,
1057 module_name: Optional[Text] = ...,
1058 required: bool = ...,
1059 **args: Any
1060) -> _flagvalues.FlagHolder[Optional[List[_T]]]:
1061 ...
1064@overload
1065def DEFINE_multi( # pylint: disable=invalid-name
1066 parser: _argument_parser.ArgumentParser[_T],
1067 serializer: _argument_parser.ArgumentSerializer[_T],
1068 name: Text,
1069 default: Iterable[_T],
1070 help: Text, # pylint: disable=redefined-builtin
1071 flag_values: _flagvalues.FlagValues = ...,
1072 module_name: Optional[Text] = ...,
1073 required: bool = ...,
1074 **args: Any
1075) -> _flagvalues.FlagHolder[List[_T]]:
1076 ...
1079@overload
1080def DEFINE_multi( # pylint: disable=invalid-name
1081 parser: _argument_parser.ArgumentParser[_T],
1082 serializer: _argument_parser.ArgumentSerializer[_T],
1083 name: Text,
1084 default: _T,
1085 help: Text, # pylint: disable=redefined-builtin
1086 flag_values: _flagvalues.FlagValues = ...,
1087 module_name: Optional[Text] = ...,
1088 required: bool = ...,
1089 **args: Any
1090) -> _flagvalues.FlagHolder[List[_T]]:
1091 ...
1094def DEFINE_multi( # pylint: disable=invalid-name,redefined-builtin
1095 parser,
1096 serializer,
1097 name,
1098 default,
1099 help,
1100 flag_values=_flagvalues.FLAGS,
1101 module_name=None,
1102 required=False,
1103 **args):
1104 """Registers a generic MultiFlag that parses its args with a given parser.
1106 Auxiliary function. Normal users should NOT use it directly.
1108 Developers who need to create their own 'Parser' classes for options
1109 which can appear multiple times can call this module function to
1110 register their flags.
1112 Args:
1113 parser: ArgumentParser, used to parse the flag arguments.
1114 serializer: ArgumentSerializer, the flag serializer instance.
1115 name: str, the flag name.
1116 default: Union[Iterable[T], Text, None], the default value of the flag. If
1117 the value is text, it will be parsed as if it was provided from the
1118 command line. If the value is a non-string iterable, it will be iterated
1119 over to create a shallow copy of the values. If it is None, it is left
1120 as-is.
1121 help: str, the help message.
1122 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1123 flag will be registered. This should almost never need to be overridden.
1124 module_name: A string, the name of the Python module declaring this flag. If
1125 not provided, it will be computed using the stack trace of this call.
1126 required: bool, is this a required flag. This must be used as a keyword
1127 argument.
1128 **args: Dictionary with extra keyword args that are passed to the
1129 ``Flag.__init__``.
1131 Returns:
1132 a handle to defined flag.
1133 """
1134 result = DEFINE_flag(
1135 _flag.MultiFlag(parser, serializer, name, default, help, **args),
1136 flag_values,
1137 module_name,
1138 required=True if required else False,
1139 )
1140 return result
1143@overload
1144def DEFINE_multi_string( # pylint: disable=invalid-name
1145 name: Text,
1146 default: Union[None, Iterable[Text], Text],
1147 help: Text, # pylint: disable=redefined-builtin
1148 flag_values: _flagvalues.FlagValues = ...,
1149 *,
1150 required: 'typing.Literal[True]',
1151 **args: Any
1152) -> _flagvalues.FlagHolder[List[Text]]:
1153 ...
1156@overload
1157def DEFINE_multi_string( # pylint: disable=invalid-name
1158 name: Text,
1159 default: None,
1160 help: Text, # pylint: disable=redefined-builtin
1161 flag_values: _flagvalues.FlagValues = ...,
1162 required: bool = ...,
1163 **args: Any
1164) -> _flagvalues.FlagHolder[Optional[List[Text]]]:
1165 ...
1168@overload
1169def DEFINE_multi_string( # pylint: disable=invalid-name
1170 name: Text,
1171 default: Union[Iterable[Text], Text],
1172 help: Text, # pylint: disable=redefined-builtin
1173 flag_values: _flagvalues.FlagValues = ...,
1174 required: bool = ...,
1175 **args: Any
1176) -> _flagvalues.FlagHolder[List[Text]]:
1177 ...
1180def DEFINE_multi_string( # pylint: disable=invalid-name,redefined-builtin
1181 name,
1182 default,
1183 help,
1184 flag_values=_flagvalues.FLAGS,
1185 required=False,
1186 **args):
1187 """Registers a flag whose value can be a list of any strings.
1189 Use the flag on the command line multiple times to place multiple
1190 string values into the list. The 'default' may be a single string
1191 (which will be converted into a single-element list) or a list of
1192 strings.
1195 Args:
1196 name: str, the flag name.
1197 default: Union[Iterable[Text], Text, None], the default value of the flag;
1198 see :func:`DEFINE_multi`.
1199 help: str, the help message.
1200 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1201 flag will be registered. This should almost never need to be overridden.
1202 required: bool, is this a required flag. This must be used as a keyword
1203 argument.
1204 **args: Dictionary with extra keyword args that are passed to the
1205 ``Flag.__init__``.
1207 Returns:
1208 a handle to defined flag.
1209 """
1210 parser = _argument_parser.ArgumentParser()
1211 serializer = _argument_parser.ArgumentSerializer()
1212 return DEFINE_multi(
1213 parser,
1214 serializer,
1215 name,
1216 default,
1217 help,
1218 flag_values,
1219 required=True if required else False,
1220 **args,
1221 )
1224@overload
1225def DEFINE_multi_integer( # pylint: disable=invalid-name
1226 name: Text,
1227 default: Union[None, Iterable[int], int, Text],
1228 help: Text, # pylint: disable=redefined-builtin
1229 lower_bound: Optional[int] = ...,
1230 upper_bound: Optional[int] = ...,
1231 flag_values: _flagvalues.FlagValues = ...,
1232 *,
1233 required: 'typing.Literal[True]',
1234 **args: Any
1235) -> _flagvalues.FlagHolder[List[int]]:
1236 ...
1239@overload
1240def DEFINE_multi_integer( # pylint: disable=invalid-name
1241 name: Text,
1242 default: None,
1243 help: Text, # pylint: disable=redefined-builtin
1244 lower_bound: Optional[int] = ...,
1245 upper_bound: Optional[int] = ...,
1246 flag_values: _flagvalues.FlagValues = ...,
1247 required: bool = ...,
1248 **args: Any
1249) -> _flagvalues.FlagHolder[Optional[List[int]]]:
1250 ...
1253@overload
1254def DEFINE_multi_integer( # pylint: disable=invalid-name
1255 name: Text,
1256 default: Union[Iterable[int], int, Text],
1257 help: Text, # pylint: disable=redefined-builtin
1258 lower_bound: Optional[int] = ...,
1259 upper_bound: Optional[int] = ...,
1260 flag_values: _flagvalues.FlagValues = ...,
1261 required: bool = ...,
1262 **args: Any
1263) -> _flagvalues.FlagHolder[List[int]]:
1264 ...
1267def DEFINE_multi_integer( # pylint: disable=invalid-name,redefined-builtin
1268 name,
1269 default,
1270 help,
1271 lower_bound=None,
1272 upper_bound=None,
1273 flag_values=_flagvalues.FLAGS,
1274 required=False,
1275 **args):
1276 """Registers a flag whose value can be a list of arbitrary integers.
1278 Use the flag on the command line multiple times to place multiple
1279 integer values into the list. The 'default' may be a single integer
1280 (which will be converted into a single-element list) or a list of
1281 integers.
1283 Args:
1284 name: str, the flag name.
1285 default: Union[Iterable[int], Text, None], the default value of the flag;
1286 see `DEFINE_multi`.
1287 help: str, the help message.
1288 lower_bound: int, min values of the flag.
1289 upper_bound: int, max values of the flag.
1290 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1291 flag will be registered. This should almost never need to be overridden.
1292 required: bool, is this a required flag. This must be used as a keyword
1293 argument.
1294 **args: Dictionary with extra keyword args that are passed to the
1295 ``Flag.__init__``.
1297 Returns:
1298 a handle to defined flag.
1299 """
1300 parser = _argument_parser.IntegerParser(lower_bound, upper_bound)
1301 serializer = _argument_parser.ArgumentSerializer()
1302 return DEFINE_multi(
1303 parser,
1304 serializer,
1305 name,
1306 default,
1307 help,
1308 flag_values,
1309 required=True if required else False,
1310 **args,
1311 )
1314@overload
1315def DEFINE_multi_float( # pylint: disable=invalid-name
1316 name: Text,
1317 default: Union[None, Iterable[float], float, Text],
1318 help: Text, # pylint: disable=redefined-builtin
1319 lower_bound: Optional[float] = ...,
1320 upper_bound: Optional[float] = ...,
1321 flag_values: _flagvalues.FlagValues = ...,
1322 *,
1323 required: 'typing.Literal[True]',
1324 **args: Any
1325) -> _flagvalues.FlagHolder[List[float]]:
1326 ...
1329@overload
1330def DEFINE_multi_float( # pylint: disable=invalid-name
1331 name: Text,
1332 default: None,
1333 help: Text, # pylint: disable=redefined-builtin
1334 lower_bound: Optional[float] = ...,
1335 upper_bound: Optional[float] = ...,
1336 flag_values: _flagvalues.FlagValues = ...,
1337 required: bool = ...,
1338 **args: Any
1339) -> _flagvalues.FlagHolder[Optional[List[float]]]:
1340 ...
1343@overload
1344def DEFINE_multi_float( # pylint: disable=invalid-name
1345 name: Text,
1346 default: Union[Iterable[float], float, Text],
1347 help: Text, # pylint: disable=redefined-builtin
1348 lower_bound: Optional[float] = ...,
1349 upper_bound: Optional[float] = ...,
1350 flag_values: _flagvalues.FlagValues = ...,
1351 required: bool = ...,
1352 **args: Any
1353) -> _flagvalues.FlagHolder[List[float]]:
1354 ...
1357def DEFINE_multi_float( # pylint: disable=invalid-name,redefined-builtin
1358 name,
1359 default,
1360 help,
1361 lower_bound=None,
1362 upper_bound=None,
1363 flag_values=_flagvalues.FLAGS,
1364 required=False,
1365 **args):
1366 """Registers a flag whose value can be a list of arbitrary floats.
1368 Use the flag on the command line multiple times to place multiple
1369 float values into the list. The 'default' may be a single float
1370 (which will be converted into a single-element list) or a list of
1371 floats.
1373 Args:
1374 name: str, the flag name.
1375 default: Union[Iterable[float], Text, None], the default value of the flag;
1376 see `DEFINE_multi`.
1377 help: str, the help message.
1378 lower_bound: float, min values of the flag.
1379 upper_bound: float, max values of the flag.
1380 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1381 flag will be registered. This should almost never need to be overridden.
1382 required: bool, is this a required flag. This must be used as a keyword
1383 argument.
1384 **args: Dictionary with extra keyword args that are passed to the
1385 ``Flag.__init__``.
1387 Returns:
1388 a handle to defined flag.
1389 """
1390 parser = _argument_parser.FloatParser(lower_bound, upper_bound)
1391 serializer = _argument_parser.ArgumentSerializer()
1392 return DEFINE_multi(
1393 parser,
1394 serializer,
1395 name,
1396 default,
1397 help,
1398 flag_values,
1399 required=True if required else False,
1400 **args,
1401 )
1404@overload
1405def DEFINE_multi_enum( # pylint: disable=invalid-name
1406 name: Text,
1407 default: Union[None, Iterable[Text], Text],
1408 enum_values: Iterable[Text],
1409 help: Text, # pylint: disable=redefined-builtin
1410 flag_values: _flagvalues.FlagValues = ...,
1411 *,
1412 required: 'typing.Literal[True]',
1413 **args: Any
1414) -> _flagvalues.FlagHolder[List[Text]]:
1415 ...
1418@overload
1419def DEFINE_multi_enum( # pylint: disable=invalid-name
1420 name: Text,
1421 default: None,
1422 enum_values: Iterable[Text],
1423 help: Text, # pylint: disable=redefined-builtin
1424 flag_values: _flagvalues.FlagValues = ...,
1425 required: bool = ...,
1426 **args: Any
1427) -> _flagvalues.FlagHolder[Optional[List[Text]]]:
1428 ...
1431@overload
1432def DEFINE_multi_enum( # pylint: disable=invalid-name
1433 name: Text,
1434 default: Union[Iterable[Text], Text],
1435 enum_values: Iterable[Text],
1436 help: Text, # pylint: disable=redefined-builtin
1437 flag_values: _flagvalues.FlagValues = ...,
1438 required: bool = ...,
1439 **args: Any
1440) -> _flagvalues.FlagHolder[List[Text]]:
1441 ...
1444def DEFINE_multi_enum( # pylint: disable=invalid-name,redefined-builtin
1445 name,
1446 default,
1447 enum_values,
1448 help,
1449 flag_values=_flagvalues.FLAGS,
1450 case_sensitive=True,
1451 required=False,
1452 **args):
1453 """Registers a flag whose value can be a list strings from enum_values.
1455 Use the flag on the command line multiple times to place multiple
1456 enum values into the list. The 'default' may be a single string
1457 (which will be converted into a single-element list) or a list of
1458 strings.
1460 Args:
1461 name: str, the flag name.
1462 default: Union[Iterable[Text], Text, None], the default value of the flag;
1463 see `DEFINE_multi`.
1464 enum_values: [str], a non-empty list of strings with the possible values for
1465 the flag.
1466 help: str, the help message.
1467 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1468 flag will be registered. This should almost never need to be overridden.
1469 case_sensitive: Whether or not the enum is to be case-sensitive.
1470 required: bool, is this a required flag. This must be used as a keyword
1471 argument.
1472 **args: Dictionary with extra keyword args that are passed to the
1473 ``Flag.__init__``.
1475 Returns:
1476 a handle to defined flag.
1477 """
1478 parser = _argument_parser.EnumParser(enum_values, case_sensitive)
1479 serializer = _argument_parser.ArgumentSerializer()
1480 return DEFINE_multi(
1481 parser,
1482 serializer,
1483 name,
1484 default,
1485 '<%s>: %s' % ('|'.join(enum_values), help),
1486 flag_values,
1487 required=True if required else False,
1488 **args,
1489 )
1492@overload
1493def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1494 name: Text,
1495 # This is separate from `Union[None, _ET, Iterable[Text], Text]` to avoid a
1496 # Pytype issue inferring the return value to
1497 # FlagHolder[List[Union[_ET, enum.Enum]]] when an iterable of concrete enum
1498 # subclasses are used.
1499 default: Iterable[_ET],
1500 enum_class: Type[_ET],
1501 help: Text, # pylint: disable=redefined-builtin
1502 flag_values: _flagvalues.FlagValues = ...,
1503 module_name: Optional[Text] = ...,
1504 *,
1505 required: 'typing.Literal[True]',
1506 **args: Any
1507) -> _flagvalues.FlagHolder[List[_ET]]:
1508 ...
1511@overload
1512def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1513 name: Text,
1514 default: Union[None, _ET, Iterable[Text], Text],
1515 enum_class: Type[_ET],
1516 help: Text, # pylint: disable=redefined-builtin
1517 flag_values: _flagvalues.FlagValues = ...,
1518 module_name: Optional[Text] = ...,
1519 *,
1520 required: 'typing.Literal[True]',
1521 **args: Any
1522) -> _flagvalues.FlagHolder[List[_ET]]:
1523 ...
1526@overload
1527def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1528 name: Text,
1529 default: None,
1530 enum_class: Type[_ET],
1531 help: Text, # pylint: disable=redefined-builtin
1532 flag_values: _flagvalues.FlagValues = ...,
1533 module_name: Optional[Text] = ...,
1534 required: bool = ...,
1535 **args: Any
1536) -> _flagvalues.FlagHolder[Optional[List[_ET]]]:
1537 ...
1540@overload
1541def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1542 name: Text,
1543 # This is separate from `Union[None, _ET, Iterable[Text], Text]` to avoid a
1544 # Pytype issue inferring the return value to
1545 # FlagHolder[List[Union[_ET, enum.Enum]]] when an iterable of concrete enum
1546 # subclasses are used.
1547 default: Iterable[_ET],
1548 enum_class: Type[_ET],
1549 help: Text, # pylint: disable=redefined-builtin
1550 flag_values: _flagvalues.FlagValues = ...,
1551 module_name: Optional[Text] = ...,
1552 required: bool = ...,
1553 **args: Any
1554) -> _flagvalues.FlagHolder[List[_ET]]:
1555 ...
1558@overload
1559def DEFINE_multi_enum_class( # pylint: disable=invalid-name
1560 name: Text,
1561 default: Union[_ET, Iterable[Text], Text],
1562 enum_class: Type[_ET],
1563 help: Text, # pylint: disable=redefined-builtin
1564 flag_values: _flagvalues.FlagValues = ...,
1565 module_name: Optional[Text] = ...,
1566 required: bool = ...,
1567 **args: Any
1568) -> _flagvalues.FlagHolder[List[_ET]]:
1569 ...
1572def DEFINE_multi_enum_class( # pylint: disable=invalid-name,redefined-builtin
1573 name,
1574 default,
1575 enum_class,
1576 help,
1577 flag_values=_flagvalues.FLAGS,
1578 module_name=None,
1579 case_sensitive=False,
1580 required=False,
1581 **args):
1582 """Registers a flag whose value can be a list of enum members.
1584 Use the flag on the command line multiple times to place multiple
1585 enum values into the list.
1587 Args:
1588 name: str, the flag name.
1589 default: Union[Iterable[Enum], Iterable[Text], Enum, Text, None], the
1590 default value of the flag; see `DEFINE_multi`; only differences are
1591 documented here. If the value is a single Enum, it is treated as a
1592 single-item list of that Enum value. If it is an iterable, text values
1593 within the iterable will be converted to the equivalent Enum objects.
1594 enum_class: class, the Enum class with all the possible values for the flag.
1595 help: str, the help message.
1596 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1597 flag will be registered. This should almost never need to be overridden.
1598 module_name: A string, the name of the Python module declaring this flag. If
1599 not provided, it will be computed using the stack trace of this call.
1600 case_sensitive: bool, whether to map strings to members of the enum_class
1601 without considering case.
1602 required: bool, is this a required flag. This must be used as a keyword
1603 argument.
1604 **args: Dictionary with extra keyword args that are passed to the
1605 ``Flag.__init__``.
1607 Returns:
1608 a handle to defined flag.
1609 """
1610 # NOTE: pytype fails if this is a direct return.
1611 result = DEFINE_flag(
1612 _flag.MultiEnumClassFlag(
1613 name,
1614 default,
1615 help,
1616 enum_class,
1617 case_sensitive=case_sensitive,
1618 **args,
1619 ),
1620 flag_values,
1621 module_name,
1622 required=True if required else False,
1623 )
1624 return result
1627def DEFINE_alias( # pylint: disable=invalid-name
1628 name: Text,
1629 original_name: Text,
1630 flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS,
1631 module_name: Optional[Text] = None,
1632) -> _flagvalues.FlagHolder[Any]:
1633 """Defines an alias flag for an existing one.
1635 Args:
1636 name: str, the flag name.
1637 original_name: str, the original flag name.
1638 flag_values: :class:`FlagValues`, the FlagValues instance with which the
1639 flag will be registered. This should almost never need to be overridden.
1640 module_name: A string, the name of the module that defines this flag.
1642 Returns:
1643 a handle to defined flag.
1645 Raises:
1646 flags.FlagError:
1647 UnrecognizedFlagError: if the referenced flag doesn't exist.
1648 DuplicateFlagError: if the alias name has been used by some existing flag.
1649 """
1650 if original_name not in flag_values:
1651 raise _exceptions.UnrecognizedFlagError(original_name)
1652 flag = flag_values[original_name]
1654 class _FlagAlias(_flag.Flag):
1655 """Overrides Flag class so alias value is copy of original flag value."""
1657 def parse(self, argument):
1658 flag.parse(argument)
1659 self.present += 1
1661 def _parse_from_default(self, value):
1662 # The value was already parsed by the aliased flag, so there is no
1663 # need to call the parser on it a second time.
1664 # Additionally, because of how MultiFlag parses and merges values,
1665 # it isn't possible to delegate to the aliased flag and still get
1666 # the correct values.
1667 return value
1669 @property
1670 def value(self):
1671 return flag.value
1673 @value.setter
1674 def value(self, value):
1675 flag.value = value
1677 help_msg = 'Alias for --%s.' % flag.name
1678 # If alias_name has been used, flags.DuplicatedFlag will be raised.
1679 return DEFINE_flag(
1680 _FlagAlias(
1681 flag.parser,
1682 flag.serializer,
1683 name,
1684 flag.default,
1685 help_msg,
1686 boolean=flag.boolean), flag_values, module_name)