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.5.0 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)

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.