coma.hooks.config_hook

Config hook utilities, factories, and defaults.

single_load_and_write_factory(config_id: str, *, parser_attr_name: str | None = None, default_file_path: str | None = None, default_ext: Extension = Extension.YAML, raise_on_fnf: bool = False, write_on_fnf: bool = True, resolve: bool = False) → Callable[[...], Dict[str, Any]]

Factory for creating a config hook that initializes a config object.

The created config hook has the following behaviour:

First, an attempt is made to load the config object corresponding to config_id from file.

Note

If a file path is provided as a command line argument (assuming the presence of multi_config() or equivalent functionality), that path is used. Otherwise, default_file_path is used as a default. If default_file_path is None, a sensible default is derived from config_id instead.

In any case, if the provided or derived file path has no file extension, default_ext is used as a default extension.

If loading the file fails due to a FileNotFoundError, then:

If raise_on_fnf is True, the error is re-raised.

If raise_on_fnf is False, a config object with default values is initialized, and then:

If write_on_fnf is True, the newly-initialized config object with default values is written to the file.

If resolve is True, the underlying omegaconf handler attempts to resolve variable interpolation before writing.

The created config hook raises:

KeyError:

If config_id does not match any known config identifier

ValueError:

If the file extension is not supported. See Extension for supported types.

FileNotFoundError:

If raise_on_fnf is True and the config file was not found

Others:

As may be raised by the underlying omegaconf handler

Example

Fail fast when encountering a FileNotFoundError:

coma.initiate(..., config_hook=single_factory(..., raise_on_fnf=True))

Parameters:

• config_id (str) – A config identifier

• parser_attr_name (str) – The known_args attribute representing this config’s file path parser argument. If None, a sensible default is derived from default_dest().

• default_file_path (str) – An optional default value for the config file path. If None, a sensible default is derived from default_default().

• default_ext (coma.config.io.Extension) – The extension to use when the provided file path lacks one

• raise_on_fnf (bool) – If True, raises a FileNotFoundError if the config file was not found. If False, a config object with default values is initialized instead of failing outright.

• write_on_fnf (bool) – If the config file was not found and raise_on_fnf is False, then write_on_fnf indicates whether to write the config object to the provided file

• resolve (bool) – If about to write a config object to file, then resolve indicates whether the underlying omegaconf handler attempts to resolve variable interpolation beforehand

Returns:

A config hook

See also

• default_dest()

• default_default()

• single_config_factory()

multi_load_and_write_factory(*, default_ext: Extension = Extension.YAML, raise_on_fnf: bool = False, write_on_fnf: bool = True, resolve: bool = False) → Callable[[...], Dict[str, Any]]

Factory for creating a config hook that is a sequence of single factory calls.

Equivalent to calling single_load_and_write_factory() for each config with the other arguments passed along. See single_load_and_write_factory() for details.

Returns:

A config hook

default(known_args, configs: Dict[str, Any]) → Dict[str, Any]

Default config hook function.

An alias for calling multi_load_and_write_factory() with default arguments.