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']:
72 from typing import Any, Dict, List, Optional
74 # This module is commonly used by others in here and should avoid
75 # taking any unnecessary dependencies back on them.
77 # Note: at this point in time, logging hasn't been configured and
78 # anything we log will come out the root logger.
81 class LoadFromFile(argparse.Action):
82 """Helper to load a config file into argparse."""
83 def __call__ (self, parser, namespace, values, option_string = None):
87 for line in buf.split(','):
89 line = line.strip('{')
90 line = line.strip('}')
91 m = re.match(r"^'([a-zA-Z_\-]+)'\s*:\s*(.*)$", line)
95 value = value.strip("'")
96 if value not in ('None', 'True', 'False'):
97 argv.append(f'--{key}')
99 parser.parse_args(argv, namespace)
102 # A global parser that we will collect arguments into.
103 prog = os.path.basename(sys.argv[0])
104 args = argparse.ArgumentParser(
106 formatter_class=argparse.ArgumentDefaultsHelpFormatter,
107 fromfile_prefix_chars="@",
108 epilog=f'-----------------------------------------------------------------------------\n{prog} uses config.py ({__file__}) for global, cross-module configuration setup and parsing.\n-----------------------------------------------------------------------------'
110 config_parse_called = False
112 # A global configuration dictionary that will contain parsed arguments
113 # It is also this variable that modules use to access parsed arguments
114 config: Dict[str, Any] = {}
116 # Defer logging messages until later when logging has been initialized.
117 saved_messages: List[str] = []
120 def add_commandline_args(title: str, description: str = ""):
121 """Create a new context for arguments and return a handle."""
122 return args.add_argument_group(title, description)
125 group = add_commandline_args(
126 f'Global Config ({__file__})',
127 'Args that control the global config itself; how meta!',
135 help='Config file from which to read args in lieu or in addition to commandline.',
141 help='Display the global configuration on STDERR at program startup.',
148 help='Populate config file compatible --config_loadfile to save config for later use.',
152 def is_flag_already_in_argv(var: str):
153 """Is a particular flag passed on the commandline?"""
160 def parse(entry_module: Optional[str]) -> Dict[str, Any]:
161 """Main program should call this early in main()"""
162 global config_parse_called
163 if config_parse_called:
165 config_parse_called = True
166 global saved_messages
168 # If we're about to do the usage message dump, put the main module's
169 # argument group first in the list (if possible), please.
170 reordered_action_groups = []
174 if arg == '--help' or arg == '-h':
175 for group in args._action_groups:
176 if entry_module is not None and entry_module in group.title:
177 reordered_action_groups.insert(0, group) # prepend
178 elif prog in group.title:
179 reordered_action_groups.insert(0, group) # prepend
181 reordered_action_groups.append(group) # append
182 args._action_groups = reordered_action_groups
184 # Examine the environment variables to settings that match
185 # known flags. For a flag called --example_flag the corresponding
186 # environment variable would be called EXAMPLE_FLAG.
187 usage_message = args.format_usage()
190 for x in usage_message.split():
204 # Environment vars the same as flag names without
205 # the initial -'s and in UPPERCASE.
206 env = var.strip('-').upper()
207 if env in os.environ:
208 if not is_flag_already_in_argv(var):
209 value = os.environ[env]
210 saved_messages.append(
211 f'Initialized from environment: {var} = {value}'
213 from string_utils import to_bool
214 if len(chunks) == 1 and to_bool(value):
216 elif len(chunks) > 1:
218 sys.argv.append(value)
224 # Parse (possibly augmented) commandline args with argparse normally.
225 known, unknown = args.parse_known_args()
226 config.update(vars(known))
228 # Reconstruct the argv with unrecognized flags for the benefit of
229 # future argument parsers. For example, unittest_main in python
230 # has some of its own flags. If we didn't recognize it, maybe
232 sys.argv = sys.argv[:1] + unknown
234 if config['config_savefile']:
235 with open(config['config_savefile'], 'w') as wf:
236 wf.write("\n".join(sys.argv[1:]))
238 if config['config_dump']:
243 def has_been_parsed() -> bool:
244 """Has the global config been parsed yet?"""
245 global config_parse_called
246 return config_parse_called
250 """Print the current config to stdout."""
251 print("Global Configuration:", file=sys.stderr)
252 pprint.pprint(config, stream=sys.stderr)
256 """Log messages saved earlier now that logging has been initialized."""
257 logger = logging.getLogger(__name__)
258 global saved_messages
259 for _ in saved_messages: