coma.config.io

Utilities for serializing configs to file.

class Extension(value)

Supported config serialization file extensions:

Value	Meaning
YAML	".yaml"
YML	".yml"
JSON	".json"

maybe_add_ext(file_path: str, ext: Extension) → str

If file_path lacks a file extension, appends ext.

Parameters:

• file_path (str) – Any file path.

• ext (Extension) – An extension to possibly append.

Returns:

A file path with an extension if one was lacking.

Return type:

str

is_json_ext(file_path: str) → bool

Returns whether file_path has a JSON-like file extension.

Parameters:

file_path (str) – Any file path.

Returns:

Whether file_path has a JSON-like file extension.

Return type:

bool

is_yaml_ext(file_path: str, *, strict: bool = False) → bool

Returns whether file_path has a YAML-like file extension.

Parameters:

• file_path (str) – Any file path.

• strict (bool) – Whether to match Extension.YAML exactly or also allow matching against other valid YAML-like file extensions.

Returns:

Whether file_path has a YAML-like file extension.

Return type:

bool

is_yml_ext(file_path: str, *, strict: bool = False) → bool

Returns whether file_path has a YAML-like file extension.

Parameters:

• file_path (str) – Any file path.

• strict (bool) – Whether to match Extension.YML exactly or also allow matching against other valid YAML-like file extensions.

Returns:

Whether file_path has a YAML-like file extension.

Return type:

bool

is_ext(file_path: str, which: Extension, *alts: Extension, strict: bool = False) → bool

Returns whether file_path has a file extension from a specific set.

Parameters:

• file_path (str) – Any file path.

• which (Extension) – The primary file extension to test against.

• *alts (Extension) – A set of alternative file extensions to test against.

• strict (bool) – Whether to match which exactly or also allow matching against any extensions in alts.

Returns:

Whether file_path has a file extension from a specific set.

Return type:

bool

initialize(config: Config, file_path: str | None = None, base_instance_key: str = 'BASE', file_instance_key: str = 'FILE') → None

Initializes a config object and possibly updates its attributes from file.

Initializes a base config object from config using omegaconf. If file_path is not None, attempts to also load a config object from file. If that succeeds, then attempts to update the base config object’s attributes with attributes of the config object loaded from file.

If either step has an already cached instance (based on the given instance keys), the cached value is used instead.

Parameters:

• config (Config) – The config to initialize.

• file_path (str, optional) – If not None, file path from which the base instance’s attributes can be updated.

• base_instance_key (InstanceKey) – The instance key of the base config instance.

• file_instance_key (InstanceKey) – The instance key of the config instance updated from file data.

Returns:

The config object is updated in-place.

Return type:

None

Raises:

• ValueError – If file_path has an unsupported file extension.

• IOError – If there are issues relating to reading from file_path.

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

write(config: Config, file_path: str, *, key: str | None = None, resolve: bool = False) → None

Serializes a config to file.

Parameters:

• config (Config) – The config to serialize.

• file_path (str) – A file path for serializing config.

• key (InstanceKey, optional) – The specific config instance to serialize. If None, the latest instance is used.

• resolve (bool) – Whether the underlying omegaconf handler should resolve variable interpolation before serializing.

Raises:

• ValueError – If file_path has an unsupported file extension.

• IOError – If there are issues relating to writing to file_path.

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

class PersistenceManager(default_extension: Extension = Extension.YAML)

register(config_id: str, extension: Extension | None = None, *names_or_flags: str, **kwargs: Any) → PersistenceManager

Registers parameters defining a file path argument for config_id that can later be added to an argparse.ArgumentParser via add_path_argument().

Parameters:

• config_id (ConfigID) – The config identifier for which to register file path argument parameters.

• extension (Extension, optional) – The extension to use if the provided file path lacks one. If None, defaults to default_extension.

• *names_or_flags (str) – Passed to add_argument(). A sensible default is used if empty.

• **kwargs (Any) – Passed to add_argument(). A sensible default is used for many parameters if missing. For details, see add_path_argument()

Note

Registering a particular config_id does not guarantee/force that the config will be serialized, but rather only explicitly determines the parameters that get passed to add_argument() (instead of relying on the sensible defaults that are otherwise provided).

Returns:

This persistence manager (to enable fluent interfacing).

Return type:

PersistenceManager

See also

• get_file_path()

add_path_argument(parser: ArgumentParser, config_id: str) → None

Adds a file path argument for config_id to parser.

Specifically, calls add_argument() on parser with the parameters register() ed for config_id. If config_id is unregistered, or if any of the following parameters are missing from the registration, sensible defaults are used instead when calling add_argument():

names_or_flags: based on 'config_id'
type: str
metavar: "FILE"
dest: 'config_id'
default: based on 'config_id' + 'extension'
help: based on 'config_id'

Additional parameters beyond these can also be registered.

Note

These parameters enable the later retrieval of any user-specified file path using get_file_path() or a default file path if the user fails to explicitly give a one.

Parameters:

• parser (argparse.ArgumentParser) – The parser for which to add a file path arguments for the given config_id.

• config_id (ConfigID) – The config identifier for which to add file path arguments to parser.

See also

• register()

• get_file_path()

get_file_path(config_id: str, known_args: Any) → str

Retrieves the file path for config_id from known_args.

Assumes that known_args is the namespace return object (the first return value) of parse_known_args() from the parser on which a file path for config_id was added using add_path_argument(). However, a sensible default is returned even if no such prior call occurred.

Parameters:

• config_id (ConfigID) – The config identifier for which to retrieve a file path from known_args.

• known_args (Any) – Typically, the namespace return object (the first return value) of parse_known_args().

Returns:

The retrieved file path for config_id.

Return type:

str

See also

• register()