{"id":8578,"library":"rapidyaml","title":"RapidYAML","description":"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.","status":"active","version":"0.11.1","language":"en","source_language":"en","source_url":"https://github.com/biojppm/rapidyaml-python","tags":["yaml","parser","serialization","high-performance","c++-wrapper","low-level"],"install":[{"cmd":"pip install rapidyaml","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"note":"The primary interface is typically imported as 'ryml'.","wrong":"from rapidyaml import *","symbol":"ryml","correct":"import ryml"}],"quickstart":{"code":"import ryml\n\nyaml_bytes = b\"\"\"\nfoo: bar\nlist:\n  - item1\n  - item2\n\"\"\"\n\ntree = ryml.parse(yaml_bytes)\n\nroot_id = tree.root_id()\nprint(f\"Root ID: {root_id}\")\n\n# Accessing 'foo: bar'\nfoo_id = tree.find_child(root_id, b\"foo\")\nif foo_id != ryml.NONE:\n    print(f\"Key: {tree.key(foo_id).decode()}, Value: {tree.val(foo_id).decode()}\")\n\n# Accessing 'list'\nlist_id = tree.find_child(root_id, b\"list\")\nif list_id != ryml.NONE and tree.is_seq(list_id):\n    print(f\"List items:\")\n    child_id = tree.first_child(list_id)\n    while child_id != ryml.NONE:\n        print(f\"  - {tree.val(child_id).decode()}\")\n        child_id = tree.next_sibling(child_id)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that any YAML string passed to `ryml.parse()` is first encoded to bytes, typically `your_string.encode('utf-8')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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)`.","message":"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)`.","severity":"breaking","affected_versions":"0.10.0 and later"},{"fix":"When dealing with JSON-like input, ensure it conforms to standard YAML or remove explicit quotes around keys if parsing with `ryml.parse()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Encode the input string to bytes before parsing, e.g., `ryml.parse(my_string.encode('utf-8'))`.","cause":"Attempting to parse a standard Python string instead of a byte string.","error":"TypeError: parse() argument 'buf' must be bytes, not str"},{"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.","cause":"Incorrectly traversing the index-based tree, or attempting to access a non-existent child/sibling.","error":"Node not found or invalid node ID"},{"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.","cause":"Misunderstanding that `ryml.parse()` returns a low-level tree object, not a native Python data structure.","error":"Expected a dict or list, got a Tree object"}]}