3 # © Copyright 2021-2022, Scott Gasch
5 """Global configuration driven by commandline arguments, environment variables
6 and saved configuration files. This works across several modules.
14 parser = config.add_commandline_args(
16 "Args related to module doing the thing.",
19 "--module_do_the_thing",
22 help="Should the module do the thing?"
30 parser = config.add_commandline_args(
32 "A program that does the thing.",
38 help="Should we really do the thing?"
40 config.parse() # Very important, this must be invoked!
42 If you set this up and remember to invoke config.parse(), all commandline
43 arguments will play nicely together. This is done automatically for you
44 if you're using the bootstrap module's initialize wrapper.::
48 [--module_do_the_thing MODULE_DO_THE_THING]
52 Args related to module doing the thing.
54 --module_do_the_thing MODULE_DO_THE_THING
55 Should the module do the thing?
58 A program that does the thing
61 Should we really do the thing?
63 Arguments themselves should be accessed via
64 :code:`config.config['arg_name']`. e.g.::
66 if not config.config['dry_run']:
76 from typing import Any, Dict, List, Optional
78 # This module is commonly used by others in here and should avoid
79 # taking any unnecessary dependencies back on them.
81 # Defer logging messages until later when logging has been initialized.
82 SAVED_MESSAGES: List[str] = []
84 # Make a copy of the original program arguments.
85 PROGRAM_NAME: str = os.path.basename(sys.argv[0])
86 ORIG_ARGV: List[str] = sys.argv.copy()
89 class OptionalRawFormatter(argparse.HelpFormatter):
90 """This formatter has the same bahavior as the normal argparse text
91 formatter except when the help text of an argument begins with
92 "RAW|". In that case, the line breaks are preserved and the text
95 Use this, for example, when you need the helptext of an argument
96 to have its spacing preserved exactly, e.g.::
102 choices=['CHEAT', 'AUTOPLAY', 'SELFTEST', 'PRECOMPUTE', 'PLAY'],
104 help='''RAW|Our mode of operation. One of:
106 PLAY = play wordle with me! Pick a random solution or
107 specify a solution with --template.
109 CHEAT = given a --template and, optionally, --letters_in_word
110 and/or --letters_to_avoid, return the best guess word;
112 AUTOPLAY = given a complete word in --template, guess it step
113 by step showing work;
115 SELFTEST = autoplay every possible solution keeping track of
116 wins/losses and average number of guesses;
118 PRECOMPUTE = populate hash table with optimal guesses.
124 def _split_lines(self, text, width):
125 if text.startswith('RAW|'):
126 return text[4:].splitlines()
127 return argparse.HelpFormatter._split_lines(self, text, width)
130 # A global parser that we will collect arguments into.
131 ARGS = argparse.ArgumentParser(
133 formatter_class=OptionalRawFormatter,
134 fromfile_prefix_chars="@",
135 epilog=f'{PROGRAM_NAME} uses config.py ({__file__}) for global, cross-module configuration setup and parsing.',
136 # I don't fully understand why but when loaded by sphinx sometimes
137 # the same module is loaded many times causing any arguments it
138 # registers via module-level code to be redefined. Work around
139 # this iff the program is 'sphinx-build'
140 conflict_handler='resolve' if PROGRAM_NAME == 'sphinx-build' else 'error',
143 # Keep track of if we've been called and prevent being called more
145 CONFIG_PARSE_CALLED = False
148 # A global configuration dictionary that will contain parsed arguments.
149 # It is also this variable that modules use to access parsed arguments.
150 # This is the data that is most interesting to our callers; it will hold
151 # the configuration result.
152 config: Dict[str, Any] = {}
154 # It would be really nice if this shit worked from interactive python
157 def add_commandline_args(title: str, description: str = "") -> argparse._ArgumentGroup:
158 """Create a new context for arguments and return a handle.
161 title: A title for your module's commandline arguments group.
162 description: A helpful description of your module.
165 An argparse._ArgumentGroup to be populated by the caller.
167 return ARGS.add_argument_group(title, description)
170 group = add_commandline_args(
171 f'Global Config ({__file__})',
172 'Args that control the global config itself; how meta!',
178 help='Config file (populated via --config_savefile) from which to read args in lieu or in addition to commandline.',
184 help='Display the global configuration (possibly derived from multiple sources) on STDERR at program startup.',
191 help='Populate config file compatible with --config_loadfile to save global config for later use.',
194 '--config_rejects_unrecognized_arguments',
198 'If present, config will raise an exception if it doesn\'t recognize an argument. The '
199 + 'default behavior is to ignore this so as to allow interoperability with programs that '
200 + 'want to use their own argparse calls to parse their own, separate commandline args.'
205 def overwrite_argparse_epilog(msg: str) -> None:
206 """Allows your code to override the default epilog created by
210 msg: The epilog message to substitute for the default.
215 def is_flag_already_in_argv(var: str) -> bool:
216 """Returns true if a particular flag is passed on the commandline?
219 var: The flag to search for.
227 def _reorder_arg_action_groups_before_help(entry_module: Optional[str]):
228 """Internal. Used to reorder the arguments before dumping out a
229 generated help string such that the main program's arguments come
233 reordered_action_groups = []
234 for grp in ARGS._action_groups:
235 if entry_module is not None and entry_module in grp.title: # type: ignore
236 reordered_action_groups.append(grp)
237 elif PROGRAM_NAME in group.title: # type: ignore
238 reordered_action_groups.append(grp)
240 reordered_action_groups.insert(0, grp)
241 return reordered_action_groups
244 def _augment_sys_argv_from_environment_variables():
245 """Internal. Look at the system environment for variables that match
246 arg names. This is done via some munging such that:
248 :code:`--argument_to_match`
252 :code:`ARGUMENT_TO_MATCH`
254 This allows programmers to set args via shell environment variables
255 in lieu of passing them on the cmdline.
259 usage_message = ARGS.format_usage()
262 for x in usage_message.split():
276 # Environment vars the same as flag names without
277 # the initial -'s and in UPPERCASE.
278 env = var.strip('-').upper()
279 if env in os.environ:
280 if not is_flag_already_in_argv(var):
281 value = os.environ[env]
282 SAVED_MESSAGES.append(f'Initialized from environment: {var} = {value}')
283 from string_utils import to_bool
285 if len(chunks) == 1 and to_bool(value):
287 elif len(chunks) > 1:
289 sys.argv.append(value)
294 def _augment_sys_argv_from_loadfile():
295 """Internal. Augment with arguments persisted in a saved file."""
298 saw_other_args = False
299 grab_next_arg = False
300 for arg in sys.argv[1:]:
301 if 'config_loadfile' in arg:
302 pieces = arg.split('=')
310 saw_other_args = True
312 if loadfile is not None:
313 if not os.path.exists(loadfile):
315 f'ERROR: --config_loadfile argument must be a file, {loadfile} not found.'
318 msg = f'Augmenting commandline arguments with those from {loadfile}.'
320 msg = f'Reading commandline arguments from {loadfile}.'
321 print(msg, file=sys.stderr)
322 SAVED_MESSAGES.append(msg)
324 with open(loadfile, 'r') as rf:
325 newargs = rf.readlines()
326 newargs = [arg.strip('\n') for arg in newargs if 'config_savefile' not in arg]
330 def parse(entry_module: Optional[str]) -> Dict[str, Any]:
331 """Main program should call this early in main(). Note that the
332 :code:`bootstrap.initialize` wrapper takes care of this automatically.
333 This should only be called once per program invocation.
336 global CONFIG_PARSE_CALLED
337 if CONFIG_PARSE_CALLED:
340 # If we're about to do the usage message dump, put the main
341 # module's argument group last in the list (if possible) so that
342 # when the user passes -h or --help, it will be visible on the
343 # screen w/o scrolling.
345 if arg in ('--help', '-h'):
346 if entry_module is not None:
347 entry_module = os.path.basename(entry_module)
348 ARGS._action_groups = _reorder_arg_action_groups_before_help(entry_module)
350 # Examine the environment for variables that match known flags.
351 # For a flag called --example_flag the corresponding environment
352 # variable would be called EXAMPLE_FLAG. If found, hackily add
353 # these into sys.argv to be parsed.
354 _augment_sys_argv_from_environment_variables()
356 # Look for loadfile and read/parse it if present. This also
357 # works by jamming these values onto sys.argv.
358 _augment_sys_argv_from_loadfile()
360 # Parse (possibly augmented, possibly completely overwritten)
361 # commandline args with argparse normally and populate config.
362 known, unknown = ARGS.parse_known_args()
363 config.update(vars(known))
365 # Reconstruct the argv with unrecognized flags for the benefit of
366 # future argument parsers. For example, unittest_main in python
367 # has some of its own flags. If we didn't recognize it, maybe
370 if config['config_rejects_unrecognized_arguments']:
372 f'Encountered unrecognized config argument(s) {unknown} with --config_rejects_unrecognized_arguments enabled; halting.'
374 SAVED_MESSAGES.append(f'Config encountered unrecognized commandline arguments: {unknown}')
375 sys.argv = sys.argv[:1] + unknown
377 # Check for savefile and populate it if requested.
378 savefile = config['config_savefile']
379 if savefile and len(savefile) > 0:
380 with open(savefile, 'w') as wf:
381 wf.write("\n".join(ORIG_ARGV[1:]))
383 # Also dump the config on stderr if requested.
384 if config['config_dump']:
387 CONFIG_PARSE_CALLED = True
391 def has_been_parsed() -> bool:
392 """Returns True iff the global config has already been parsed"""
393 return CONFIG_PARSE_CALLED
397 """Print the current config to stdout."""
398 print("Global Configuration:", file=sys.stderr)
399 pprint.pprint(config, stream=sys.stderr)
404 """Log messages saved earlier now that logging has been initialized."""
405 logger = logging.getLogger(__name__)
406 logger.debug('Original commandline was: %s', ORIG_ARGV)
407 for _ in SAVED_MESSAGES: