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