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) — shallow-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.

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