uwtools.api.config

API access to uwtools configuration management tools.

uwtools.api.config.compare(config_1_path, config_2_path, config_1_format=None, config_2_format=None)

Compare two config files.

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

Parameters:

  • config_1_path (Path | str) – Path to 1st config file.

  • config_2_path (Path | str) – Path to 2nd config file.

  • config_1_format (str | None) – Format of 1st config file (optional if file’s extension is recognized).

  • config_2_format (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.get_fieldtable_config(config=None, stdin_ok=False)

Get a FieldTableConfig object.

Parameters:

  • config (dict | str | Path | None) – FieldTable file (None => read stdin), or initial dict.

  • stdin_ok – 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 | str | Path | 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 | str | Path | 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 | str | Path | 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 | str | Path | 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, 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 is True, a report of values needed to realize the config is logged. In dry_run mode, output is written to stderr.

If total is True, an exception will be raised if any Jinja2 variables/expressions cannot be rendered. Otherwise, such variables/expressions will be passed through unchanged in the output.

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) – Format of the input config (optional if file’s extension is recognized).

  • update_config (Config | Path | dict | str | None) – Update config file (None => read stdin).

  • update_format (str | None) – Format of the update config (optional if file’s extension is recognized).

  • output_file (str | Path | None) – Output config file (None => write to stdout).

  • output_format (str | None) – Format of the output config (optional if file’s extension is recognized).

  • key_path (list[str | int] | None) – Path through keys to the desired output block.

  • 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 variable/expression 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:
Return type:

dict

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

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

If no config is specified, stdin is read and will be parsed as YAML and then validated. A dict or a YAMLConfig instance may also be provided for validation.

Parameters:

  • schema_file (Path | str) – The JSON Schema file to use for validation.

  • config (dict | str | YAMLConfig | Path | None) – The config to validate.

  • stdin_ok (bool) – OK to read from stdin?

Returns:

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

Return type:

bool