saneyaml

What it is and what it does

saneyaml is a thin wrapper around PyYAML designed to make YAML parsing and generation more predictable for typical configuration-file use cases. It addresses two common pain points: unwanted type inference (converting strings like '3.0.0' into floats or booleans) and loss of key order. By default, saneyaml loads everything except booleans as strings, preserves insertion order in dictionaries, and can optionally detect duplicate map keys—all while producing clean, readable YAML output when dumping.

The library is intended for developers who need reliable, unsurprising YAML handling in configuration workflows. It trades some of PyYAML's automatic type conversion for predictability, making it especially useful when you want version strings, IDs, and other numeric-looking values to remain strings unless explicitly converted.

Use it for:

• Parse configuration files where numeric-looking strings (versions, IDs) must stay strings and not convert to numbers.
• Generate human-readable YAML output from Python dicts while maintaining consistent formatting and key order.
• Detect and report duplicate keys in YAML maps to catch configuration errors early.
• Load YAML safely in build or deployment tools where type surprises could cause silent failures.
• Preserve the order of configuration keys when round-tripping YAML through Python.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A lightweight PyYAML wrapper that reads and writes YAML safely with predictable behavior, loading everything except booleans as strings and preserving key order.

Yes, if you need predictable YAML handling for configuration files and want to avoid PyYAML's automatic type conversions. The single dependency, permissive license, and low install friction make it a lightweight addition. Maintenance is aging (last release 2024-08-14, no updates in over 730 days), but the repository is active and there are no known security vulnerabilities. Suitable for stable, non-evolving use cases; monitor the repo if you need ongoing feature development.

Install

saneyaml on PyPI

pip install saneyaml

uv add saneyaml

poetry add saneyaml

Installing saneyaml

Before you install

Low install friction with a single runtime dependency (PyYAML). Maintenance status is aging—last commit was 2025-03-30 and the latest release was 2024-08-14, over 730 days ago—but the repository remains active and unarchived.

License in practice

Licensed under Apache-2.0 (permissive), so you can use it freely in commercial and private projects without copyleft obligations.

Quickstart

pip install saneyaml

from saneyaml import load, dump

yaml_text = '''version: 3.0.0
description: Example config'''
data = load(yaml_text)
output = dump(data)
print(output)

Requires PyYAML 5.x or higher and Python 3.7+.

Verify before relying

• Whether duplicate key detection is enabled by default or requires explicit configuration.
• Performance characteristics when handling large YAML files compared to raw PyYAML.
• Scope of 'sane behavior' differences from PyYAML beyond type conversion and ordering.

Package facts

Evidence: saneyaml-0.6.1-py3-none-any.whl

Keywords: utilities, yaml, pyyaml, block, flow

Tags

More Software Development packages