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 pure omegaconf dot-list notation. To resolve these clashes, a prefix notation is introduced.

Prefix Notation

For a config with identifier config_id, any omegaconf dot-list notation can be prefixed with config_id followed by sep 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, set exclusive to True. This raises a ValueError 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:

main.py
@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 (assuming sep is ‘::’):

$ 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 identifier

  • raise_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 one sep token is found within a single override argument

  • raise_on_empty_split (bool) – Whether to raise or suppress a ValueError if no split is achieved. This can only happen if sep is None 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 identifier

  • ValueError – Various. See the raise_on_* above.

  • Others – As may be raised by the underlying omegaconf handler

override_factory(*, 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) → Callable[source]

Factory for creating slight variations of override().