ruyaml YAML Parser

Warnings

• breaking 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.
  Fix: Change `pip install ruamel.yaml` to `pip install ruyaml` and `from ruamel.yaml import ...` to `from ruyaml import ...`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install ruyaml Install ruyaml

Imports

• YAML

  from ruyaml import YAML

  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.

Quickstart

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.

from ruyaml import YAML
from io import StringIO

# Initialize a YAML instance for round-trip parsing
yaml = YAML()

# Example YAML data with comments and specific ordering
data = """
# User Configuration
name: John Doe
age: 30 # Current age
cities:
  - New York
  - London
options: {enabled: true, max_retries: 5}
"""

# Load YAML data from a string
stream = StringIO(data)
cfg = yaml.load(stream)

# Modify data - comments and structure are preserved
cfg['age'] = 31
cfg['cities'].append('Paris')
cfg['options']['timeout'] = 30 # Adding a new key

# Dump the modified YAML data back to a string, preserving original formatting
output_stream = StringIO()
yaml.dump(cfg, output_stream)

print(output_stream.getvalue())
# Expected output will include comments and maintain much of the original layout.