uwtools.api.config

API access to uwtools configuration management tools.

uwtools.api.config.compare(config_1_path: Union[Path, str], config_2_path: Union[Path, str], config_1_format: Optional[str] = None, config_2_format: Optional[str] = None) → bool

Compare two config files.

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

Parameters

  • config_1_path – Path to 1st config file

  • config_2_path – Path to 2nd config file

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

  • config_2_format – Format of 2nd config file (optional if file’s extension is recognized)

Returns

False if config files had differences, otherwise True

uwtools.api.config.get_fieldtable_config(config: Optional[Union[dict, str, Path]] = None, stdin_ok=False) → FieldTableConfig

Get a FieldTableConfig object.

Parameters

  • config – FieldTable file to load (None or unspecified => read stdin), or initial dict

  • stdin_ok – OK to read from stdin?

Returns

An initialized FieldTableConfig object

uwtools.api.config.get_ini_config(config: Optional[Union[dict, str, Path]] = None, stdin_ok: bool = False) → INIConfig

Get an INIConfig object.

Parameters

  • config – INI file to load (None or unspecified => read stdin), or initial dict

  • stdin_ok – OK to read from stdin?

Returns

An initialized INIConfig object

uwtools.api.config.get_nml_config(config: Optional[Union[dict, str, Path]] = None, stdin_ok: bool = False) → NMLConfig

Get an NMLConfig object.

Parameters

  • config – Fortran namelist file to load (None or unspecified => read stdin), or initial dict

  • stdin_ok – OK to read from stdin?

Returns

An initialized NMLConfig object

uwtools.api.config.get_sh_config(config: Optional[Union[dict, str, Path]] = None, stdin_ok: bool = False) → SHConfig

Get an SHConfig object.

Parameters

  • config – File of shell ‘key=value’ pairs to load (None or unspecified => read stdin), or initial dict

  • stdin_ok – OK to read from stdin?

Returns

An initialized SHConfig object

uwtools.api.config.get_yaml_config(config: Optional[Union[dict, str, Path]] = None, stdin_ok: bool = False) → YAMLConfig

Get a YAMLConfig object.

Parameters

  • config – YAML file to load (None or unspecified => read stdin), or initial dict

  • stdin_ok – OK to read from stdin?

Returns

An initialized YAMLConfig object

uwtools.api.config.realize(input_config: Optional[Union[dict, Config, Path, str]] = None, input_format: Optional[str] = None, update_config: Optional[Union[dict, Config, Path, str]] = None, update_format: Optional[str] = None, output_file: Optional[Union[str, Path]] = None, output_format: Optional[str] = None, key_path: Optional[List[Union[str, int]]] = None, values_needed: bool = False, total: bool = False, dry_run: bool = False, stdin_ok: bool = False) → None

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 – Input config file (None or unspecified => read stdin)

  • input_format – Format of the input config (optional if file’s extension is recognized)

  • update_config – Update config file (None or unspecified => read stdin)

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

  • output_file – Output config file (None or unspecified => write to stdout)

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

  • key_path – Path through keys to the desired output block

  • values_needed – Report complete, missing, and template values

  • total – Require rendering of all Jinja2 variables/expressions

  • dry_run – Log output instead of writing to output

  • stdin_ok – OK to read from stdin?

Raises

UWConfigRealizeError if total is True and any Jinja2 variable/expression was not rendered

uwtools.api.config.realize_to_dict(input_config: Optional[Union[dict, Config, Path, str]] = None, input_format: Optional[str] = None, update_config: Optional[Union[dict, Config, Path, str]] = None, update_format: Optional[str] = None, values_needed: bool = False, dry_run: bool = False, stdin_ok: bool = False) → dict

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

See realize() for details on arguments, etc.

uwtools.api.config.validate(schema_file: Union[Path, str], config: Optional[Union[dict, YAMLConfig, Path, str]] = None, stdin_ok: bool = False) → bool

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 – The JSON Schema file to use for validation

  • config – The config to validate

  • stdin_ok – OK to read from stdin?

Returns

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