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.
15
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.)
22
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"""
27
28import getopt
29import os
30import re
31import sys
32import types
33import warnings
34
35from absl.flags import _argument_parser
36from absl.flags import _defines
37from absl.flags import _exceptions
38from absl.flags import _flag
39from absl.flags import _flagvalues
40from absl.flags import _helpers
41from absl.flags import _validators
42
43__all__ = (
44    'DEFINE',
45    'DEFINE_flag',
46    'DEFINE_string',
47    'DEFINE_boolean',
48    'DEFINE_bool',
49    'DEFINE_float',
50    'DEFINE_integer',
51    'DEFINE_enum',
52    'DEFINE_enum_class',
53    'DEFINE_list',
54    'DEFINE_spaceseplist',
55    'DEFINE_multi',
56    'DEFINE_multi_string',
57    'DEFINE_multi_integer',
58    'DEFINE_multi_float',
59    'DEFINE_multi_enum',
60    'DEFINE_multi_enum_class',
61    'DEFINE_alias',
62    # Flag validators.
63    'register_validator',
64    'validator',
65    'register_multi_flags_validator',
66    'multi_flags_validator',
67    'mark_flag_as_required',
68    'mark_flags_as_required',
69    'mark_flags_as_mutual_exclusive',
70    'mark_bool_flags_as_mutual_exclusive',
71    # Flag modifiers.
72    'set_default',
73    'override_value',
74    # Key flag related functions.
75    'declare_key_flag',
76    'adopt_module_key_flags',
77    'disclaim_key_flags',
78    # Module exceptions.
79    'Error',
80    'CantOpenFlagFileError',
81    'DuplicateFlagError',
82    'IllegalFlagValueError',
83    'UnrecognizedFlagError',
84    'UnparsedFlagAccessError',
85    'ValidationError',
86    'FlagNameConflictsWithMethodError',
87    # Public classes.
88    'Flag',
89    'BooleanFlag',
90    'EnumFlag',
91    'EnumClassFlag',
92    'MultiFlag',
93    'MultiEnumClassFlag',
94    'FlagHolder',
95    'FlagValues',
96    'ArgumentParser',
97    'BooleanParser',
98    'EnumParser',
99    'EnumClassParser',
100    'ArgumentSerializer',
101    'FloatParser',
102    'IntegerParser',
103    'BaseListParser',
104    'ListParser',
105    'ListSerializer',
106    'EnumClassListSerializer',
107    'CsvListSerializer',
108    'WhitespaceSeparatedListParser',
109    'EnumClassSerializer',
110    # Helper functions.
111    'get_help_width',
112    'text_wrap',
113    'flag_dict_to_args',
114    'doc_to_help',
115    # The global FlagValues instance.
116    'FLAGS',
117)
118
119# Initialize the FLAGS_MODULE as early as possible.
120# It's only used by adopt_module_key_flags to take SPECIAL_FLAGS into account.
121_helpers.FLAGS_MODULE = sys.modules[__name__]
122
123# Add current module to disclaimed module ids.
124_helpers.disclaim_module_ids.add(id(sys.modules[__name__]))
125
126# DEFINE functions. They are explained in more details in the module doc string.
127# pylint: disable=invalid-name
128DEFINE = _defines.DEFINE
129DEFINE_flag = _defines.DEFINE_flag
130DEFINE_string = _defines.DEFINE_string
131DEFINE_boolean = _defines.DEFINE_boolean
132DEFINE_bool = DEFINE_boolean  # Match C++ API.
133DEFINE_float = _defines.DEFINE_float
134DEFINE_integer = _defines.DEFINE_integer
135DEFINE_enum = _defines.DEFINE_enum
136DEFINE_enum_class = _defines.DEFINE_enum_class
137DEFINE_list = _defines.DEFINE_list
138DEFINE_spaceseplist = _defines.DEFINE_spaceseplist
139DEFINE_multi = _defines.DEFINE_multi
140DEFINE_multi_string = _defines.DEFINE_multi_string
141DEFINE_multi_integer = _defines.DEFINE_multi_integer
142DEFINE_multi_float = _defines.DEFINE_multi_float
143DEFINE_multi_enum = _defines.DEFINE_multi_enum
144DEFINE_multi_enum_class = _defines.DEFINE_multi_enum_class
145DEFINE_alias = _defines.DEFINE_alias
146# pylint: enable=invalid-name
147
148# Flag validators.
149register_validator = _validators.register_validator
150validator = _validators.validator
151register_multi_flags_validator = _validators.register_multi_flags_validator
152multi_flags_validator = _validators.multi_flags_validator
153mark_flag_as_required = _validators.mark_flag_as_required
154mark_flags_as_required = _validators.mark_flags_as_required
155mark_flags_as_mutual_exclusive = _validators.mark_flags_as_mutual_exclusive
156mark_bool_flags_as_mutual_exclusive = _validators.mark_bool_flags_as_mutual_exclusive
157
158# Flag modifiers.
159set_default = _defines.set_default
160override_value = _defines.override_value
161
162# Key flag related functions.
163declare_key_flag = _defines.declare_key_flag
164adopt_module_key_flags = _defines.adopt_module_key_flags
165disclaim_key_flags = _defines.disclaim_key_flags
166
167# Module exceptions.
168# pylint: disable=invalid-name
169Error = _exceptions.Error
170CantOpenFlagFileError = _exceptions.CantOpenFlagFileError
171DuplicateFlagError = _exceptions.DuplicateFlagError
172IllegalFlagValueError = _exceptions.IllegalFlagValueError
173UnrecognizedFlagError = _exceptions.UnrecognizedFlagError
174UnparsedFlagAccessError = _exceptions.UnparsedFlagAccessError
175ValidationError = _exceptions.ValidationError
176FlagNameConflictsWithMethodError = _exceptions.FlagNameConflictsWithMethodError
177
178# Public classes.
179Flag = _flag.Flag
180BooleanFlag = _flag.BooleanFlag
181EnumFlag = _flag.EnumFlag
182EnumClassFlag = _flag.EnumClassFlag
183MultiFlag = _flag.MultiFlag
184MultiEnumClassFlag = _flag.MultiEnumClassFlag
185FlagHolder = _flagvalues.FlagHolder
186FlagValues = _flagvalues.FlagValues
187ArgumentParser = _argument_parser.ArgumentParser
188BooleanParser = _argument_parser.BooleanParser
189EnumParser = _argument_parser.EnumParser
190EnumClassParser = _argument_parser.EnumClassParser
191ArgumentSerializer = _argument_parser.ArgumentSerializer
192FloatParser = _argument_parser.FloatParser
193IntegerParser = _argument_parser.IntegerParser
194BaseListParser = _argument_parser.BaseListParser
195ListParser = _argument_parser.ListParser
196ListSerializer = _argument_parser.ListSerializer
197EnumClassListSerializer = _argument_parser.EnumClassListSerializer
198CsvListSerializer = _argument_parser.CsvListSerializer
199WhitespaceSeparatedListParser = _argument_parser.WhitespaceSeparatedListParser
200EnumClassSerializer = _argument_parser.EnumClassSerializer
201# pylint: enable=invalid-name
202
203# Helper functions.
204get_help_width = _helpers.get_help_width
205text_wrap = _helpers.text_wrap
206flag_dict_to_args = _helpers.flag_dict_to_args
207doc_to_help = _helpers.doc_to_help
208
209# Special flags.
210_helpers.SPECIAL_FLAGS = FlagValues()
211
212DEFINE_string(
213    'flagfile', '',
214    'Insert flag definitions from the given file into the command line.',
215    _helpers.SPECIAL_FLAGS)  # pytype: disable=wrong-arg-types
216
217DEFINE_string('undefok', '',
218              'comma-separated list of flag names that it is okay to specify '
219              'on the command line even if the program does not define a flag '
220              'with that name.  IMPORTANT: flags in this list that have '
221              'arguments MUST use the --flag=value format.',
222              _helpers.SPECIAL_FLAGS)  # pytype: disable=wrong-arg-types
223
224#: The global FlagValues instance.
225FLAGS = _flagvalues.FLAGS
226