ruamel-yaml-clib

0.2.15 · active · verified Sat Mar 28

ruamel-yaml-clib is a C-based reader, parser, and emitter for the ruamel.yaml library, derived from libyaml. It enhances the performance of ruamel.yaml by providing C extensions for core YAML processing operations. This package was split from ruamel.yaml to facilitate the creation of universal wheels and streamline platform-specific compilation. The current version is 0.2.15.

Warnings

breaking Starting with `ruamel.yaml` version 0.19.1, the library no longer automatically installs `ruamel-yaml-clib` as a direct dependency. To ensure the C-accelerated backend is installed, users must explicitly install `ruamel.yaml` with the `libyaml` extra, e.g., `pip install ruamel.yaml[libyaml]`.
Fix: Install `ruamel.yaml` with the `libyaml` extra: `pip install ruamel.yaml[libyaml]`. If `ruamel-yaml-clib` is installed directly, `ruamel.yaml` will still detect and use it.
gotcha Compilation issues may occur with newer `clang` versions (e.g., >= 16) when building `ruamel-yaml-clib` from source. This typically manifests in environments like FreeBSD where `clang` is the default compiler.
Fix: Workarounds may involve patching the source code or using an older/different compiler toolchain. Refer to `ruamel.yaml.clib` issue trackers or community discussions for specific patches.
gotcha When `ruamel-yaml-clib` is active (using the C-based SafeLoader/SafeDumper within `ruamel.yaml`), the `yaml.indent` setting applies uniformly to both mappings and sequences. The pure Python implementation of `ruamel.yaml` offers more granular control over indentation styles.
Fix: If different indentation settings for mappings and sequences are required, instantiate `ruamel.yaml.YAML(pure=True)` to force the pure Python implementation.
deprecated The maintainer has indicated that `ruamel.yaml.clib` will not receive fixes for free-threading issues. `ruamel.yaml.clibz` is the designated replacement for future free-threading support. While `ruamel.yaml.clib` remains functional, this signals a future transition.
Fix: For applications requiring free-threading support with `ruamel.yaml`'s C backend in the future, monitor `ruamel.yaml`'s documentation for guidance on adopting `ruamel.yaml.clibz`.

Install

pip install ruamel-yaml-clib Install latest version

Imports

YAML
```
from ruamel.yaml import YAML
```
ruamel-yaml-clib is a backend for ruamel.yaml and is not imported directly by user code. ruamel.yaml detects and utilizes ruamel-yaml-clib automatically if installed, unless pure Python parsing is explicitly requested (e.g., YAML(pure=True)).

Quickstart

This quickstart demonstrates basic loading and dumping of YAML using `ruamel.yaml`. If `ruamel-yaml-clib` is installed, `ruamel.yaml` will use its C extensions for improved performance without requiring any changes to user code. To explicitly use the pure Python implementation, instantiate `YAML(pure=True)`.

import sys
from ruamel.yaml import YAML

# ruamel.yaml will automatically use ruamel-yaml-clib if available
# For pure Python implementation, use: yaml = YAML(pure=True)
yaml = YAML()

data = {
    'name': 'Alice',
    'age': 30,
    'details': {
        'city': 'New York',
        'occupation': 'Engineer'
    }
}

# Dump to string
import io
string_stream = io.StringIO()
yaml.dump(data, string_stream)
yaml_string = string_stream.getvalue()
print('--- Dumped YAML ---')
print(yaml_string)

# Load from string
loaded_data = yaml.load(yaml_string)
print('--- Loaded Data ---')
print(loaded_data['name'])
print(loaded_data['details']['city'])

# Demonstrate round-trip preservation (if ruamel.yaml is configured for it)
config_yaml_str = """
# My config
key: value # inline comment
list:
  - item1
  - item2
"""

rt_yaml = YAML()
rt_data = rt_yaml.load(config_yaml_str)
rt_data['list'].append('item3')

output_stream = io.StringIO()
rt_yaml.dump(rt_data, output_stream)
print('--- Round-trip preserved ---')
print(output_stream.getvalue())

view raw JSON →