pyrs-yaml

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

Features

YAML 1.2 compliant - Uses saphyr-parser for full YAML 1.2 support
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, see benchmarks
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
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

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
doc = pyrs_yaml.parse(yaml_str, resolve_merges=False)

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

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

# 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])

PyYAML Compatible API

# Load YAML to dict
data = pyrs_yaml.safe_load(yaml_str)

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

# 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)

# 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"

Performance

Criterion benchmarks in 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:

Operation	Time
Parse (small, ~2 keys)	~1.7 µs
Parse (medium, ~30 keys)	~12 µs
Parse (large, ~60 keys)	~38 µs
Serialize (small)	~4.4 µs
Serialize (medium)	~4.7 µs
Serialize (large)	~5.5 µs
Roundtrip (small)	~5.9 µs
Roundtrip (large)	~45 µs

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.12.1.tar.gz (111.0 kB view details)

Uploaded Aug 6, 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.12.1-cp314-cp314t-win_arm64.whl (556.0 kB view details)

Uploaded Aug 6, 2026 CPython 3.14tWindows ARM64

pyrs_yaml-0.12.1-cp314-cp314t-win_amd64.whl (580.7 kB view details)

Uploaded Aug 6, 2026 CPython 3.14tWindows x86-64

pyrs_yaml-0.12.1-cp314-cp314t-win32.whl (542.3 kB view details)

Uploaded Aug 6, 2026 CPython 3.14tWindows x86

pyrs_yaml-0.12.1-cp314-cp314t-macosx_11_0_arm64.whl (600.4 kB view details)

Uploaded Aug 6, 2026 CPython 3.14tmacOS 11.0+ ARM64

pyrs_yaml-0.12.1-cp314-cp314t-macosx_10_12_x86_64.whl (637.8 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-win_arm64.whl (591.7 kB view details)

Uploaded Aug 6, 2026 CPython 3.8+Windows ARM64

pyrs_yaml-0.12.1-cp38-abi3-win_amd64.whl (624.1 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-win32.whl (575.4 kB view details)

Uploaded Aug 6, 2026 CPython 3.8+Windows x86

pyrs_yaml-0.12.1-cp38-abi3-musllinux_1_2_x86_64.whl (889.1 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-musllinux_1_2_i686.whl (915.5 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-musllinux_1_2_aarch64.whl (821.9 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (677.2 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl (717.1 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl (736.8 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (643.6 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-manylinux_2_5_i686.manylinux1_i686.whl (704.7 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-macosx_11_0_arm64.whl (633.5 kB view details)

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

pyrs_yaml-0.12.1-cp38-abi3-macosx_10_12_x86_64.whl (662.0 kB view details)

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

File details

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

File metadata

Download URL: pyrs_yaml-0.12.1.tar.gz
Upload date: Aug 6, 2026
Size: 111.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for pyrs_yaml-0.12.1.tar.gz
Algorithm	Hash digest
SHA256	`c4f0cb20dd8e29282100e1a1dbc00e46ff720224c9f63ed2484c743b6cee4aff`
MD5	`c44b05c39b8c710b6fddef60da8ef919`
BLAKE2b-256	`bc644963031e88532e09458b00845f1b3d316469b7c682d414515f94c1e32bbc`

Algorithm	Hash digest
SHA256	`e346891edb17a71472d6cc64afadfb7c758cd8d964f22ecafcc353212e10f5f2`
MD5	`bd8dcd576e2df756cb7eee1652b7af42`
BLAKE2b-256	`9678f2eca1bc07b49dc3d69681e692ca29945ac9a9bfdbdc1f503cc7dac395f6`

Algorithm	Hash digest
SHA256	`e905ad51ba09d5c80139a1f18d46b7450237db6cffd2b5ae710b6857a229a01a`
MD5	`c2874595c81352560ce0413edaa93267`
BLAKE2b-256	`c13ded4d27c2e09c832b316b5d6f777bc6c6519cbf97ae0feaa6069c26671ed6`

Algorithm	Hash digest
SHA256	`598c3c5f0e12a0b3acd33e2e6b8551121c02360558335220ceab65525ff8c0db`
MD5	`f5a08172ee603141195e42aa79532f61`
BLAKE2b-256	`725ffde551f69c5f90b7a60a33e917d96872a47b02c48841e2de7944067e98a0`

Algorithm	Hash digest
SHA256	`256211bd1ebfa51eef9177035d2a44b423fdb07cbc0429f0773a94c3c5455fac`
MD5	`9920525ac1459d1ef7206b0758245e67`
BLAKE2b-256	`0c56712e66a7154bb1ea5bf1634f06490cf66bd8b21bf79b9bde91e52fb39beb`

Algorithm	Hash digest
SHA256	`83512e6e7e7077887a7cf4d8ca8fa44b6a87c473e2244825dff49d4f50e01129`
MD5	`c38079dd92716ab9c12a1c5652cb4cfc`
BLAKE2b-256	`74fd592c09928ff28351d2d45bcf6297b7bb63e353ee23509ed94959a163a59b`

Algorithm	Hash digest
SHA256	`925f146fd5f8ced4ad71fd658fed090852c18494315b153f1c66627e34b46b77`
MD5	`6eea2579b60883574fceda9c592f8bcf`
BLAKE2b-256	`119361f189155990336c71477346e665e6470ccc24407637e92f5df290cb3aa3`

Algorithm	Hash digest
SHA256	`43547a658f6094be2cea88614f95cc6be3ced1c1bc2572fd6ccf8f40fb1b88fd`
MD5	`3e076538477c8a17524e88ede15bc2e7`
BLAKE2b-256	`a14650d653384c4e2b49f26b2847b0171a40565667254be1ce31396ae15cb629`

Algorithm	Hash digest
SHA256	`1e5c6f35d9326200bb553cadc6c23e1725edaa9f5e2ab2bb8f603e0dea68c2e8`
MD5	`83db4bdeeeb8885029d5b36241d24c12`
BLAKE2b-256	`90ad751f727434e5eef7764f3487cf5d6e2a65180e25bb15301076843f9391a0`

Algorithm	Hash digest
SHA256	`9210a02f666904b1a3c786ee150f884cbef85aa70d3decaf596b47f3462405fc`
MD5	`4db8756f65def4ce28b979f0187aa635`
BLAKE2b-256	`19bc5e0f70ef079b5d27aeb732aebba952dadbb5376ba2b89b7a96786249b060`

Algorithm	Hash digest
SHA256	`1d628da24fe38751c7748cb3a619ab6ddd37d391ef6fc1eb429136b16ae8bf39`
MD5	`54a72a9d9b694d34651e39b421ccc871`
BLAKE2b-256	`731c40f4910d6ae466fc2d3ad0d91c8cc4ceaf5e3b619b7e1b8a87eee03f9933`

Algorithm	Hash digest
SHA256	`026300b9e1eaa9eceae33104e5bfc8dd6a66662baca178d12c91dd9f8e78e019`
MD5	`d845c819a4f72ba632f16ed4f2346ee0`
BLAKE2b-256	`f5823d014d35a66bb4c1d49d4d01eefec35f073c89c426b66bd049455757929e`

Algorithm	Hash digest
SHA256	`4ad6426b4a41acf10ae61d32d7151907d65259606aa1a0c553e0193055949b69`
MD5	`a5afe96141b578657a3f112f004ab9f3`
BLAKE2b-256	`5f0e9e7f8066ee722c1d0b92ed0f772a1b82284fc118e821455c3f4de172cd43`

Algorithm	Hash digest
SHA256	`656de3452c91d94f5faf0c12ae8d1e827f74f0fea6ac8b361f71d3c865c3fae9`
MD5	`d272a132ef38ec75ee5b85da75b45f9a`
BLAKE2b-256	`2ceb44c43abfc987cbc148eb33752b706593c2afd90f2aa4f9c214946faac1c2`

Algorithm	Hash digest
SHA256	`95713bba07d09d355b60069c437bfedc6ba9d216a45c05957da8590412102e8f`
MD5	`6f48169da958e11d8521b03f9fade8ed`
BLAKE2b-256	`d6c7185af44a40e83a9d3f61caad0a7493c7b89d7f47b1a896bae3a5eae79268`

Algorithm	Hash digest
SHA256	`05d416d0b65dd72af341d1472a427258723fc3366d6af292c481e1b0220a7869`
MD5	`48324b004817c485cc5fd11692c93a64`
BLAKE2b-256	`efc0bf18d3d0fa4c9a6b53141005a7eadf3bdaac6ca740ec26befb9fbf3c5506`

Algorithm	Hash digest
SHA256	`8690ea24ac5150be61db75d0e20bb61d095e453fef9f9ae74d429f4780a88989`
MD5	`d64be519a3637501f6722ee680b1b70e`
BLAKE2b-256	`e70041492cd5dfea1a0928cb901e4228e5740647606dd6e83a85a31190b05396`

Algorithm	Hash digest
SHA256	`788f6e3916e1fc360712fd1a0031ae3d1ba7b5def1884732725f96652cdb9654`
MD5	`b41786ffafe6bd1d60263f5837378ba7`
BLAKE2b-256	`ca8fde34eed49408618db325596a36d92d0b94fab5338e77c7bfa6e82d63f047`

Algorithm	Hash digest
SHA256	`e92bf384eae21591d88a43feb2844dfa2c4f8eb27352c6b1a161dc7e3f1f61b3`
MD5	`658db9e89cbb00952e6442b7ba3dfdea`
BLAKE2b-256	`aaada24cf64814aff1c9778d148fccde799621eb340cda8ca67699dfeb854f75`

pyrs-yaml 0.12.1

pyrs-yaml

Features

Installation

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

File hashes