uwtools.api.template

API access to uwtools templating logic.

uwtools.api.template.render(values_src=None, values_format=None, input_file=None, output_file=None, overrides=None, env=False, searchpath=None, values_needed=False, dry_run=False, stdin_ok=False)

Render a Jinja2 template to a file, based on specified values.

Primary values used to render the template are taken from the specified file. The format of the values source will be deduced from the filename extension, if possible. This can be overridden via the values_format argument. A dict object may alternatively be provided as the primary values source. If no input file is specified, stdin is read. If no output file is specified, stdout is written to.

Parameters:

• values_src (dict | Path | str | None) – Source of values to render the template.

• values_format (str | None) – Format of values when sourced from file.

• input_file (str | Path | None) – Raw input template file (None => read stdin).

• output_file (str | Path | None) – Rendered template output file (None => write to stdout).

• overrides (dict[str, str] | None) – Supplemental override values.

• env (bool) – Supplement values with environment variables?

• searchpath (list[str] | None) – Paths to search for extra templates.

• values_needed (bool) – Just report variables needed to render the template?

• dry_run (bool) – Run in dry-run mode?

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

Returns:

The rendered template string.

Raises:

UWTemplateRenderError if template could not be rendered.

Return type:

str

uwtools.api.template.render_to_str(values_src=None, values_format=None, input_file=None, overrides=None, env=False, searchpath=None, values_needed=False, dry_run=False)

Render a Jinja2 template to a string, based on specified values.

See render() for details on arguments, etc.

Parameters:

• values_src (dict | Path | str | None)

• values_format (str | None)

• input_file (str | Path | None)

• overrides (dict[str, str] | None)

• env (bool)

• searchpath (list[str] | None)

• values_needed (bool)

• dry_run (bool)

Return type:

str

uwtools.api.template.translate(input_file=None, output_file=None, dry_run=False, stdin_ok=False)

Translate an atparse template to a Jinja2 template.

@[] tokens are replaced with Jinja2 {{}} equivalents. If no input file is specified, stdin is read. If no output file is specified, stdout is written to. In dry_run mode, output is written to stderr.

Parameters:

• input_file (str | Path | None) – Path to atparse file (None => read stdin).

• output_file (str | Path | None) – Path to the file to write the converted template to.

• dry_run (bool) – Run in dry-run mode?

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

Returns:

True.

Return type:

bool