yarutsk 0.5.0

A YAML round-trip library that preserves comments and insertion order

yarutsk

⚠ AI-authored. This library — design, implementation, tests, and documentation — was written by Claude Code (Anthropic) under human direction.

A Python YAML library that round-trips documents while preserving comments, insertion order, scalar styles, tags, anchors and aliases, blank lines, and explicit document markers.

Full documentation: https://theyugin.github.io/yarutsk/

Quick start

pip install yarutsk

import io
import yarutsk

doc = yarutsk.load(io.StringIO("""
# database config
host: localhost  # primary
port: 5432
"""))

doc["port"] = 5433

out = io.StringIO()
yarutsk.dump(doc, out)
print(out.getvalue())
# # database config
# host: localhost  # primary
# port: 5433

YamlMapping subclasses dict and YamlSequence subclasses list, so they work everywhere a dict or list is expected — isinstance(doc, dict), json.dumps(doc), and any library accepting plain mappings or sequences.

Python 3.12+ required. Pre-built wheels for Linux / macOS / Windows on x86_64 and aarch64.

What's preserved

• Scalar styles — plain, 'single', "double", literal |, folded >
• Non-canonical scalars — yes/no/on/off, ~, 0xFF, 0o77 reproduced as written
• YAML tags — !!str, !!binary, !!timestamp, and any custom tag
• Anchors and aliases — &name / *name round-trip intact
• Blank lines between entries and explicit document markers (---, ...)

Comparison

Feature	yarutsk	ruamel.yaml	PyYAML
Comments preserved	Yes	Yes	No
Scalar styles preserved	Yes	Partial	No
Insertion order preserved	Yes	Yes	No
Blank lines preserved	Yes	Partial	No
Tags preserved	Yes	Yes	No
Anchors/aliases preserved	Yes	Yes	No
dict / list subclasses	Yes	No	No
Rust speed	Yes	No	No

yarutsk focuses on round-trip fidelity: edit a config file and emit it back without touching the formatting. ruamel.yaml offers similar fidelity in pure Python. PyYAML is faster for load-only workloads where output formatting doesn't matter.

Documentation

Everything — the full API, type conversions, Schema and library integrations (pydantic / msgspec / cattrs), error handling, thread safety, and limitations — lives at https://theyugin.github.io/yarutsk/.

Direct links:

• Installation
• API reference
• Library integrations
• Round-trip fidelity
• Error handling
• Thread safety
• Limitations
• Changelog
• Contributing

Benchmarks

Compare load, dump, and round-trip performance against PyYAML and ruamel.yaml:

make bench

License

MIT. The scanner and parser are vendored from yaml-rust2 (also MIT) with one targeted modification: the comment-skipping loop now emits Comment tokens instead of discarding them.