{"id":4243,"library":"ruyaml","title":"ruyaml YAML Parser","description":"ruyaml is a fork of ruamel.yaml, a YAML parser and emitter for Python that aims to preserve comments, order, and other structural details during round-trip loading and dumping. It is actively maintained, with version 0.91.0 being the latest stable release, and receives updates periodically, often merging upstream changes from `ruamel.yaml`.","status":"active","version":"0.91.0","language":"en","source_language":"en","source_url":"https://github.com/pycontribs/ruyaml","tags":["yaml","parser","serialization","deserialization","config","roundtrip"],"install":[{"cmd":"pip install ruyaml","lang":"bash","label":"Install ruyaml"}],"dependencies":[],"imports":[{"note":"Prior to version 0.20.0, the library was named `ruamel.yaml` and imported as such. `ruyaml` is a distinct fork and requires its own import path.","wrong":"from ruamel.yaml import YAML","symbol":"YAML","correct":"from ruyaml import YAML"}],"quickstart":{"code":"from ruyaml import YAML\nfrom io import StringIO\n\n# Initialize a YAML instance for round-trip parsing\nyaml = YAML()\n\n# Example YAML data with comments and specific ordering\ndata = \"\"\"\n# User Configuration\nname: John Doe\nage: 30 # Current age\ncities:\n  - New York\n  - London\noptions: {enabled: true, max_retries: 5}\n\"\"\"\n\n# Load YAML data from a string\nstream = StringIO(data)\ncfg = yaml.load(stream)\n\n# Modify data - comments and structure are preserved\ncfg['age'] = 31\ncfg['cities'].append('Paris')\ncfg['options']['timeout'] = 30 # Adding a new key\n\n# Dump the modified YAML data back to a string, preserving original formatting\noutput_stream = StringIO()\nyaml.dump(cfg, output_stream)\n\nprint(output_stream.getvalue())\n# Expected output will include comments and maintain much of the original layout.","lang":"python","description":"This quickstart demonstrates how to load and dump YAML data while preserving comments, ordering, and block/flow styles using `ruyaml`'s default `YAML()` instance for round-trip parsing."},"warnings":[{"fix":"Change `pip install ruamel.yaml` to `pip install ruyaml` and `from ruamel.yaml import ...` to `from ruyaml import ...`.","message":"The package was renamed from `ruamel.yaml` to `ruyaml` starting with version 0.20.0. All import paths and installation commands must reflect this change.","severity":"breaking","affected_versions":"0.20.0 onwards"},{"fix":"If simpler loading/dumping is desired, explicitly specify `typ='safe'` or `typ='unsafe'`. For example: `yaml = YAML(typ='safe')`. Be aware this will lose round-trip preservation capabilities.","message":"By default, `ruyaml` uses a round-trip aware loader/dumper (`YAML()`) which preserves comments, ordering, and tag information. Users migrating from `PyYAML` might expect simpler type conversion or different default formatting.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To control string quoting, use `yaml.indent(mapping=X, sequence=Y, offset=Z)`. To force flow style for collections, use `yaml.default_flow_style = True` or explicitly set `yaml.Representer.add_representer` for custom types. For specific string issues, `yaml.scalar_string = True` might help.","message":"When dumping, `ruyaml` might automatically quote strings containing special characters or represent certain data structures (like dicts or lists) in block style by default, which can differ from `PyYAML`'s output or simple string representations.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}