YTE: YAML Template Engine with Python Expressions

Common errors

• NameError: name 'my_variable' is not defined

  cause A Python expression within the YAML template (e.g., `? my_variable + 1`) is trying to use a variable that was not provided in the `context` dictionary when `process_yaml` was called.
  fix Pass `my_variable` and its value in the `context` dictionary to the `process_yaml` function. For example: `process_yaml(template, context={'my_variable': 10})`.

• SyntaxError: invalid syntax

  cause The Python expression following a `?` in the YAML template contains invalid Python syntax, or a Python-specific construct (like `for` or `if`) is malformed.
  fix Carefully review the Python expression within the YAML template. Ensure correct indentation for blocks, proper closing of parentheses/brackets, and adherence to Python syntax rules. Use a Python linter or IDE to validate the expression in isolation if needed.

• TypeError: unsupported operand type(s) for +: 'int' and 'str'

  cause A Python expression is attempting an operation (e.g., addition) between incompatible data types (e.g., an integer and a string), which is common when template variables have unexpected types.
  fix Explicitly cast variables to the correct type within the YTE expression (e.g., `? int(item_count) + 1`) or ensure the `context` dictionary provides variables with the expected types.

Warnings

• gotcha YTE uses '?' as the prefix for Python expressions within YAML. This is a non-standard YAML syntax extension and might conflict with YAML linters or other parsers not aware of YTE.
  Fix: Be aware of the '?' prefix for expressions and ensure your tooling is compatible or configure it to ignore these YTE-specific constructs. YTE templates are still valid YAML, where '?' expressions are treated as strings by standard parsers.
• breaking There have been reported compatibility issues with Python 3.12 regarding the availability of for-loop variables for substitution within YTE templates. This may lead to unexpected behavior or failures.
  Fix: If encountering issues on Python 3.12, check the YTE GitHub issues for a resolution or consider using Python 3.11 or earlier until a fix is released. Review template logic, especially variable scoping within loops.
• gotcha YTE expressions are raw Python code. Any variable referenced within an expression (e.g., `? age > 18`) must be explicitly passed in the `context` dictionary to `process_yaml` or be a built-in Python function/value. Undefined variables will raise a `NameError`.
  Fix: Ensure all variables used in YTE expressions are present in the `context` dictionary passed to `process_yaml`. Thoroughly test templates for missing variable definitions.

Install

• pip install yte Install YTE

Imports

• process_yaml
  wrong:

  import yte.process_yaml

  correct:

  from yte import process_yaml

  The primary function to process YAML templates is directly available under the 'yte' package, not a submodule 'yte.process_yaml'.

Quickstart

This quickstart demonstrates how to use `process_yaml` to render a YAML template containing embedded Python expressions. Expressions are prefixed with `?` and are evaluated in the provided context.

from yte import process_yaml
import os

# Example YAML content with YTE expressions
yaml_template = """
name: John Doe
age: ? 30 + 5  # Simple Python expression
is_adult: ? age > 18
items:
  ? for i in range(2):
    - id: ? i + 1
      value: Item ? i + 1
"""

# Context (variables) for the template. In a real scenario, this might come from
# a file, environment variables, or a Python dictionary.
context = {
    "username": os.environ.get('YTE_USERNAME', 'guest')
}

processed_yaml = process_yaml(yaml_template, context=context)
print(processed_yaml)