uwtools.api.config

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, Path, str]] = None) → FieldTableConfig

Get a FieldTableConfig object.

Parameters

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

Returns

An initialized FieldTableConfig object

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

Get an INIConfig object.

Parameters

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

Returns

An initialized INIConfig object

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

Get an NMLConfig object.

Parameters

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

Returns

An initialized NMLConfig object

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

Get an SHConfig object.

Parameters

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

Returns

An initialized SHConfig object

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

Get a YAMLConfig object.

Parameters

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

Returns

An initialized YAMLConfig object

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

Realize an output config based on an input config and optional supplemental configs.

If no input is specified, stdin is read. A dict or Config object may also be provided as input. If no output is specified, stdout is written to. When an input or output filename is specified, its format will be deduced from its extension, if possible. This can be overridden by specifying the format explicitly, and it is required to do so for reads from stdin or writes to stdout, as no attempt is made to deduce the format of streamed data.

If optional supplemental configs (which may likewise be file paths or Config / dict objects) are provided, they will be merged, in the order specified, onto the input config. The format of all input configs must match.

If the input-config format is YAML, any supported output format may be specified. For all other input formats, the output format must match the input.

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.

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)

  • 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)

  • supplemental_configs – Configs to merge, in order, onto the input

  • values_needed – Report complete, missing, and template values

  • dry_run – Log output instead of writing to output

Returns

True

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

Realize an output config based on an input config and optional supplemental configs.

If no input is specified, stdin is read. A dict or Config object may also be provided as input. When an input filename is specified, its format will be deduced from its extension, if possible. This can be overridden by specifying the format explicitly, and it is required to do so for reads from stdin, as no attempt is made to deduce the format of streamed data.

If optional supplemental configs (which may likewise be file paths or Config / dict objects) are provided, they will be merged, in the order specified, onto the input config. The format of all input configs must match.

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.

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)

  • supplemental_configs – Configs to merge, in order, onto the input

  • values_needed – Report complete, missing, and template values

  • dry_run – Log output instead of writing to output

Returns

A dict representing the realized config

uwtools.api.config.validate(schema_file: Union[Path, str], config: Optional[Union[dict, YAMLConfig, Path, str]] = None) → 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

Returns

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