{"id":7010,"library":"aspy-yaml","title":"aspy-yaml","description":"aspy-yaml is a Python library providing a few extensions to PyYAML, primarily focused on preserving dictionary order during YAML loading and dumping. It offers `ordered_load` and `ordered_dump` functions to maintain insertion order for mappings, which is not guaranteed by standard `yaml.load` in older Python versions. The library is currently at version 1.3.0, released in May 2019, and is maintained with a low release cadence.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/asottile/aspy.yaml","tags":["yaml","pyyaml","ordered-dict","configuration","serialization"],"install":[{"cmd":"pip install aspy.yaml","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core YAML parsing and dumping functionality is provided by PyYAML.","package":"pyyaml","optional":false},{"reason":"Used internally for ordered dictionaries on Python versions prior to 3.7 where dictionaries were not insertion-ordered by default.","package":"ordereddict","optional":true}],"imports":[{"note":"The function is directly available from the aspy.yaml package, not a submodule named 'ordered_load'.","wrong":"import aspy.yaml.ordered_load","symbol":"ordered_load","correct":"from aspy.yaml import ordered_load"},{"note":"Similar to ordered_load, dump is a direct export.","wrong":"import aspy.yaml.ordered_dump","symbol":"ordered_dump","correct":"from aspy.yaml import ordered_dump"}],"quickstart":{"code":"from aspy.yaml import ordered_load, ordered_dump\n\nyaml_str = '''\nkey1: value1\nkey2: value2\nlist_key:\n  - itemA\n  - itemB\n'''\n\n# Load YAML while preserving dictionary order\ndata = ordered_load(yaml_str)\nprint(f\"Loaded data (order preserved): {data}\")\n\n# Verify order\nassert list(data.keys()) == ['key1', 'key2', 'list_key']\n\n# Modify data and dump it back, preserving order\ndata['new_key'] = 'new_value'\noutput_yaml = ordered_dump(data)\nprint(f\"\\nDumped YAML (order preserved):\\n{output_yaml}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions of aspy-yaml and PyYAML"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of 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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ImportError: No module named aspy.yaml"},{"fix":"Replace calls to `yaml.load` with `from aspy.yaml import ordered_load` and then use `ordered_load(yaml_string)`.","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.","error":"Dictionary order is not preserved after loading YAML."},{"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.","cause":"This error typically indicates a syntax issue in your YAML file, such as incorrect indentation, unclosed quotes, or illegal characters.","error":"yaml.scanner.ScannerError: while scanning for the next token"}]}