rapidyaml

library0.15.0pypypi✓ verified 87d ago

RapidYAML (ryml) is a Python wrapper for a fast C++ library designed to parse and emit YAML. It focuses on performance by exposing a low-level, index-based C++ API that operates with node indices and string views, rather than automatically building Python dict/list structures. The current version is 0.11.1, and it maintains an active release cadence.

serialization

pip install rapidyaml

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RAPIDYAML

rapidyaml

serializationpythonv0.15.0

Install

1.8s avg

Import

36ms

Disk

19MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.15.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

build_error

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.8s · import 0.036s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ryml

✓ import ryml

✗ from rapidyaml import *

The primary interface is typically imported as 'ryml'.

This quickstart demonstrates parsing a YAML byte string and traversing the resulting tree using RapidYAML's low-level, index-based API. It shows how to find child nodes by key and iterate through sequence items, decoding byte strings to Python strings for output.

import ryml yaml_bytes = b""" foo: bar list: - item1 - item2 """ tree = ryml.parse(yaml_bytes) root_id = tree.root_id() print(f"Root ID: {root_id}") # Accessing 'foo: bar' foo_id = tree.find_child(root_id, b"foo") if foo_id != ryml.NONE: print(f"Key: {tree.key(foo_id).decode()}, Value: {tree.val(foo_id).decode()}") # Accessing 'list' list_id = tree.find_child(root_id, b"list") if list_id != ryml.NONE and tree.is_seq(list_id): print(f"List items:") child_id = tree.first_child(list_id) while child_id != ryml.NONE: print(f" - {tree.val(child_id).decode()}") child_id = tree.next_sibling(child_id)

Debug

Known issues

gotchaRapidYAML's Python wrapper exposes a low-level C++ API. It does not automatically convert YAML structures into native Python dictionaries or lists. Users must explicitly traverse the tree using node indices and extract values, which are typically returned as `memoryview` objects of bytes.

fix

Be prepared to iterate through the tree structure manually using methods like `root_id()`, `first_child()`, `next_sibling()`, `key()`, `val()`, and `is_map()`, `is_seq()`. Decode byte strings (e.g., `.decode('utf-8')`) when Python strings are needed.

affects: All versions

gotchaWhen parsing, RapidYAML requires input to be `bytes` or `bytearray` objects, not Python `str` objects. This is because the underlying C++ library does not take ownership of the source buffer.

fix

Ensure that any YAML string passed to `ryml.parse()` is first encoded to bytes, typically `your_string.encode('utf-8')`.

affects: All versions

breakingAs of RapidYAML 0.11.1 (and some earlier C++ changes), a default-constructed `ryml.Tree` is no longer empty by default. `Tree::root_id()` will not modify an empty tree to create a root. To create an explicitly empty tree, use `ryml.Tree(0)`.

fix

If you need an empty tree that behaves like older versions (i.e., `root_id()` creates the root), ensure you initialize it with `tree = ryml.Tree()` if that is the intended behavior in the Python wrapper. If you explicitly need an empty tree, initialize with `ryml.Tree(0)`.

affects: 0.10.0 and later

gotchaRapidYAML's C++ core is strict about JSON parsing. Attempting to parse JSON with explicitly quoted keys (e.g., `{"a":"b"}`) might result in parse errors, as it expects more 'relaxed' JSON or standard YAML.

fix

When dealing with JSON-like input, ensure it conforms to standard YAML or remove explicit quotes around keys if parsing with `ryml.parse()`.

affects: All versions

Errors

Common errors & fixes

TypeError: parse() argument 'buf' must be bytes, not str

Attempting to parse a standard Python string instead of a byte string.

fix

Encode the input string to bytes before parsing, e.g., `ryml.parse(my_string.encode('utf-8'))`.

Node not found or invalid node ID

Incorrectly traversing the index-based tree, or attempting to access a non-existent child/sibling.

fix

Always check the return value of tree traversal methods (e.g., `find_child`, `first_child`, `next_sibling`) against `ryml.NONE` before attempting to use the returned ID.

Expected a dict or list, got a Tree object

Misunderstanding that `ryml.parse()` returns a low-level tree object, not a native Python data structure.

fix

Manually iterate the `ryml.Tree` object using its index-based API to construct Python dictionaries and lists if required. For example, check `tree.is_map(node_id)` or `tree.is_seq(node_id)` to determine the YAML type.

Upgrade

Version history

0.15.0latest on PyPI · released Jun 8, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/biojppm/rapidyaml-python ↗

packagehttps://pypi.org/project/rapidyaml/ ↗

homepagehttps://biicode.github.io/rapidyaml/ ↗