Ouroboros Jinja

Expand Jinja2 templates that back-reference other values in the same document — the snake eats its own tail.

# defaults.yaml
slug: ~
domain: "{{ slug }}.nimbus.fi"
volume-name: "{{ slug }}-volume"
permanent-ip-name: "{{ domain }}"

# server.toml
name = "Prominence 2: Hasturian Era"
slug = "hasturian"

import ouroboros_jinja

config = ouroboros_jinja.load("defaults.yaml", "server.toml")
# {
#   "slug": "hasturian",
#   "domain": "hasturian.nimbus.fi",
#   "volume-name": "hasturian-volume",
#   "permanent-ip-name": "hasturian.nimbus.fi",
#   "name": "Prominence 2: Hasturian Era"
# }

API

• expand(*mappings) — deep-merge mappings (later ones win) and expand every string value as a Jinja2 template.
• loads(*yaml_texts) — parse YAML texts, merge and expand.
• load(*paths) — read files (.toml via tomllib, everything else as YAML), merge and expand.

Templates may reference any top-level key, including nested content ({{ an_object.description }}) and lists ({% for port in ports %}). Values are expanded lazily and recursively, in dependency order.

Merging

When several documents are given, nested mappings are merged key by key, so a later document can override one leaf without restating its siblings:

# assets.yaml
assets:
    tractor:
        name: "Aurora"
    trailer:
        name: "Beatrice"
stack:
    engine: "{{ assets.tractor.name }}"
    payload: "{{ assets.trailer.name }}"

# addon.yaml
assets:
    tractor:
        name: "Charlie"

load("assets.yaml", "addon.yaml") keeps assets.trailer and only replaces assets.tractor.name, so stack.engine expands to "Charlie" and stack.payload to "Beatrice".

Anything that is not a mapping on both sides is replaced outright — a list in a later document wins over an earlier list, it is not concatenated. The input mappings are never mutated.

Semantics

• Reference cycles raise CircularReferenceError with the chain spelled out: Circular reference detected: item_1 -> item_2 -> item_3 -> item_1.
• Unknown variables raise ExpansionError (Jinja2 StrictUndefined).
• A top-level key with a null value (slug: ~) is a required override: referencing it before it has been overridden raises ExpansionError instead of silently interpolating "None".
• Only strings containing {{ or {% are touched; other values (ints, lists, …) pass through unchanged.

Testing

uv run pytest