# YAMLRocks

> YAMLRocks is a fast, correct YAML library for Python, implemented in Rust with PyO3. It is safe by default (tags never construct arbitrary objects), defaults to the YAML 1.2 core schema, reads and writes bytes without an extra encode step, and adds a comment-preserving round-trip mode, native `!include` resolution, JSON Schema validation, and source-tracked annotated mode.

Important notes for working with YAMLRocks:

- Install with `pip install yamlrocks`; the import name is `yamlrocks`. Prebuilt wheels ship for CPython (including free-threaded builds); no C toolchain is needed.
- The core API is `loads`/`load` (parse), `dumps`/`dump` (serialize), `to_json` (JSON output), and the `loads_all`/`load_all` multi-document variants. `async_loads`/`async_load`/`async_load_all` run the parse off the event loop.
- `loads` takes and `dumps` returns `bytes` (a `str` is also accepted on input). There is no `yamlrocks.load` that executes code; the safe behavior is the only behavior.
- Behavior is controlled by `option=` flags combined with `|`, such as `OPT_ROUND_TRIP`, `OPT_INCLUDES`, `OPT_SECRETS`, `OPT_ENV_VAR`, `OPT_ANNOTATED`, `OPT_YAML_1_1`, `OPT_SORT_KEYS`, and the `OPT_INDENT_2`/`OPT_INDENT_4` pair.
- Round-trip mode returns a `YAMLRocksDocument`: edit it like a `dict`/`list`, then `to_yaml()` re-emits with comments and layout intact, byte-for-byte for an unmodified document.
- For a near drop-in migration from PyYAML, `import yamlrocks.compat as yaml` exposes `safe_load`/`safe_dump` and friends returning `str` like PyYAML.

## Documentation Sets

- [Abridged documentation](https://yaml.rocks/llms-small.txt): a compact version of the documentation for YAMLRocks, with non-essential content removed
- [Complete documentation](https://yaml.rocks/llms-full.txt): the full documentation for YAMLRocks
- [Guides and recipes](https://yaml.rocks/_llms-txt/guides-and-recipes.txt): Task-oriented documentation: loading, dumping, JSON, round-trip editing, includes, annotated mode, schema validation, custom tags, and worked recipes.
- [API reference](https://yaml.rocks/_llms-txt/api-reference.txt): The full function and option reference, exceptions, the security model, and migration guides.

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation