Ordered YAML Loader and Dumper

Common errors

• ModuleNotFoundError: No module named 'yaml'

  cause The underlying PyYAML library, which `yamlloader` depends on, is not installed.
  fix Install PyYAML: `pip install pyyaml` (or simply `pip install yamlloader` which should pull in PyYAML as a dependency).

• YAMLLoadWarning: calling yaml.load() without Loader=... is deprecated, as the default Loader is unsafe. Please read https://pyyaml.readthedocs.io/en/latest/api.html#yamllib-org-api

  cause You are calling PyYAML's `yaml.load()` function without explicitly specifying a `Loader` class. This warning is from PyYAML itself, which `yamlloader` uses.
  fix Always provide a `Loader` argument. For `yamlloader`'s ordered loading, use `yaml.load(file_obj, Loader=yamlloader.ordereddict.CLoader)`. For general safe loading, use `yaml.safe_load(file_obj)` or `yaml.load(file_obj, Loader=yaml.SafeLoader)`.

• MemoryError: cannot allocate vector of size ...

  cause Attempting to load a very large YAML file (e.g., several gigabytes) into memory at once, potentially exceeding available RAM.
  fix For extremely large YAML files, consider processing them in chunks if the structure allows, or using alternative streaming parsers not offered by `yamlloader`/`PyYAML`. Ensure your system has sufficient RAM for the file size.

• yaml.scanner.ScannerError: while scanning for the next token found character '\t' that cannot start any token in "<string>", line X, column Y

  cause YAML syntax is very strict about indentation. This error typically means you've used a tab character for indentation where spaces are required, or there's an inconsistent mix of tabs and spaces.
  fix Replace all tab characters with spaces for indentation in your YAML file. Many text editors have 'convert tabs to spaces' functionality. Ensure consistent indentation levels (e.g., always 2 or 4 spaces).

Warnings

• breaking Support for Python 3.7 was dropped in `yamlloader` version 1.3.2. Users on Python 3.7 must use `yamlloader` version 1.2 or older. Later versions require Python 3.8+.
  Fix: Upgrade Python to 3.8+ or pin `yamlloader` to `<1.3.0` for Python 3.7 environments.
• deprecated PyYAML's `yaml.load()` function without an explicit `Loader` argument (e.g., `yaml.load(file_obj)`) has been deprecated since PyYAML 5.1 due to security concerns, as it could lead to arbitrary code execution when processing untrusted YAML. While `yamlloader`'s examples always specify a Loader, users might accidentally revert to the insecure pattern.
  Fix: Always explicitly specify a loader when calling `yaml.load()`. For safe loading of untrusted input, use `yaml.safe_load()` or `yaml.load(file, Loader=yaml.SafeLoader)`. When using `yamlloader`, ensure you pass its specific loaders: `yaml.load(file, Loader=yamlloader.ordereddict.CLoader)` or `yaml.load(file, Loader=yamlloader.ordereddict.CSafeLoader)`.
• gotcha While `yamlloader` explicitly uses `OrderedDict` internally (and `dict` for Python 3.7+ as `dict` preserves insertion order), prior to `yamlloader 1.0.0`, it might have behaved differently with Python 3.7+ native `dict` ordering. Since `1.0.0`, it consistently returns `OrderedDict` or order-preserving `dict` for all supported Python versions.
  Fix: For consistent ordered dictionary behavior, ensure you are using `yamlloader` version `1.0.0` or newer. For Python 3.7+, standard `dict`s preserve insertion order, but explicit `OrderedDict`s or `yamlloader`'s wrappers provide a stronger guarantee and consistent API.
• gotcha yamlloader leverages PyYAML's C-bindings for performance (`CLoader`, `CDumper`). If PyYAML was installed without C extensions (e.g., missing `libyaml-dev` or `Cython`), these C-versions will automatically fall back to their pure Python equivalents. This fallback is usually seamless but can hide performance issues. You can disable this fallback by setting `yamlloader.settings.ALLOW_C_VERSION_FALLBACK = False` which will cause an error if C-versions are unavailable.
  Fix: To ensure C-version performance, install `libyaml-dev` (or equivalent for your OS) and `Cython` before installing PyYAML or `yamlloader`. Check `yaml.cyaml` exists in your environment to verify C-binding availability.

Install

• pip install yamlloader Install with pip

Imports

• yamlloader

  import yamlloader

  The main package import.
• CLoader
  wrong:

  from yamlloader import CLoader

  correct:

  from yamlloader.ordereddict import CLoader

  CLoader (and CDumper) are within the 'ordereddict' submodule. Using the C-versions is recommended for performance; they gracefully fall back to pure Python if C bindings are not compiled for PyYAML.
• CDumper

  from yamlloader.ordereddict import CDumper

  CDumper for dumping YAML while preserving order, with C-speed if available.
• yaml

  import yaml

  yamlloader builds on PyYAML, so the base PyYAML library is often imported alongside it.

Quickstart

This quickstart demonstrates how to load and dump YAML content using `yamlloader`'s `CLoader` and `CDumper` to ensure dictionary order is preserved. It highlights how `yaml.load` is used with the custom loader and how the order is maintained in the resulting Python object, even for standard dictionaries in Python 3.7+.

import yaml
from yamlloader.ordereddict import CLoader, CDumper
import os

yaml_content = """
key_a: value_1
key_b: value_2
key_c: value_3
list_items:
  - item1
  - item2
  - item3
"""

# Create a dummy YAML file
with open('config.yaml', 'w') as f:
    f.write(yaml_content)

# --- Loading YAML --- 
print('--- Loading YAML ---')
with open('config.yaml', 'r') as f:
    # Using CLoader to preserve order
    data = yaml.load(f, Loader=CLoader)

print(f"Loaded data type: {type(data)}")
print(f"Loaded data: {data}")

# Verify order preservation (Python 3.7+ dicts preserve insertion order by default,
# but yamlloader explicitly guarantees and was designed around OrderedDict behavior)
expected_keys = ['key_a', 'key_b', 'key_c', 'list_items']
actual_keys = list(data.keys())
print(f"Keys in order: {actual_keys == expected_keys}")

# --- Dumping YAML --- 
print('\n--- Dumping YAML ---')
modified_data = data
modified_data['new_key'] = 'new_value'

output_yaml = yaml.dump(modified_data, Dumper=CDumper, default_flow_style=False)
print(f"Dumped YAML:\n{output_yaml}")

# Clean up dummy file
os.remove('config.yaml')