<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# YAML Recipes

## Contents
- Create a config from scratch
- Read: multi-document files and defaults
- Modify: nested keys, lists, comment-preserving edits
- Validate against a schema
- Convert YAML ↔ JSON
- Gotchas (Norway problem, implicit typing, anchors)

## Create a config from scratch

```python
import yaml

config = {
    "server": {"host": "0.0.0.0", "port": 8080},
    "features": ["auth", "metrics"],
    "welcome": "Bienvenue à Montréal",
}
with open("config.yaml", "w") as f:
    yaml.safe_dump(config, f,
                   default_flow_style=False,  # block style, not {a: 1}
                   sort_keys=False,           # keep insertion order
                   allow_unicode=True)        # keep accented chars readable
```

Force quotes on an ambiguous scalar:

```python
yaml.safe_dump({"country": "NO", "version": "1.10"}, f,
               default_style=None)  # safe_dump already quotes these on output
# When hand-writing YAML text, quote them yourself: country: "NO"
```

## Read: multi-document files and defaults

```python
import yaml

# Single document
data = yaml.safe_load(open("config.yaml")) or {}   # empty file → None, so `or {}`

# Multi-document (--- separators), e.g. Kubernetes manifests
docs = list(yaml.safe_load_all(open("manifests.yaml")))

# Nested read with defaults
port = (data.get("server") or {}).get("port", 8080)
```

## Modify: nested keys, lists, comment-preserving edits

PyYAML (comments will be lost):

```python
data = yaml.safe_load(open("config.yaml"))
data.setdefault("server", {})["port"] = 9090
data.setdefault("features", []).append("tracing")
yaml.safe_dump(data, open("config.yaml", "w"),
               default_flow_style=False, sort_keys=False, allow_unicode=True)
```

ruamel.yaml (comments, quotes, key order all survive):

```python
from ruamel.yaml import YAML

y = YAML()                 # round-trip mode
y.indent(mapping=2, sequence=4, offset=2)   # match common k8s/compose style
doc = y.load(open("docker-compose.yml"))
doc["services"]["web"]["ports"] = ["8080:80"]
y.dump(doc, open("docker-compose.yml", "w"))
```

Multi-document write:

```python
yaml.safe_dump_all(docs, open("manifests.yaml", "w"),
                   default_flow_style=False, sort_keys=False)
```

## Validate against a schema

For structural guarantees use jsonschema (`pip install jsonschema`) on the loaded data — YAML loads to the same shapes JSON Schema describes:

```python
import yaml, jsonschema

schema = {
    "type": "object",
    "required": ["server"],
    "properties": {
        "server": {
            "type": "object",
            "required": ["port"],
            "properties": {"port": {"type": "integer",
                                    "minimum": 1, "maximum": 65535}},
        }
    },
}
data = yaml.safe_load(open("config.yaml"))
jsonschema.validate(data, schema)   # raises ValidationError with a JSON path
```

## Convert YAML ↔ JSON

```python
import json, yaml

# YAML → JSON
json.dump(yaml.safe_load(open("config.yaml")), open("config.json", "w"),
          indent=2, ensure_ascii=False)

# JSON → YAML
yaml.safe_dump(json.load(open("config.json")), open("config.yaml", "w"),
               default_flow_style=False, sort_keys=False, allow_unicode=True)
```

Caveat: JSON has no equivalent for YAML anchors, multi-doc streams, or non-string keys — conversion resolves/loses them.

## Gotchas (Norway problem, implicit typing, anchors)

- **The Norway problem.** In YAML 1.1 (what PyYAML implements), unquoted `no`, `yes`, `on`, `off`, `y`, `n` parse as booleans — `country: NO` becomes `country: False`. Quote them. Same family: `port: 022` is octal 18, `version: 1.10` is the float `1.1`.
- **Timestamps auto-convert.** `date: 2026-08-05` loads as `datetime.date`, not a string. Quote if you need the text.
- **`safe_load` of an empty file returns `None`**, not `{}` — guard with `or {}`.
- **Duplicate keys don't error** in PyYAML — the last one silently wins. ruamel.yaml raises; use it when duplicates would be a bug.
- **Anchors/aliases (`&base`, `*base`, `<<:` merge)** load fine but PyYAML re-dumps them expanded (aliases only re-emitted when the same object identity repeats). If the user's file relies on anchors for maintainability, edit with ruamel.yaml.
- **`sort_keys` defaults to True** in `safe_dump` — it silently alphabetizes configs; always pass `sort_keys=False` when round-tripping.
- **Long strings get folded** with line breaks on dump; pass `width=4096` to keep long values (URLs, tokens) on one line.
- **YAML 1.2 vs 1.1.** ruamel.yaml follows 1.2 (only `true`/`false` are booleans); PyYAML follows 1.1. The same file can load differently across the two libraries — pick one per task and stay with it.