uwtools.api.template

API access to uwtools templating logic.

uwtools.api.template.render(values_src: Optional[Union[dict, Path, str]] = None, values_format: Optional[str] = None, input_file: Optional[Union[str, Path]] = None, output_file: Optional[Union[str, Path]] = None, overrides: Optional[Dict[str, str]] = None, env: bool = False, searchpath: Optional[List[str]] = None, values_needed: bool = False, dry_run: bool = False, stdin_ok: bool = False) → str

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 – Source of values to render the template

  • values_format – Format of values when sourced from file

  • input_file – Path to read raw Jinja2 template from (None or unspecified => read stdin)

  • output_file – Path to write rendered Jinja2 template to (None or unspecified => write to stdout)

  • overrides – Supplemental override values

  • env – Supplement values with environment variables?

  • searchpath – Paths to search for extra templates

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

  • dry_run – Run in dry-run mode?

  • stdin_ok – OK to read from stdin?

Returns

The rendered template string

Raises

UWTemplateRenderError if template could not be rendered

uwtools.api.template.render_to_str(values_src: Optional[Union[dict, Path, str]] = None, values_format: Optional[str] = None, input_file: Optional[Union[str, Path]] = None, overrides: Optional[Dict[str, str]] = None, env: bool = False, searchpath: Optional[List[str]] = None, values_needed: bool = False, dry_run: bool = False) → str

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

See render() for details on arguments, etc.

uwtools.api.template.translate(input_file: Optional[Union[str, Path]] = None, output_file: Optional[Union[str, Path]] = None, dry_run: bool = False, stdin_ok: bool = False) → bool

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 – Path to the template containing atparse syntax (None or unspecified => read stdin)

  • output_file – Path to the file to write the converted template to

  • dry_run – Run in dry-run mode?

  • stdin_ok – OK to read from stdin?

Returns

True