`uwtools.api.config`

API access to uwtools configuration management tools.

class uwtools.api.config.Config(config=None)

Bases: ABC, UserDict

A base class specifying (and partially implementing) methods to read, manipulate, and write several configuration-file formats.

Parameters:: config (dict | str | Config | Path | None) – Config file to load (None => read from stdin), or initial dict.

abstract as_dict()

Returns a pure dict version of the config.

Return type:: dict

compare_config(dict1, dict2=None, header=True)

Compare two config dictionaries.

Assumes a section/key/value structure.

Parameters:

dict1 (dict) – The first dictionary.
dict2 (dict | None) – The second dictionary (default: this config).
header (bool | None)

Returns:

True if the configs are identical, False otherwise.

Return type:

bool

property config_file: Path | None: Return the path to the config file from which this object was instantiated, if applicable.

dereference(context=None)

Render as much Jinja2 syntax as possible.

Parameters:: context (dict | None)
Return type:: Config

abstract dump(path)

Dump the config to stdout or a file.

Parameters:: path (Path | None) – Path to dump config to (default: stdout).
Return type:: None

abstract static dump_dict(cfg, path=None)

Dump a provided config dictionary to stdout or a file.

Parameters:

cfg (dict) – The in-memory config object to dump.
path (Path | None) – Path to dump config to (default: stdout).

Return type:

None

incomplete(data=<object object>, keypath=None, keys=None, vals=None)

Return lists of keys leading to keys and values with unrendered content.

Parameters:

data (Any) – The data object to inspect for unrendered keys/values.
keypath (list | None) – A list of keys/indexes leading to the current data object.
keys (list | None) – A list of keypaths leading to keys with unrendered content.
vals (list | None) – A list of keypaths leading to values with unrendered content.

Return type:

tuple[list[list], list[list]]

update_from(src)

Update a config.

Parameters:: src (dict | UserDict) – The dictionary with new data to use.
Return type:: None

class uwtools.api.config.FieldTableConfig(config=None)

Bases: YAMLConfig

Work with configs in field_table format.

Parameters:: config (dict | str | Config | Path | None) – Config file to load (None => read from stdin), or initial dict.

as_dict()

Returns a pure dict version of the config.

Return type:: dict

dump(path=None)

Dump the config in Field Table format.

Parameters:: path (Path | None) – Path to dump config to (default: stdout).
Return type:: None

classmethod dump_dict(cfg, path=None)

Dump a provided config dictionary in Field Table format.

FMS field and tracer managers must be registered in an ASCII table called field_table. This table lists field type, target model and methods the querying model will ask for. See UFS documentation for more information:

https://ufs-weather-model.readthedocs.io/en/ufs-v1.0.0/InputsOutputs.html#field-table-file

The example format for generating a field file is:

sphum:
  longname: specific humidity
  units: kg/kg
  profile_type:
    name: fixed
    surface_value: 1.e30

Parameters:

cfg (dict) – The in-memory config object to dump.
path (Path | None) – Path to dump config to (default: stdout).

Return type:

None

class uwtools.api.config.INIConfig(config=None)

Bases: Config

Work with INI configs.

Parameters:: config (dict | Path | None) – Config file to load (None => read from stdin), or initial dict.

as_dict()

Returns a pure dict version of the config.

Return type:: dict

dump(path=None)

Dump the config in INI format.

Parameters:: path (Path | None) – Path to dump config to (default: stdout).
Return type:: None

classmethod dump_dict(cfg, path=None)

Dump a provided config dictionary in INI format.

Parameters:

cfg (dict) – The in-memory config object to dump.
path (Path | None) – Path to dump config to (default: stdout).

Return type:

None

class uwtools.api.config.NMLConfig(config=None)

Bases: Config

Work with Fortran namelist configs.

Construct an NMLConfig object.

Parameters:: config (dict | Path | None) – Config file to load (None => read from stdin), or initial dict.

as_dict()

Returns a pure dict version of the config.

Return type:: dict

dump(path)

Dump the config in Fortran namelist format.

Parameters:: path (Path | None) – Path to dump config to (default: stdout).
Return type:: None

classmethod dump_dict(cfg, path=None)

Dump a provided config dictionary in Fortran namelist format.

Parameters:

cfg (dict | Namelist) – The in-memory config object to dump.
path (Path | None) – Path to dump config to (default: stdout).

Return type:

None

class uwtools.api.config.SHConfig(config=None)

Bases: Config

Work with key=value shell configs.

Parameters:: config (dict | Path | None) – Config file to load (None => read from stdin), or initial dict.

as_dict()

Returns a pure dict version of the config.

Return type:: dict

dump(path)

Dump the config as key=value lines.

Parameters:: path (Path | None) – Path to dump config to (default: stdout).
Return type:: None

classmethod dump_dict(cfg, path=None)

Dump a provided config dictionary in bash format.

Parameters:

cfg (dict) – The in-memory config object to dump.
path (Path | None) – Path to dump config to (default: stdout).

Return type:

None

class uwtools.api.config.YAMLConfig(config=None)

Bases: Config

Work with YAML configs.

Parameters:: config (dict | str | Config | Path | None) – Config file to load (None => read from stdin), or initial dict.

as_dict()

Returns a pure dict version of the config.

Return type:: dict

dump(path=None)

Dump the config in YAML format.

Parameters:: path (Path | None) – Path to dump config to (default: stdout).
Return type:: None

classmethod dump_dict(cfg, path=None)

Dump a provided config dictionary in YAML format.

Parameters:

cfg (dict) – The in-memory config object to dump.
path (Path | None) – Path to dump config to (default: stdout).

Return type:

None

uwtools.api.config.compare(path1, path2, format1=None, format2=None)

Compare two config files.

Recognized file extensions are: ini, nml, sh, yaml

Parameters:

path1 (Path | str) – Path to 1st config file.
path2 (Path | str) – Path to 2nd config file.
format1 (str | None) – Format of 1st config file (optional if file’s extension is recognized).
format2 (str | None) – Format of 2nd config file (optional if file’s extension is recognized).

Returns:

False if config files had differences, otherwise True.

Return type:

bool

uwtools.api.config.compose(configs, realize=False, output_file=None, input_format=None, output_format=None, cycle=None, leadtime=None)

Compose config files.

Specify explicit input or output formats to override default treatment based on file extension. Recognized file extensions are: ini, nml, sh, yaml.

Parameters:

configs (list[str | Path]) – Paths to configs to compose.
realize (bool) – Render template expressions where possible.
output_file (Path | str | None) – Output config destination (default: write to stdout).
input_format (str | None) – Format of configs to compose (choices: ini, nml, sh, yaml, default: yaml)
output_format (str | None) – Format of output config (choices: ini, nml, sh, yaml, default: yaml)
cycle (datetime | None) – A datetime object to make available for use in configs.
leadtime (timedelta | None) – A timedelta object to make available for use in configs.

Returns:

The composed config.

Return type:

Config

uwtools.api.config.get_fieldtable_config(config=None, stdin_ok=False)

Get a FieldTableConfig object.

Parameters:

config (dict | Path | str | None) – FieldTable file (None => read stdin), or initial dict.
stdin_ok (bool) – OK to read from stdin?

Returns:

An initialized FieldTableConfig object.

Return type:

FieldTableConfig

uwtools.api.config.get_ini_config(config=None, stdin_ok=False)

Get an INIConfig object.

Parameters:

config (dict | Path | str | None) – INI file or dict (None => read stdin).
stdin_ok (bool) – OK to read from stdin?

Returns:

An initialized INIConfig object.

Return type:

INIConfig

uwtools.api.config.get_nml_config(config=None, stdin_ok=False)

Get an NMLConfig object.

Parameters:

config (dict | Path | str | None) – Namelist file of dict (None => read stdin).
stdin_ok (bool) – OK to read from stdin?

Returns:

An initialized NMLConfig object.

Return type:

NMLConfig

uwtools.api.config.get_sh_config(config=None, stdin_ok=False)

Get an SHConfig object.

Parameters:

config (dict | Path | str | None) – Shell key=value pairs file or dict (None => read stdin).
stdin_ok (bool) – OK to read from stdin?

Returns:

An initialized SHConfig object.

Return type:

SHConfig

uwtools.api.config.get_yaml_config(config=None, stdin_ok=False)

Get a YAMLConfig object.

Parameters:

config (dict | Path | str | None) – YAML file or dict (None => read stdin).
stdin_ok (bool) – OK to read from stdin?

Returns:

An initialized YAMLConfig object.

Return type:

YAMLConfig

uwtools.api.config.realize(input_config=None, input_format=None, update_config=None, update_format=None, output_file=None, output_format=None, key_path=None, cycle=None, leadtime=None, values_needed=False, total=False, dry_run=False, stdin_ok=False)

Realize a config based on a base input config and an optional update config.

The input config may be specified as a filesystem path, a dict, or a Config object. When it is not, it will be read from stdin.

If an update config is specified, it is merged onto the input config, augmenting or overriding base values. It may be specified as a filesystem path, a dict, or a Config object. When it is not, it will be read from stdin.

At most one of the input config or the update config may be left unspecified, in which case the other will be read from stdin. If neither filename or format is specified for the update config, no update will be performed.

The output destination may be specified as a filesystem path. When it is not, it will be written to stdout.

If values_needed=True, a report of keys and values with incomplete Jinja2 expressions, indicating values needed to fully realize the config, is logged. Additionally, the return will be a dict object whose keys item provides a list of keypaths leading to incomplete keys and whose vals item provides a list of keypaths leading to incomplete values. If total=False (see below), the function will return after logging the values-needed report.

If total=True, an exception will be raised if any Jinja2 content cannot be rendered. Otherwise, such content will be passed through unchanged in the output, unless values_needed=True, in which case the function will return.

In dry_run mode, output is written to stderr.

Recognized file extensions are: ini, nml, sh, yaml

Parameters:

input_config (Config | Path | dict | str | None) – Input config file (None => read stdin).
input_format (str | None) – Input config format (default: deduced from filename extension; yaml if that fails).
update_config (Config | Path | dict | str | None) – Update config file (None => read stdin).
update_format (str | None) – Update config format (default: deduced from filename extension; yaml if that fails).
output_file (Path | str | None) – Output config file (None => write to stdout).
output_format (str | None) – Output config format (default: deduced from filename extension; yaml if that fails).
key_path (list[YAMLKey] | None) – Path of keys to the desired output block.
cycle (datetime | None) – A datetime object to make available for use in configs.
leadtime (timedelta | None) – A timedelta object to make available for use in configs.
values_needed (bool) – Report complete, missing, and template values.
total (bool) – Require rendering of all Jinja2 variables/expressions.
dry_run (bool) – Log output instead of writing to output.
stdin_ok (bool) – OK to read from stdin?

Returns:

The dict representation of the realized config.

Raises:

UWConfigRealizeError if total is True and any Jinja2 syntax was not rendered.

Return type:

dict

uwtools.api.config.realize_to_dict(input_config=None, input_format=None, update_config=None, update_format=None, key_path=None, values_needed=False, total=False, dry_run=False, stdin_ok=False)

Realize a config to a dict, based on a base input config and an optional update config.

See realize() for details on arguments, etc.

Parameters:

input_config (Config | dict | Path | str | None)
input_format (str | None)
update_config (Config | dict | Path | str | None)
update_format (str | None)
key_path (list[YAMLKey] | None)
values_needed (bool)
total (bool)
dry_run (bool)
stdin_ok (bool)

Return type:

dict

uwtools.api.config.validate(schema_file, config_data=None, config_path=None, stdin_ok=False)

Check whether the specified config conforms to the specified JSON Schema spec.

Specify at most one of config_data or config_path. If no config is specified, stdin is read and will be parsed as YAML and then validated.

Parameters:

schema_file (Path | str) – The JSON Schema file to use for validation.
config_data (bool | dict | float | int | list | str | YAMLConfig | None) – A config to validate.
config_path (Path | str | None) – A path to a file containing a config to validate.
stdin_ok (bool) – OK to read from stdin?

Raises:

TypeError if both config_* arguments specified.

Returns:

True if the YAML file conforms to the schema, False otherwise.

Return type:

bool

uwtools.api.config

`uwtools.api.config`