pyrs-yaml

A high-performance Python YAML library with perfect round-trip support, built with Rust and PyO3.

Features

YAML 1.2 compliant - Uses granit-parser for full YAML 1.2 support with native comment preservation
Perfect Round-Trip - Preserves comments, anchors, tags, chomping, scalar styles, and flow/block formatting
In-Place Editing - Edit parsed documents via JSONPath-style paths (doc.set("$.a.b", v)) or the Node tree API, without losing formatting
High Performance - Rust backend, 7× faster safe_dump/from_dict vs v0.10 (direct writer, no intermediate AST); fast-path safe_load/safe_loads skips anchor tracking when none present
Depth-limited parsing - max_depth (default 1000) on parse, parse_file, parse_all_docs, parse_stream, safe_load, safe_loads, read_markdown, read_markdown_str to prevent deep nesting attacks
NumPy ndarray support - safe_dump() / safe_dumps() / from_dict() / dump_file() serialize numpy.ndarray of any dimension (0-D through N-D) with zero-copy Rust dispatch
JSON Schema validation - YamlDocument.validate(schema) validates parsed documents against JSON Schema; YamlValidateError for failures
Async I/O - safe_dumps_async / safe_dump_async / safe_loads_async / safe_load_async via asyncio.run_in_executor
Incremental re-parse - doc.source() + doc.reparse() for re-parsing stored YAML in-place with different options (e.g. schema="yaml1.1")
JSON serialization - doc.to_json() exports documents to standard JSON
Duplicate keys - allow_duplicate_keys=True opts into last-value-wins; YamlDuplicateKeyError otherwise
Custom tag handlers - register_tag with priority-based chaining, YamlTagSkip, remove_tag/clear_tag_handlers
Pydantic models - parse_as(Model, yaml) validates parsed YAML against Pydantic v2 models
Custom AST - Extensible AST for advanced YAML manipulation
PyYAML Compatible - Drop-in replacement with safe_load/safe_dump API

Installation

pip install pyrs-yaml

Or with uv:

uv pip install pyrs-yaml

Requirements

Supported Python versions (installing wheels): Python 3.8+ (CPython; PyPy and free-threaded 3.14t wheels are also published). abi3 wheels mean one wheel covers all supported Python versions.
Rust toolchain (building from source only): Rust 1.96 or later (MSRV, edition 2024). This is above PyO3's own baseline (rustc 1.83+ for PyO3 0.29) and is chosen deliberately for std API headroom — it keeps current stable APIs (e.g. assert_matches!, stabilized in 1.96) available without waiting for a future MSRV bump. End users installing wheels never need Rust.

Documentation

Full documentation (English, 简体中文, 日本語, 한국어) is available at https://759401524.github.io/pyrs-yaml. See CONTRIBUTING.md for development guidelines.

Quick Start

import pyrs_yaml

# Parse YAML
doc = pyrs_yaml.parse("key: value")
print(doc.to_yaml())  # key: value

# PyYAML compatible API
data = pyrs_yaml.safe_load("key: value")
print(data)  # {'key': 'value'}

# Round-trip preserves comments
original = "# Comment\nkey: value  # inline\n"
doc = pyrs_yaml.parse(original)
assert doc.to_yaml() == original  # True

# Edit in place without losing formatting
doc.set("$.key", "edited")  # key: edited  # inline
doc.set("$.new", 1)  # add a new key
print(doc.to_yaml())

JSON Schema validation

doc = pyrs_yaml.parse("name: Alice\nage: 30")
doc.validate({"type": "object", "properties": {"name": {"type": "string"}}})
# None — validation passed

# Invalid — raises YamlValidateError
doc.validate({"type": "object", "required": ["email"]})
# pyrs_yaml.YamlValidateError: "Email" is a required property

Async serialization

import asyncio
import pyrs_yaml


async def main():
    yaml = await pyrs_yaml.safe_dumps_async({"a": 1})
    data = await pyrs_yaml.safe_loads_async(yaml)
    print(data)  # {'a': 1}


asyncio.run(main())

Incremental re-parse

doc = pyrs_yaml.parse("x: on")
print(doc.get("x"))  # "on" (core schema: string)

doc.reparse(schema="yaml1.1")
print(doc.get("x"))  # True (yaml1.1 schema: bool)

JSON export

doc = pyrs_yaml.parse("a: 1\nb: hello")
json_str = doc.to_json()  # '{"a": 1, "b": "hello"}'

NumPy ndarray support

import numpy as np
import pyrs_yaml

# 1-D array
arr = np.array([1, 2, 3], dtype="int32")
yaml_str = pyrs_yaml.safe_dump(arr)
print(yaml_str)
# - 1
# - 2
# - 3

# 2-D matrix
matrix = np.array([[1, 2], [3, 4]], dtype="float64")
yaml_str = pyrs_yaml.safe_dump(matrix)
print(yaml_str)
# -
#   - 1.0
#   - 2.0
# -
#   - 3.0
#   - 4.0

# Round-trip
loaded = pyrs_yaml.safe_load(yaml_str)
assert loaded == [[1.0, 2.0], [3.0, 4.0]]

Duplicate keys

Duplicate mapping keys raise YamlDuplicateKeyError by default:

pyrs_yaml.parse("key: first\nkey: second")
# pyrs_yaml.YamlDuplicateKeyError: duplicate key: key

Pass allow_duplicate_keys=True to keep the last value instead:

doc = pyrs_yaml.parse("key: first\nkey: second", allow_duplicate_keys=True)
doc.get("key")  # "second"

The flag is available on parse, safe_load, safe_loads, parse_file, parse_all_docs, and YAML(allow_duplicate_keys=True). In round-trip mode, serializing a document with allowed duplicate keys emits the last occurrence.

Serialization options

to_yaml_with_options() controls indentation and line wrapping:

yaml_str = doc.to_yaml_with_options(
    indent_size=2,  # legacy base indent (used when the per-type options are omitted)
    width=80,  # line-wrap width; 0 disables wrapping
    indent_mapping=4,  # indent per block-mapping level
    indent_sequence=2,  # indent per block-sequence level
    indent_offset=0,  # base offset applied to the whole document
)

indent_mapping / indent_sequence / indent_offset default to indent_size / 0 when omitted, so indent_size=4 still indents everything by 4.

Tag handlers

import pyrs_yaml


# Decorator form
@pyrs_yaml.register_tag("!custom")
def custom_handler(node):
    return f"custom:{node}"


# Imperative form
pyrs_yaml.register_tag("!custom", lambda node: node.upper())

doc = pyrs_yaml.parse("name: !custom value")
doc.get("name")  # "custom:value"

Multiple handlers per tag run in ascending priority order; raising YamlTagSkip passes control to the next handler.
A handler must return a string — anything else raises YamlTagError.
remove_tag("!custom") and clear_tag_handlers() unregister handlers.

Pydantic models

Parse YAML directly into a Pydantic v2 model:

from pydantic import BaseModel
import pyrs_yaml


class Config(BaseModel):
    name: str
    age: int


cfg = pyrs_yaml.parse_as(Config, "name: Alice\nage: 30")
cfg.name  # "Alice"

parse_as raises TypeError for non-BaseModel targets and propagates Pydantic's ValidationError when the YAML does not match the model.

Features Supported

Feature	Support
YAML 1.2	Full
Comments (standalone + inline)	Preserved
Anchors (`&`) and aliases (`*`)	Preserved
Tags (`!!str`, `!!int`, etc.)	Preserved
Chomping (`\|-`, `\|+`, `>-`, `>+`)	Preserved
Complex keys (sequence/mapping as key)	Supported
Escape sequences (`\n`, `\t`, `\uXXXX`)	Supported
Flow collections (`{}`, `[]`)	Preserved
Block scalars (`\|`, `>`)	Preserved
Merge keys (`<<: *alias`)	Resolved (opt-out via `resolve_merges=False`)
NumPy ndarray	Full (0-D through N-D)
JSON Schema validation	Full
Async I/O	Full
Incremental re-parse	Full
JSON export	Full
Duplicate keys	Configurable (`YamlDuplicateKeyError` / last-wins)
Custom tag handlers	Priority-chained `register_tag`
Pydantic models	`parse_as()` validation

API Reference

Core Functions

# Parse YAML string (accepts str or bytes)
doc = pyrs_yaml.parse(yaml_str)
doc = pyrs_yaml.parse(yaml_bytes)

# Parse with options (max_depth, schema, allow_duplicate_keys)
doc = pyrs_yaml.parse(yaml_str, resolve_merges=False, max_depth=500, schema="yaml1.1")

# Parse YAML file
doc = pyrs_yaml.parse_file("config.yaml")

# Parse multiple YAML documents
docs = pyrs_yaml.parse_all_docs(yaml_str)

# Stream parsing (on_event callback)
def handler(event):
    print(event)
    return True  # return False to stop
iter = pyrs_yaml.parse_stream(yaml_str, on_event=handler, max_depth=1000)

# Convert to YAML string (with options)
yaml_str = doc.to_yaml()
yaml_str = doc.to_yaml_with_options(indent_size=4, explicit_start=True, sort_keys=True)

# Get value by key (with default)
value = doc.get("key")
value = doc.get("missing_key", "default")

# Get root type
doc.root_type()  # "mapping", "sequence", "scalar", "null"

# Check containment and length
"key" in doc
len(doc)

# Iterate
for key in doc:
    print(key, doc[key])

# Dump to YAML from dict
yaml_str = pyrs_yaml.from_dict(data)

# i18n language management
pyrs_yaml.set_language("zh-CN")
pyrs_yaml.get_language()  # "zh-CN"
pyrs_yaml.list_languages()  # ["en", "zh-CN"]
pyrs_yaml.detect_language()  # auto-detect from environment
pyrs_yaml.negotiate_language(["zh-CN", "en"], "en")  # "zh-CN"

PyYAML Compatible API

# Load YAML to dict (supports schema and max_depth)
data = pyrs_yaml.safe_load(yaml_str)
data = pyrs_yaml.safe_load(yaml_str, schema="yaml1.1", max_depth=500)

# Load multiple documents
docs = pyrs_yaml.safe_loads(yaml_str)
docs = pyrs_yaml.safe_loads(yaml_str, allow_duplicate_keys=True)

# Dump dict to YAML
yaml_str = pyrs_yaml.safe_dump(data)

# Convert dict to YAML
yaml_str = pyrs_yaml.from_dict(data)

# Convert JSON to YAML
yaml_str = pyrs_yaml.from_json(json_str)

# Dump to file
pyrs_yaml.dump_file(data, "output.yaml")

# Extract YAML frontmatter from markdown
frontmatter, content = pyrs_yaml.read_markdown("post.md")
frontmatter, content = pyrs_yaml.read_markdown_str(markdown_text)
frontmatter, content = pyrs_yaml.read_markdown_str(markdown_text, max_depth=200)

Performance

divan benchmarks in crates/pyrs-yaml/benches/yaml_bench.rs (Rust) + pytest-codspeed in tests/test_benchmark_crosslib.py (Python). See benchmarks docs for the full cross-library comparison against PyYAML and ruamel.yaml.

v0.11 highlights (vs v0.10):

safe_dump / from_dict / dump_file / dump_iterable: 7× faster — direct writer eliminates intermediate CustomNode AST
safe_load / safe_loads / to_dict: fast-path — skips anchor tracking when input has no & characters
resolve_core_type: first-byte dispatch — non-numeric/boolean scalars return Str immediately

Development

# Install dependencies
uv sync

# Build Python extension
uv run maturin develop --release

# Run tests (Rust: cargo nextest; Python: uv run pytest)
cargo nextest run --all
uv run pytest tests/ -v --ignore=tests/benchmark_compare.py

# Lint and format (Rust + Python)
cargo clippy -- -D warnings
cargo fmt
uv run ruff check .
uv run ruff format .

# Run benchmarks (Rust)
cargo bench

# Run benchmarks (Python)
uv run pytest tests/test_benchmark_crosslib.py tests/test_benchmark_api.py --codspeed

# Performance sanity checks
uv run pytest tests/test_performance.py -v

# Git hooks
prek install --prepare-hooks
prek run --all-files

License

Licensed under either of:

at your option.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyrs_yaml-0.15.0.tar.gz (159.5 kB view details)

Uploaded Aug 19, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pyrs_yaml-0.15.0-cp314-cp314t-win_arm64.whl (1.3 MB view details)

Uploaded Aug 19, 2026 CPython 3.14tWindows ARM64

pyrs_yaml-0.15.0-cp314-cp314t-win_amd64.whl (1.4 MB view details)

Uploaded Aug 19, 2026 CPython 3.14tWindows x86-64

pyrs_yaml-0.15.0-cp314-cp314t-win32.whl (1.3 MB view details)

Uploaded Aug 19, 2026 CPython 3.14tWindows x86

pyrs_yaml-0.15.0-cp314-cp314t-macosx_11_0_arm64.whl (1.3 MB view details)

Uploaded Aug 19, 2026 CPython 3.14tmacOS 11.0+ ARM64

pyrs_yaml-0.15.0-cp314-cp314t-macosx_10_12_x86_64.whl (1.4 MB view details)

Uploaded Aug 19, 2026 CPython 3.14tmacOS 10.12+ x86-64

pyrs_yaml-0.15.0-cp38-abi3-win_arm64.whl (1.3 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+Windows ARM64

pyrs_yaml-0.15.0-cp38-abi3-win_amd64.whl (1.4 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+Windows x86-64

pyrs_yaml-0.15.0-cp38-abi3-win32.whl (1.3 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+Windows x86

pyrs_yaml-0.15.0-cp38-abi3-musllinux_1_2_x86_64.whl (1.7 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+musllinux: musl 1.2+ x86-64

pyrs_yaml-0.15.0-cp38-abi3-musllinux_1_2_i686.whl (1.7 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+musllinux: musl 1.2+ i686

pyrs_yaml-0.15.0-cp38-abi3-musllinux_1_2_aarch64.whl (1.6 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+musllinux: musl 1.2+ ARM64

pyrs_yaml-0.15.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.5 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+manylinux: glibc 2.17+ x86-64

pyrs_yaml-0.15.0-cp38-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl (1.5 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+manylinux: glibc 2.17+ s390x

pyrs_yaml-0.15.0-cp38-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl (1.5 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+manylinux: glibc 2.17+ ppc64le

pyrs_yaml-0.15.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.4 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+manylinux: glibc 2.17+ ARM64

pyrs_yaml-0.15.0-cp38-abi3-manylinux_2_5_i686.manylinux1_i686.whl (1.5 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+manylinux: glibc 2.5+ i686

pyrs_yaml-0.15.0-cp38-abi3-macosx_11_0_arm64.whl (1.3 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+macOS 11.0+ ARM64

pyrs_yaml-0.15.0-cp38-abi3-macosx_10_12_x86_64.whl (1.4 MB view details)

Uploaded Aug 19, 2026 CPython 3.8+macOS 10.12+ x86-64

File details

Details for the file pyrs_yaml-0.15.0.tar.gz.

File metadata

Download URL: pyrs_yaml-0.15.0.tar.gz
Upload date: Aug 19, 2026
Size: 159.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for pyrs_yaml-0.15.0.tar.gz
Algorithm	Hash digest
SHA256	`65e783dfb09724eaa71372d41dd1bb9238b0b53e57767b396ed2c6872ed4a8ac`
MD5	`510c7f9d383575cdb9449ac819265818`
BLAKE2b-256	`2f55a5ee756bf78b5c67e77e670cf5c722d68947d2bb5c87de987ced15524fad`

Algorithm	Hash digest
SHA256	`95a7bc59770a216d52abfa5f61eee3ac0ea853f6eed6c273a9365947a9ff2c94`
MD5	`c3dbb9a9e8bc4ee6f0a3d0c66d36f10a`
BLAKE2b-256	`1978b3c6ae7466739f2e32d7e93fb7ab1b3c2517a123ac40173cde21e7f25bd1`

Algorithm	Hash digest
SHA256	`96c863b5cba52f5368d5120fff92f6a13a1cf0b553df42821f5b0e0c3be3841d`
MD5	`3904e63c6402a82f88072d213cebe3a1`
BLAKE2b-256	`af5087176ec615d41d88b8ea62376acb2563b94769a1bee82e52bacaf5009c1a`

Algorithm	Hash digest
SHA256	`1e10a8d90d0ef94b917a7db84c4244ce4d0110bfeb4098687ac3fe4ae9554cf9`
MD5	`7f0fc0596f41c743f306870ca07aca44`
BLAKE2b-256	`7e8a440d07eb283c930c72195ab1abd984c832538796b20d9e5c1c0370e5fd3b`

Algorithm	Hash digest
SHA256	`edc11d00e4157a584b2b4ea1811b38c6e0696011bd62bfd120715ad4a7badbb9`
MD5	`4a7c8cc55299a1c4703235fb1dffc468`
BLAKE2b-256	`8ab4583839f8f11a4a6ca4412e704caae67f0952ec5870f1af1a8cb31f007c6e`

Algorithm	Hash digest
SHA256	`e37ac23895d5230a89cbd1f116312c8be553bda99cb64f419f2e81f667b8c227`
MD5	`d6e835ee3f05b8473f91f94367f5b479`
BLAKE2b-256	`c2dfc005c3f4cc52cd97493524c3cd0fcf77330d796f7e5aa8b75ca7223adb92`

Algorithm	Hash digest
SHA256	`b0258f84e4af4d4b1fb3704d5a5b9f8c9775ff4304a354d1847a269ae0282eaa`
MD5	`ba5f6d5163850f2270eed59621322da5`
BLAKE2b-256	`be034619f6a7dfd9905923a9e89fa86b5ff0eec44e067e1d784b5b6de3a8963e`

Algorithm	Hash digest
SHA256	`bcfcb71137f76bfa2467d4bfe2c63cac828dacdd663ec04cb306b88ed324cc44`
MD5	`41784c7db7f46792d009b0f2eeef648a`
BLAKE2b-256	`b21853ebc3fefa43de8ba7425e629a86c602af41892d2740cc48b36948ad31b2`

Algorithm	Hash digest
SHA256	`71e140a71013c2df8b2bd84bfcccba221413e971daccc0ba856c146341e1c2b3`
MD5	`206ddebad3eefab0013b0363bfcaba78`
BLAKE2b-256	`6ce2ca734d78701e172ac43586c2b6f49f6a7f386245324e783c1d2ab0fb92ef`

Algorithm	Hash digest
SHA256	`d34dadefdc0bf2cf5369fdfac2007e1577a6e870772d062081083a5671c63014`
MD5	`7b5bd34f8ed0a3734e1c593e51d600c6`
BLAKE2b-256	`27b5804547567c10ff0c19bcc7d4051904c5d162a8652c13b63461b00d83ceb3`

Algorithm	Hash digest
SHA256	`20f79fb7cac2b19533a9bf6750a86e1b830aa58f9f129893cf19afff722ae657`
MD5	`378a79cbac615d91f30958f982238392`
BLAKE2b-256	`cbf286f8bbc5524dd686a51881dd7aafc0e274c2846f4801fbdccbfe3c85c5b0`

Algorithm	Hash digest
SHA256	`ffda5cc5f98254a74b852b0a91039968d9266e2db92ed8ed731a0bb6b9152614`
MD5	`f1214a39f11ff5e1869c0564f311c208`
BLAKE2b-256	`2cd69030939fd35f407e18e34c724220cbd853720aa9911755f379cf8a737f72`

Algorithm	Hash digest
SHA256	`a4397d7f5f46ab33c482e16c81c074190e39249e99240ba20f8369513d1f2e57`
MD5	`8be97558c5a2ecf144eaf5501ae4e691`
BLAKE2b-256	`980ba72a8957c2b76dd0a17e1ab237ce944b1b7e9729317d5984d3509dd1481d`

Algorithm	Hash digest
SHA256	`e0511fc8a60b767ab0140f443bb9862922f1c8027623c048cf339349bcf3b216`
MD5	`b0593431ec3abdd2906b5660315147dc`
BLAKE2b-256	`9c20f0c07808633b7204e641f5174f28ffffc974195512b3e9d9f006dae586f1`

Algorithm	Hash digest
SHA256	`0b72b8c8fb18c1493314855d3b3010c0fa0c1774b3d76b8d3b422eb5d5b4dc57`
MD5	`12c2766c9bb9480c4ca31d0a172e1aca`
BLAKE2b-256	`3905f2d37e6fababddda22f58cc75a0b3aa1f2454e2e3d3a466da4344f18a9da`

Algorithm	Hash digest
SHA256	`9cf02ebdd25edf234df02dc04ef8c3894131ffce21b58fec6d01ebde58a541ce`
MD5	`d01939f34ec434126975a077cfb9c74f`
BLAKE2b-256	`5b019ba0afb5f5fa29f14684b2322651d2236a5d13888e534c782273c8ec9900`

Algorithm	Hash digest
SHA256	`211c634d6da07df081c9cc7e41c875c1329a945dcdefa34b66fd91435d8a6d19`
MD5	`c5c74413451db7959fd4d3180fc4af04`
BLAKE2b-256	`b7c6f4d8d22148c923e19845e97b674b03db46e847646371ad289f39e723992c`

Algorithm	Hash digest
SHA256	`f56dc51280b722dbd2d032ab180c3acee64b2941aef52f06d6e9b26274ca8ce7`
MD5	`06a0aec01cd0bfe13650aadbafbd878a`
BLAKE2b-256	`aeceabe0e5a154af6051eecf067277667ed436133af1ee1114f3032029050ab3`

Algorithm	Hash digest
SHA256	`66e4d9a1ef74ea346f7fe2604d2b8ad2813e584f9b5da19e9778e0c79538a79b`
MD5	`bcb4191f8ee1c68b3581fa5994b756e2`
BLAKE2b-256	`32135f935e1fc5775ba9c9873b2d8bce1e5033f3c3eca674958f77bba5ea459e`

pyrs-yaml 0.15.0

pyrs-yaml

Features

Installation

Requirements

Documentation

Quick Start

JSON Schema validation

Async serialization

Incremental re-parse

JSON export

NumPy ndarray support

Duplicate keys

Serialization options

Tag handlers

Pydantic models

Features Supported

API Reference

Core Functions

PyYAML Compatible API

Performance

Development

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata