RapidYAML

Common errors

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

  cause 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

  cause 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

  cause 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.

Warnings

• gotcha RapidYAML'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.
• gotcha When 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')`.
• breaking As 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)`.
• gotcha RapidYAML'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()`.

Install

• pip install rapidyaml Install stable release

Imports

• ryml
  wrong:

  from rapidyaml import *

  correct:

  import ryml

  The primary interface is typically imported as 'ryml'.

Quickstart

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)