3 """Global configuration driven by commandline arguments (even across
4 different modules). Usage:
10 parser = config.add_commandline_args(
12 "Args related to module doing the thing.",
15 "--module_do_the_thing",
18 help="Should the module do the thing?"
26 parser = config.add_commandline_args(
28 "A program that does the thing.",
34 help="Should we really do the thing?"
36 config.parse() # Very important, this must be invoked!
38 If you set this up and remember to invoke config.parse(), all commandline
39 arguments will play nicely together:
43 [--module_do_the_thing MODULE_DO_THE_THING]
47 Args related to module doing the thing.
49 --module_do_the_thing MODULE_DO_THE_THING
50 Should the module do the thing?
53 A program that does the thing
56 Should we really do the thing?
58 Arguments themselves should be accessed via
59 config.config['arg_name']. e.g.
61 if not config.config['dry_run']:
71 from typing import Any, Dict, List, Optional
73 # This module is commonly used by others in here and should avoid
74 # taking any unnecessary dependencies back on them.
76 # Defer logging messages until later when logging has been initialized.
77 saved_messages: List[str] = []
79 # Make a copy of the original program arguments.
80 program_name = os.path.basename(sys.argv[0])
81 original_argv = [arg for arg in sys.argv]
84 # A global parser that we will collect arguments into.
85 args = argparse.ArgumentParser(
87 formatter_class=argparse.ArgumentDefaultsHelpFormatter,
88 fromfile_prefix_chars="@",
89 epilog=f'------------------------------------------------------------------------------\n{program_name} uses config.py ({__file__}) for global, cross-module configuration setup and parsing.\n------------------------------------------------------------------------------'
92 # Keep track of if we've been called and prevent being called more
94 config_parse_called = False
96 # A global configuration dictionary that will contain parsed arguments.
97 # It is also this variable that modules use to access parsed arguments.
98 # This is the data that is most interesting to our callers; it will hold
99 # the configuration result.
100 config: Dict[str, Any] = {}
103 def add_commandline_args(title: str, description: str = ""):
104 """Create a new context for arguments and return a handle."""
105 return args.add_argument_group(title, description)
108 group = add_commandline_args(
109 f'Global Config ({__file__})',
110 'Args that control the global config itself; how meta!',
116 help='Config file (populated via --config_savefile) from which to read args in lieu or in addition to commandline.',
122 help='Display the global configuration on STDERR at program startup.',
129 help='Populate config file compatible with --config_loadfile to save config for later use.',
133 def is_flag_already_in_argv(var: str):
134 """Is a particular flag passed on the commandline?"""
141 def parse(entry_module: Optional[str]) -> Dict[str, Any]:
142 """Main program should call this early in main()"""
143 global config_parse_called
144 if config_parse_called:
147 global saved_messages
149 # If we're about to do the usage message dump, put the main module's
150 # argument group last in the list (if possible) so that when the user
151 # passes -h or --help, it will be visible on the screen w/o scrolling.
152 reordered_action_groups = []
155 if arg == '--help' or arg == '-h':
156 for group in args._action_groups:
157 if entry_module is not None and entry_module in group.title:
158 reordered_action_groups.append(group)
159 elif program_name in group.title:
160 reordered_action_groups.append(group)
162 reordered_action_groups.insert(0, group)
163 args._action_groups = reordered_action_groups
165 # Examine the environment variables that match known flags. For a
166 # flag called --example_flag the corresponding environment
167 # variable would be called EXAMPLE_FLAG.
168 usage_message = args.format_usage()
171 for x in usage_message.split():
185 # Environment vars the same as flag names without
186 # the initial -'s and in UPPERCASE.
187 env = var.strip('-').upper()
188 if env in os.environ:
189 if not is_flag_already_in_argv(var):
190 value = os.environ[env]
191 saved_messages.append(
192 f'Initialized from environment: {var} = {value}'
194 from string_utils import to_bool
195 if len(chunks) == 1 and to_bool(value):
197 elif len(chunks) > 1:
199 sys.argv.append(value)
205 # Look for loadfile and read/parse it if present.
207 saw_other_args = False
208 grab_next_arg = False
209 for arg in sys.argv[1:]:
210 if 'config_loadfile' in arg:
211 pieces = arg.split('=')
219 saw_other_args = True
221 if loadfile is not None:
223 msg = f'Augmenting commandline arguments with those from {loadfile}.'
224 print(msg, file=sys.stderr)
225 saved_messages.append(msg)
226 if not os.path.exists(loadfile):
227 print(f'ERROR: --config_loadfile argument must be a file, {loadfile} not found.',
230 with open(loadfile, 'r') as rf:
231 newargs = rf.readlines()
232 newargs = [arg.strip('\n') for arg in newargs if 'config_savefile' not in arg]
235 # Parse (possibly augmented, possibly completely overwritten)
236 # commandline args with argparse normally and populate config.
237 known, unknown = args.parse_known_args()
238 config.update(vars(known))
240 # Reconstruct the argv with unrecognized flags for the benefit of
241 # future argument parsers. For example, unittest_main in python
242 # has some of its own flags. If we didn't recognize it, maybe
244 sys.argv = sys.argv[:1] + unknown
246 # Check for savefile and populate it if requested.
247 savefile = config['config_savefile']
248 if savefile and len(savefile) > 0:
249 with open(savefile, 'w') as wf:
251 "\n".join(original_argv[1:])
254 # Also dump the config on stderr if requested.
255 if config['config_dump']:
258 config_parse_called = True
262 def has_been_parsed() -> bool:
263 """Has the global config been parsed yet?"""
264 global config_parse_called
265 return config_parse_called
269 """Print the current config to stdout."""
270 print("Global Configuration:", file=sys.stderr)
271 pprint.pprint(config, stream=sys.stderr)
276 """Log messages saved earlier now that logging has been initialized."""
277 logger = logging.getLogger(__name__)
278 global saved_messages
279 for _ in saved_messages: