Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Copyright 2017 The Abseil Authors.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14"""This package is used to define and parse command line flags.
16This package defines a *distributed* flag-definition policy: rather than
17an application having to define all flags in or near main(), each Python
18module defines flags that are useful to it. When one Python module
19imports another, it gains access to the other's flags. (This is
20implemented by having all modules share a common, global registry object
21containing all the flag information.)
23Flags are defined through the use of one of the DEFINE_xxx functions.
24The specific function used determines how the flag is parsed, checked,
25and optionally type-converted, when it's seen on the command line.
26"""
28import sys
30from absl.flags import _argument_parser
31from absl.flags import _defines
32from absl.flags import _exceptions
33from absl.flags import _flag
34from absl.flags import _flagvalues
35from absl.flags import _helpers
36from absl.flags import _validators
38__all__ = (
39 'DEFINE',
40 'DEFINE_flag',
41 'DEFINE_string',
42 'DEFINE_boolean',
43 'DEFINE_bool',
44 'DEFINE_float',
45 'DEFINE_integer',
46 'DEFINE_enum',
47 'DEFINE_enum_class',
48 'DEFINE_list',
49 'DEFINE_spaceseplist',
50 'DEFINE_multi',
51 'DEFINE_multi_string',
52 'DEFINE_multi_integer',
53 'DEFINE_multi_float',
54 'DEFINE_multi_enum',
55 'DEFINE_multi_enum_class',
56 'DEFINE_alias',
57 # Flag validators.
58 'register_validator',
59 'validator',
60 'register_multi_flags_validator',
61 'multi_flags_validator',
62 'mark_flag_as_required',
63 'mark_flags_as_required',
64 'mark_flags_as_mutual_exclusive',
65 'mark_bool_flags_as_mutual_exclusive',
66 # Flag modifiers.
67 'set_default',
68 'override_value',
69 # Key flag related functions.
70 'declare_key_flag',
71 'adopt_module_key_flags',
72 'disclaim_key_flags',
73 # Module exceptions.
74 'Error',
75 'CantOpenFlagFileError',
76 'DuplicateFlagError',
77 'IllegalFlagValueError',
78 'UnrecognizedFlagError',
79 'UnparsedFlagAccessError',
80 'ValidationError',
81 'FlagNameConflictsWithMethodError',
82 # Public classes.
83 'Flag',
84 'BooleanFlag',
85 'EnumFlag',
86 'EnumClassFlag',
87 'MultiFlag',
88 'MultiEnumClassFlag',
89 'FlagHolder',
90 'FlagValues',
91 'ArgumentParser',
92 'BooleanParser',
93 'EnumParser',
94 'EnumClassParser',
95 'ArgumentSerializer',
96 'FloatParser',
97 'IntegerParser',
98 'BaseListParser',
99 'ListParser',
100 'ListSerializer',
101 'EnumClassListSerializer',
102 'CsvListSerializer',
103 'WhitespaceSeparatedListParser',
104 'EnumClassSerializer',
105 # Helper functions.
106 'get_help_width',
107 'text_wrap',
108 'flag_dict_to_args',
109 'doc_to_help',
110 # The global FlagValues instance.
111 'FLAGS',
112)
114# Initialize the FLAGS_MODULE as early as possible.
115# It's only used by adopt_module_key_flags to take SPECIAL_FLAGS into account.
116_helpers.FLAGS_MODULE = sys.modules[__name__]
118# Add current module to disclaimed module ids.
119_helpers.disclaim_module_ids.add(id(sys.modules[__name__]))
121# DEFINE functions. They are explained in more details in the module doc string.
122# pylint: disable=invalid-name
123DEFINE = _defines.DEFINE
124DEFINE_flag = _defines.DEFINE_flag
125DEFINE_string = _defines.DEFINE_string
126DEFINE_boolean = _defines.DEFINE_boolean
127DEFINE_bool = DEFINE_boolean # Match C++ API.
128DEFINE_float = _defines.DEFINE_float
129DEFINE_integer = _defines.DEFINE_integer
130DEFINE_enum = _defines.DEFINE_enum
131DEFINE_enum_class = _defines.DEFINE_enum_class
132DEFINE_list = _defines.DEFINE_list
133DEFINE_spaceseplist = _defines.DEFINE_spaceseplist
134DEFINE_multi = _defines.DEFINE_multi
135DEFINE_multi_string = _defines.DEFINE_multi_string
136DEFINE_multi_integer = _defines.DEFINE_multi_integer
137DEFINE_multi_float = _defines.DEFINE_multi_float
138DEFINE_multi_enum = _defines.DEFINE_multi_enum
139DEFINE_multi_enum_class = _defines.DEFINE_multi_enum_class
140DEFINE_alias = _defines.DEFINE_alias
141# pylint: enable=invalid-name
143# Flag validators.
144register_validator = _validators.register_validator
145validator = _validators.validator
146register_multi_flags_validator = _validators.register_multi_flags_validator
147multi_flags_validator = _validators.multi_flags_validator
148mark_flag_as_required = _validators.mark_flag_as_required
149mark_flags_as_required = _validators.mark_flags_as_required
150mark_flags_as_mutual_exclusive = _validators.mark_flags_as_mutual_exclusive
151mark_bool_flags_as_mutual_exclusive = _validators.mark_bool_flags_as_mutual_exclusive
153# Flag modifiers.
154set_default = _defines.set_default
155override_value = _defines.override_value
157# Key flag related functions.
158declare_key_flag = _defines.declare_key_flag
159adopt_module_key_flags = _defines.adopt_module_key_flags
160disclaim_key_flags = _defines.disclaim_key_flags
162# Module exceptions.
163# pylint: disable=invalid-name
164Error = _exceptions.Error
165CantOpenFlagFileError = _exceptions.CantOpenFlagFileError
166DuplicateFlagError = _exceptions.DuplicateFlagError
167IllegalFlagValueError = _exceptions.IllegalFlagValueError
168UnrecognizedFlagError = _exceptions.UnrecognizedFlagError
169UnparsedFlagAccessError = _exceptions.UnparsedFlagAccessError
170ValidationError = _exceptions.ValidationError
171FlagNameConflictsWithMethodError = _exceptions.FlagNameConflictsWithMethodError
173# Public classes.
174Flag = _flag.Flag
175BooleanFlag = _flag.BooleanFlag
176EnumFlag = _flag.EnumFlag
177EnumClassFlag = _flag.EnumClassFlag
178MultiFlag = _flag.MultiFlag
179MultiEnumClassFlag = _flag.MultiEnumClassFlag
180FlagHolder = _flagvalues.FlagHolder
181FlagValues = _flagvalues.FlagValues
182ArgumentParser = _argument_parser.ArgumentParser
183BooleanParser = _argument_parser.BooleanParser
184EnumParser = _argument_parser.EnumParser
185EnumClassParser = _argument_parser.EnumClassParser
186ArgumentSerializer = _argument_parser.ArgumentSerializer
187FloatParser = _argument_parser.FloatParser
188IntegerParser = _argument_parser.IntegerParser
189BaseListParser = _argument_parser.BaseListParser
190ListParser = _argument_parser.ListParser
191ListSerializer = _argument_parser.ListSerializer
192EnumClassListSerializer = _argument_parser.EnumClassListSerializer
193CsvListSerializer = _argument_parser.CsvListSerializer
194WhitespaceSeparatedListParser = _argument_parser.WhitespaceSeparatedListParser
195EnumClassSerializer = _argument_parser.EnumClassSerializer
196# pylint: enable=invalid-name
198# Helper functions.
199get_help_width = _helpers.get_help_width
200text_wrap = _helpers.text_wrap
201flag_dict_to_args = _helpers.flag_dict_to_args
202doc_to_help = _helpers.doc_to_help
204# Special flags.
205_helpers.SPECIAL_FLAGS = FlagValues()
207DEFINE_string(
208 'flagfile', '',
209 'Insert flag definitions from the given file into the command line.',
210 _helpers.SPECIAL_FLAGS) # pytype: disable=wrong-arg-types
212DEFINE_string('undefok', '',
213 'comma-separated list of flag names that it is okay to specify '
214 'on the command line even if the program does not define a flag '
215 'with that name. IMPORTANT: flags in this list that have '
216 'arguments MUST use the --flag=value format.',
217 _helpers.SPECIAL_FLAGS) # pytype: disable=wrong-arg-types
219#: The global FlagValues instance.
220FLAGS = _flagvalues.FLAGS