aspy-yaml

Common errors

• ImportError: No module named aspy.yaml

  cause The `aspy.yaml` package is not installed in the current Python environment, or there's an issue with the Python path preventing it from being found.
  fix Ensure `aspy.yaml` is installed for the correct Python interpreter: `pip install aspy.yaml`. If using virtual environments, activate the correct environment before installation and running the script.

• Dictionary order is not preserved after loading YAML.

  cause This issue occurs if you are using `yaml.load` (from the base PyYAML library) instead of `aspy.yaml.ordered_load`. Standard Python dictionaries prior to 3.7 do not guarantee insertion order, and `PyYAML`'s default loader does not enforce it.
  fix Replace calls to `yaml.load` with `from aspy.yaml import ordered_load` and then use `ordered_load(yaml_string)`.

• yaml.scanner.ScannerError: while scanning for the next token

  cause This error typically indicates a syntax issue in your YAML file, such as incorrect indentation, unclosed quotes, or illegal characters.
  fix Carefully review the YAML content, paying close attention to indentation, proper quoting of strings (especially those containing special characters or starting with numbers/keywords), and correct formatting of lists and dictionaries. Use an online YAML validator or an IDE with YAML linting to pinpoint the exact error.

Warnings

• breaking Direct use of `yaml.load` (from the underlying PyYAML library) is unsafe when parsing untrusted YAML data, as it can lead to arbitrary code execution. `aspy-yaml`'s `ordered_load` is built upon PyYAML's loading mechanisms and inherits this behavior.
  Fix: Always use `yaml.safe_load` from PyYAML, or ensure the input source for `aspy.yaml.ordered_load` is trusted. If `ordered_load` is strictly needed, sanitize or validate input rigorously before loading.
• gotcha aspy-yaml, through PyYAML, primarily adheres to the YAML 1.1 specification. This can lead to unexpected parsing results for certain values, such as 'yes', 'no', 'on', 'off' being parsed as booleans, or octal numbers requiring a '0o' prefix in YAML 1.2 but being interpreted differently in 1.1.
  Fix: When authoring YAML, explicitly quote scalar values that might be misinterpreted (e.g., 'yes', 'no', '010'). For stricter YAML 1.2 compliance, consider `ruamel.yaml` as an alternative.
• gotcha YAML's indentation-sensitive syntax is a frequent source of errors. Incorrect spacing can lead to `ParserError` or misinterpretation of the document structure, which is common across all YAML parsers, including aspy-yaml.
  Fix: Use a linter or an IDE with YAML syntax checking. Ensure consistent use of spaces (not tabs) for indentation. Start new blocks with increased indentation and maintain the same level within a block.

Install

• pip install aspy.yaml Install with pip

Imports

• ordered_load
  wrong:

  import aspy.yaml.ordered_load

  correct:

  from aspy.yaml import ordered_load

  The function is directly available from the aspy.yaml package, not a submodule named 'ordered_load'.
• ordered_dump
  wrong:

  import aspy.yaml.ordered_dump

  correct:

  from aspy.yaml import ordered_dump

  Similar to ordered_load, dump is a direct export.

Quickstart

This quickstart demonstrates how to use `ordered_load` to parse a YAML string into a Python object, ensuring that dictionary keys maintain their original order. It then shows how to use `ordered_dump` to serialize a Python object back into a YAML string, again preserving the order of keys. This is particularly useful for configuration files where order matters or for consistent output.

from aspy.yaml import ordered_load, ordered_dump

yaml_str = '''
key1: value1
key2: value2
list_key:
  - itemA
  - itemB
'''

# Load YAML while preserving dictionary order
data = ordered_load(yaml_str)
print(f"Loaded data (order preserved): {data}")

# Verify order
assert list(data.keys()) == ['key1', 'key2', 'list_key']

# Modify data and dump it back, preserving order
data['new_key'] = 'new_value'
output_yaml = ordered_dump(data)
print(f"\nDumped YAML (order preserved):\n{output_yaml}")