Edit YAML files from Python, while respecting format and comments during the round-trip.
Built on tree-sitter-yaml via the yamlpath and yamlpatch Rust crates.
# With uv
$ uv add yamltrip
# With pip
$ pip install yamltripimport yamltrip
# Load and read
doc = yamltrip.loads("name: Alice\nage: 30")
print(doc["name"]) # "Alice"
print("name" in doc) # True
# Immutable mutations: each call returns a new Document
doc2 = doc.replace("age", value=31)
doc3 = doc2.add(key="city", value="Portland")
print(doc3.dumps())
# Complex values (dicts/lists) work too
doc4 = doc3.replace("age", value={"years": 31, "months": 4})
doc5 = doc4.upsert("hobbies", value=["reading", "hiking"])
# File-based editing with a context manager
with yamltrip.edit("config.yml") as editor:
editor.replace("version", value="2.0")
editor.upsert("settings", "debug", value=True)
# writes back on successful exit; discards on exception| Function | Description |
|---|---|
yamltrip.loads(source) |
Parse a YAML string into a Document |
yamltrip.load(path) |
Read a YAML file into a Document |
yamltrip.edit(path) |
Open a YAML file for editing (context manager) |
Every mutation method returns a new Document. The original is never
modified.
doc = yamltrip.loads("items:\n - a\n - b")
doc.root # {"items": ["a", "b"]}
doc["items"] # ["a", "b"]
doc["items", 0] # "a"
("items", 0) in doc # True
doc.get("items", 0) # "a" (returns None if missing)
doc.get("missing", default=42) # 42
doc.replace("items", 0, value="x")
doc.replace("items", value=["x", "y"]) # dicts and lists accepted
doc.add("items", key="c", value=3)
doc.upsert("new", "nested", value=True)
doc.upsert("config", value={"debug": True}) # dicts and lists accepted
doc.remove("items", 0)
doc.prune_remove("a", "b", "c") # remove + prune empty parents
doc.append("items", value="c")
doc.insert("items", index=1, value="between") # positional insert
doc.extend_list("items", values=["d", "e"])
doc.remove_from_list("items", values=["a"])
doc.sync("items", value=["a", "new", "b"]) # minimal diff-and-patch
doc.query("items") # Feature with location info
doc.query_pretty("items") # Feature with surrounding context
doc.extract(feature) # raw YAML text for a Feature
doc.has_anchors() # True if anchors/aliases present
doc.dumps() # full YAML source
doc.dump("output.yml") # write to fileWraps Document with the same mutation methods, but applies changes in place
and writes back to disk when the context exits cleanly:
with yamltrip.edit("config.yml") as ed:
ed.replace("version", value="2.0")
ed.upsert("new_key", value="new_value")
ed.remove("old_key")
ed.sync("deps", value={"a": "1.0", "b": "2.0"}) # minimal patching
print(ed["version"]) # "2.0"
print(ed.get("missing")) # None
print(ed.original["version"]) # original value before editsAll yamltrip errors inherit from YAMLTripError:
ParseError: YAML input cannot be parsed.QueryError: path not found during lookup.PatchError: mutation operation failed.KeyExistsError:add()target already exists.KeyMissingError:replace()target does not exist.
- Multi-document YAML streams (
---separated) are not supported. - YAML tags (
!!omap,!!set,!!merge, custom tags) are not interpreted. - Anchors and aliases (
&anchor/*alias) are detected (doc.has_anchors()) but not resolved during value extraction. - Large integers may lose precision. YAML integers outside the signed
64-bit range (i64) may become
floatduring deserialization. - Editor write-back is not atomic.
Editordetects external file changes between enter and exit, but the check-then-write is racy. Do not use it with concurrent writers.
- No custom Python class serialization. Values convert to/from
str,int,float,bool,None,list, anddictonly. - UTF-8 only. Other encodings raise
ParseError. - Non-finite floats round-trip.
float("inf"),float("-inf"), andfloat("nan")map to YAML's.inf,-.inf, and.nan. - Integer keys cannot create structures.
upsert()with integer path components can update existing sequence entries but cannot create new intermediate mappings. Only string keys create new mappings. - No negative sequence indices for lookup. Python-style negative indexing
is not supported for
[]access orreplace()/remove(). However,insert()accepts negative indices (matchinglist.insert()semantics). - Line endings preserved as-is. No CRLF/LF normalization. Mixed line endings pass through unchanged.
yamltrip depends entirely on the yamlpath and yamlpatch Rust crates for format-preserving YAML parsing and patching. These libraries use tree-sitter to query and modify YAML source text without discarding comments, whitespace, or key ordering. All of the core logic in yamltrip passes through them. Thanks to William Woodruff for creating and maintaining both crates as part of zizmor.
MIT