Ordered YAML (oyaml)

1.1 · active · verified Sat Apr 11

oyaml is a drop-in replacement for PyYAML designed to preserve dictionary ordering during YAML loading and dumping. It supports both Python 2 and Python 3 by patching the underlying PyYAML library. The current version is 1.1, with releases occurring infrequently, primarily for compatibility updates with newer PyYAML versions or test suite improvements.

Warnings

gotcha For Python 3.7 and later, standard dictionaries (`dict`) inherently preserve insertion order. This reduces the primary benefit of `oyaml` for these Python versions when working with standard `dict`s, though `oyaml` still ensures `OrderedDict`s are used or order is strictly maintained across all operations and Python versions.
Fix: Consider if `oyaml` is truly necessary for new code on Python 3.7+, or if direct `PyYAML` usage with `sort_keys=False` for dumping (if order matters for output) is sufficient. For cross-version compatibility or explicit `OrderedDict` requirements, `oyaml` remains useful.
breaking In `oyaml` v0.8, the behavior for `FullLoader` in CPython 3.6+ was changed to deserialize YAML maps into a standard Python `dict` instead of `collections.OrderedDict`. If your application relied on `FullLoader` returning `OrderedDict` on CPython 3.6+ specifically, this change is breaking.
Fix: Explicitly cast the loaded dictionary to `OrderedDict` if the specific type is required, or ensure your code is robust to handling either `dict` or `OrderedDict` from `FullLoader`.
gotcha Like PyYAML, it is unsafe to use `yaml.load()` with untrusted input due to the potential for arbitrary code execution. Always prefer `yaml.safe_load()` for security.
Fix: Replace all instances of `yaml.load()` with `yaml.safe_load()` when processing input from untrusted sources.

Install

pip install oyaml Install oyaml

Imports

yaml
```
import oyaml as yaml
```
oyaml is intended as a drop-in replacement. Aliasing it as 'yaml' ensures that code expecting PyYAML's interface benefits from oyaml's order-preserving features without modifications. Importing `yaml` directly would use PyYAML, not oyaml.

Quickstart

This quickstart demonstrates how to import oyaml as `yaml` and use its `safe_load` and `safe_dump` functions. It shows that `oyaml` preserves the order of keys when loading from a YAML string and when dumping an `OrderedDict` to a YAML string, by default, if `sort_keys=False` is used for `safe_dump` with standard dictionaries. For Python versions < 3.7, `safe_load` will return `OrderedDict` instances. For Python 3.7+ with standard `dict`s, while `safe_load` might return a standard `dict`, its order is insertion-ordered.

import oyaml as yaml
from collections import OrderedDict

yaml_data = """
key_c: 3
key_a: 1
key_b: 2
"""

# Load YAML preserving order
loaded_dict = yaml.safe_load(yaml_data)
print(f"Loaded dictionary type: {type(loaded_dict)}")
print(f"Loaded dictionary keys order: {list(loaded_dict.keys())}")

# Dump a dictionary with explicit order
ordered_data = OrderedDict([
    ('first_key', 'value_1'),
    ('second_key', 'value_2'),
    ('third_key', 'value_3')
])
dumped_yaml = yaml.safe_dump(ordered_data, sort_keys=False)
print(f"\nDumped YAML with order preserved:\n{dumped_yaml}")

view raw JSON →