coma.config.cli
Utilities for overriding config attributes with command line arguments.
- override(config_id: str, configs: Dict[str, Any], unknown_args: List[str], *, sep: str = ':', exclusive: bool = False, raise_on_no_matches: bool = True, raise_on_many_matches: bool = True, raise_on_many_seps: bool = True, raise_on_empty_split: bool = True) Any [source]
Overrides a config’s attribute values with command line arguments.
Similar to from_dotlist() followed by merge(), but with additional features.
Specifically, since
coma
commands accept an arbitrary number of configs, config attributes’ names may end up clashing when using pureomegaconf
dot-list notation. To resolve these clashes, a prefix notation is introduced.Prefix Notation
For a config with identifier
config_id
, anyomegaconf
dot-list notation can be prefixed withconfig_id
followed bysep
to uniquely link the override to the corresponding config.In addition, an attempt is made to match all non-prefixed arguments in dot-list notation to the config corresponding to
config_id
. These shared config overrides are not consumed, and so can be used to override multiple configs without duplication. However, this powerful feature can also be error prone. To disable it, setexclusive
toTrue
. This raises aValueError
if shared overrides match more than one config.Note
If the config is not structured,
omegaconf
will happily add any attributes to it. To prevent this, ensure that the config is structured (using structured() or set_struct()).Finally, prefixes can be abbreviated as long as the abbreviation is unambiguous (i.e., matches a unique config identifier).
Examples
Resolving clashing dot-list notations with (abbreviated) prefixes:
@dataclass class Person: name: str @dataclass class School: name: str class AddStudent: def __init__(self, person, school): ... def run(self): ... ... coma.register("add_student", AddStudent, Person, School)
Invoking on the command line:
$ python main.py add_student p:name="..." s:name="..."
- Parameters
config_id (str) – A config identifier for the config to target
configs (Dict[str, Any]) – A dictionary of (id-config) pairs
unknown_args (List[str]) – Remainder (second return value) of parse_known_args()
sep (str) – The prefix separation token to use
exclusive (bool) – Whether shared overrides should match at most one config
raise_on_no_matches (bool) – Whether to raise or suppress a
ValueError
if a prefix does not match any known config identifierraise_on_many_matches (bool) – Whether to raise or suppress a
ValueError
if a prefix ambiguous (i.e., matches more than one config identifier)raise_on_many_seps (bool) – Whether to raise or suppress a
ValueError
if more than onesep
token is found within a single override argumentraise_on_empty_split (bool) – Whether to raise or suppress a
ValueError
if no split is achieved. This can only happen ifsep
isNone
and one of the arguments consists entirely of whitespace.
- Returns
A new config object that uses command line arguments to overrides the attributes of the config object originally corresponding to
config_id
- Raises
KeyError – If
config_id
does not match any known config identifierValueError – Various. See the
raise_on_*
above.Others – As may be raised by the underlying
omegaconf
handler