codemod-yaml

What it is and what it does

codemod-yaml is a library for making targeted edits to YAML files while preserving formatting. It uses tree-sitter to parse YAML and allows you to modify document structure programmatically, then write the result back with minimal changes to whitespace and layout on unmodified lines. This makes it suitable for automation tools and codemods that need to update YAML configuration files without introducing unnecessary formatting noise into version control diffs.

The library is inspired by tomlkit and pyupgrade, adopting their philosophy of format-preserving edits. It exposes a simple API where you parse a YAML file into a stream object, modify its contents like a Python dict, and serialize it back to bytes. The main constraint is Python version support: runtime usage works back to 3.9, but development and full mypy compatibility require 3.10-3.12.

Use it for:

• Update version strings in CI/CD configuration files while keeping formatting intact for minimal git diffs.
• Automate bulk changes to Kubernetes manifests or Helm values without reformatting the entire document.
• Build codemods that modify application configuration YAML files as part of refactoring or migration workflows.
• Programmatically edit Docker Compose or other YAML-based infrastructure-as-code files with surgical precision.

Worth the install?

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

Modifies YAML documents in place with surgical precision, preserving all whitespace and formatting on unchanged lines to produce minimal diffs.

Yes. The package solves a real problem—format-preserving YAML edits—with low install friction, active maintenance, permissive licensing, and no known vulnerabilities. It is well-suited for automation and codemod tools where minimal diffs matter. The narrow Python version window for development is not a blocker for runtime use.

Install

codemod-yaml on PyPI

pip install codemod-yaml

uv add codemod-yaml

poetry add codemod-yaml

Installing codemod-yaml

Before you install

Low friction installation with only two runtime dependencies (tree-sitter and tree-sitter-yaml). Actively maintained with recent releases; last commit 2026-05-12. Requires Python 3.9+, though development and full linting support is limited to 3.10-3.12.

License in practice

MIT license permits commercial and private use with minimal restrictions; you must include a copy of the license and copyright notice.

Quickstart

from codemod_yaml import parse
stream = parse(somepath.read_bytes())
if stream["version"] == ["2.7"]:
    stream["version"][:] = ["3.6", "3.13"]
somepath.write_bytes(stream.text)

Requires Python 3.9+; tree-sitter and tree-sitter-yaml must be installed and available.

Verify before relying

• Whether tree-sitter-yaml is automatically installed or must be installed separately as a system dependency.
• Performance characteristics and scalability limits for large or deeply nested YAML documents.

Package facts

Evidence: codemod_yaml-0.7.0-py3-none-any.whl

Tags

More Markup packages