pythonizeyaml

English | 简体中文

pythonizeyaml is a YAML library with a PyYAML-compatible API and a lossless round-trip engine implemented in Rust. Loading and dumping an untouched document reproduces its source text, including comments, blank lines, indentation, scalar styles, document markers, anchors, and multi-document layout.

The parser and emitter are compiled through PyO3 and Maturin. There is no Python YAML runtime dependency.

Comparison with Other YAML Libraries

The table below compares pythonizeyaml 0.6.1 with PyYAML, yamltrip, and ruamel.yaml.

The biggest practical distinctions:

• Compared with PyYAML: pythonizeyaml keeps source layout by default, but is much younger and lacks PyYAML's mature event API, custom constructor ecosystem, encoding breadth, and long-term compatibility history. Unlike unsafe PyYAML loaders, it does not execute !!python/... tags.
• Compared with yamltrip: yamltrip is optimized around editing and querying YAML files through Document/Editor; it explicitly does not support multi-document streams, tag interpretation, anchor resolution, or arbitrary-size integer preservation. pythonizeyaml provides a PyYAML-style data API and broader YAML semantics, but its structural-edit patching is less specialized than yamltrip's.
• Compared with ruamel.yaml: ruamel is the mature reference for mutable comment-preserving YAML objects. pythonizeyaml instead promises exact source replay for unchanged documents and uses Rust-native parsing, Decimal precision policy, and Tagged values. It does not yet offer ruamel's class registration, plug-in ecosystem, or depth of YAML conformance coverage.

Sources: PyYAML repository, yamltrip README, and ruamel.yaml repository.

Requirements

• Python 3.10 or newer
• Rust 1.83 or newer when building from source
• Maturin 1.15 or newer for extension development

Installation

pip install pythonizeyaml

Optional Pydantic integration: pip install "pythonizeyaml[pydantic]" (adds YAMLModel); add pip install "pythonizeyaml[pydantic-settings]" for YAMLSettings.

For a source checkout:

poetry install
poetry run maturin develop

Quickstart

import pythonizeyaml as yaml

document = yaml.load(open("config.yaml", encoding="utf-8"))
document["service"]["port"] = 9090
text = yaml.dump(document)

Only the changed scalar is rewritten. Comments and formatting elsewhere remain byte-identical. Pass a writable stream as the second argument to write directly:

with open("config.yaml", "w", encoding="utf-8") as handle:
    yaml.dump(document, handle)

Command Line

Installing the wheel also installs a yaml command for quick path-based edits from the shell:

yaml config.yaml get service.port          # 8080
yaml config.yaml set service.port 9090     # rewrites only that scalar
yaml config.yaml set tls.enabled true      # creates the missing chain
yaml config.yaml del service.debug

Paths are dot-separated (foo.bar.jay); a numeric segment addresses an item of the sequence at that point (servers.0.host). set creates missing intermediate mappings automatically, and values are interpreted as YAML — true is a boolean, 123 an integer, null is null — so quote them ("'123'") to force a string. Everything the command does not touch keeps its original comments, indentation, and scalar styles. See the CLI chapter for details.

Numeric Resolution

Integers use Python's arbitrary-precision int. Decimal and exponent literals are compared exactly with IEEE 754 binary64:

from decimal import Decimal
import pythonizeyaml as yaml

assert type(yaml.load("value: 1.5\n")["value"]) is float
assert type(yaml.load("value: 0.1\n")["value"]) is Decimal
assert type(yaml.load("value: 1e400\n")["value"]) is Decimal

Use !!float to force float or !!decimal to force Decimal.

Tags and Safety

The core and common standard YAML tags are resolved, including !!binary, !!timestamp, !!set, and merge keys. Unknown application tags are returned as pythonizeyaml.Tagged(tag, value) and preserve their spelling during round trips.

Use safe_load or safe_load_all for untrusted YAML. These functions reject non-standard tags instead of constructing arbitrary Python objects.

value = yaml.safe_load("enabled: true\n")

full_load/full_load_all return plain data while tolerating unknown tags (they come back as inert Tagged values), and unsafe_load/unsafe_load_all are documented aliases of them. Like every loader in this library, they never construct arbitrary Python objects.

API

The module exposes:

• load, load_all, dump, dump_all
• safe_load, safe_load_all, safe_dump, safe_dump_all
• full_load, full_load_all, unsafe_load, unsafe_load_all
• round_trip_load, round_trip_load_all, round_trip_dump, round_trip_dump_all
• YAML, SafeYAML, IndentConfig, DEFAULT_CONFIG, Tagged
• Document, DocumentStream, and Comments
• load_document, load_documents, read_document, and read_documents
• ScalarStyle, CollectionStyle, Chomping, and SourceSpan
• YAMLError and its PyYAML-compatible subclasses
• YAMLModel, and with pydantic-settings also YAMLSettings (optional Pydantic integration)

Loader=, Dumper, sort_keys, default_flow_style, allow_unicode, and encoding are accepted for migration compatibility and ignored where they conflict with lossless output.

Advanced Style Documents

load(), load_all(), and load_document() all return mutable, style-aware Document objects whose values carry the styling API directly. For explicit control over comments, scalar styles, collection styles, tags, anchors, aliases, directives, and document markers, style the values you read:

from pythonizeyaml import ScalarStyle, load_document

document = load_document("name: example\nitems:\n  - one\n  - two\n")
document["name"].style = ScalarStyle.DOUBLE
document["name"].comments.before = ["# service name"]
document["items"].collection_style = "flow"

text = document.dump()

load_document() returns one mutable Document; load_documents() returns a list-like DocumentStream. Collection roots load as DocumentMapping or DocumentSequence (dict/list subclasses) and scalar roots as DocumentScalar. Every value inside a document is a round-trip wrapper — a dict/list subclass, or a subclass of the scalar's own type — that compares and hashes like a plain value. Assigned scalars are wrapped and plain dict/list values are converted, so new subtrees are styleable immediately. Documents edit like their wrapped dict/list: document["key"] = value, del document["key"], document["items"].append(x). Use Document.new() to create styled documents from scratch.

Values expose path, value, span, style, collection_style, chomping, block_indent_indicator, tag, anchor, and comments. The set(...) method applies multiple fields atomically. Style changes are validated before mutation; see StyleError, PathError, and AliasError for failures. bool and None values are plain (they cannot be subclassed) and are the only loaded scalars without this API.

For repository setup, testing, and contribution conventions, see CONTRIBUTING.md.

Indentation Configuration

IndentConfig(mapping=2, sequence=2, offset=0, width=80, preserve_quotes=True) controls newly created data and explicit re-layout requests. Loaded documents retain their original layout unless an override is supplied.

Development

cargo test --manifest-path rust/Cargo.toml --no-default-features
poetry run maturin develop
poetry run pytest
poetry build

Tests run against tests/fixtures/; add malformed inputs under tests/fixtures/invalid/.

Root Scalar Documents

Root scalars load as DocumentScalar, a Document wrapper that keeps source metadata and scalar styles (quotes, block headers) but is not a str/int subclass. It compares equal to the wrapped value and coerces through str(), int(), float(), and bool(); nested scalars are ordinary Python values with their original style and formatting retained.