Yamlfix

Warnings

• gotcha Yamlfix can sometimes inadvertently alter the structure or quoting of certain YAML constructs, particularly multi-line strings, volumes definitions (e.g., in Docker Compose), or long keys, leading to functional changes if not carefully reviewed.
  Fix: Always review changes made by `yamlfix` using version control (e.g., `git diff`) before committing. Consider using `--check` flag or `fix_code` with manual comparison for critical files. Report unexpected behavior to the project's GitHub issues. Explicitly configure quoting behavior if specific styles are required (e.g., `preserve_quotes`, `quote_basic_values`).
• gotcha The tool might move YAML 'shebangs' (e.g., `#!/usr/bin/env yaml`) to the left or introduce unexpected header separators (`---`) even if the file is correctly formed without one, which might break scripts relying on specific file content or existing YAML standards.
  Fix: If a file should not have a `---` header or a shebang needs to remain at a specific position, verify `yamlfix`'s behavior and consider excluding such files or configuring `explicit_document_start` if available. For shebangs, manual intervention or a pre-commit hook specifically for shebangs might be necessary. Check the `explicit_document_start` configuration option.
• gotcha Configuration via `pyproject.toml`, `.yamlfix.toml`, or environment variables is powerful but can be overridden by conflicting settings, and values are parsed by Pydantic, which enforces type. Providing a value with the wrong type (e.g., a string for a boolean) will result in errors.
  Fix: Ensure configuration keys and their types strictly match those defined in the `YamlfixConfig` class. When using environment variables, be mindful that all values are initially strings and Pydantic will attempt to cast them to the expected type (e.g., 'true'/'false' to boolean, numeric strings to int/float). Consult the official documentation for available configuration options and their expected types.

Install

• pip install yamlfix Install with pip

Imports

• fix_files

  from yamlfix import fix_files

  For fixing multiple YAML files programmatically.
• fix_code

  from yamlfix import fix_code

  For fixing YAML content passed as a string.

Quickstart

This quickstart demonstrates how to use `yamlfix` both as a command-line tool (simulated) and programmatically using `fix_files` to modify a file in place, and `fix_code` to format a YAML string. It highlights how the tool corrects common formatting inconsistencies like indentation, missing document headers, and list styling.

import os
import stat
from yamlfix import fix_files, fix_code

# --- CLI Usage Example ---
# Create a malformed YAML file
malformed_cli_yaml = """
key: value
  another_key:    nested_value
- item1
-    item2
"""

with open("malformed.yaml", "w") as f:
    f.write(malformed_cli_yaml)

# Run yamlfix via CLI (simulate for quickstart)
# In a real scenario, you would run: !yamlfix malformed.yaml
print("\n--- CLI (Simulated) ---")
print("Original malformed.yaml:")
with open("malformed.yaml", "r") as f:
    print(f.read())

# Simulate fixing by reading, fixing with fix_code, and writing back
fixed_content_cli = fix_code(malformed_cli_yaml)
with open("malformed.yaml", "w") as f:
    f.write(fixed_content_cli)

print("Fixed malformed.yaml:")
with open("malformed.yaml", "r") as f:
    print(f.read())

# --- Programmatic Usage Example (fix_files) ---
# Create another malformed YAML file
malformed_file_yaml = """
list:
- item_a
  - item_b
  # A comment
  -item_c
"""

with open("another_malformed.yml", "w") as f:
    f.write(malformed_file_yaml)

print("\n--- Programmatic (fix_files) ---")
print("Original another_malformed.yml:")
with open("another_malformed.yml", "r") as f:
    print(f.read())

# Fix the file(s) programmatically
fix_files(["another_malformed.yml"])

print("Fixed another_malformed.yml:")
with open("another_malformed.yml", "r") as f:
    print(f.read())

# --- Programmatic Usage Example (fix_code) ---
print("\n--- Programmatic (fix_code) ---")
code_to_fix = """
  key1:  value1
key2: value2
"""
print("Original code string:\n" + code_to_fix)
fixed_code_string = fix_code(code_to_fix)
print("Fixed code string:\n" + fixed_code_string)

# Cleanup generated files
os.remove("malformed.yaml")
os.remove("another_malformed.yml")