文章目錄

  • 安裝
  • 基本使用
  • 1. 讀取 YAML
  • 2. 寫入 YAML
  • 3. 讀取 → 修改 → 保留格式寫回（典型用例）
  • 配置選項
  • 與 PyYAML 的對比
  • 高級用法：Round-trip 模式（推薦用於配置編輯）
  • 示例：帶註釋的 YAML 文件處理
  • 總結

ruamel.yaml 是一個功能強大且廣泛使用的 Python 庫，用於處理 YAML（YAML Ain’t Markup Language）格式的數據。它是 PyYAML 的一個增強分支，由 Anthon van der Neut 維護，主要優勢在於：

  • 保留原始 YAML 文件的格式（包括註釋、縮進、順序等）；
  • 支持 YAML 1.2 規範（比 PyYAML 默認支持的 YAML 1.1 更現代）；
  • 提供更靈活的 API，適用於讀取、修改並寫回 YAML 文件的場景（如配置文件編輯）。

安裝

pip install ruamel.yaml

基本使用

1. 讀取 YAML
from ruamel.yaml import YAML

yaml = YAML()
with open('config.yaml') as f:
    data = yaml.load(f)

print(data)
2. 寫入 YAML
from ruamel.yaml import YAML

yaml = YAML()
data = {'name': 'Alice', 'age': 30, 'active': True}

with open('output.yaml', 'w') as f:
    yaml.dump(data, f)
3. 讀取 → 修改 → 保留格式寫回（典型用例）

這是 ruamel.yaml 最突出的能力：修改 YAML 文件但保留註釋和結構。

from ruamel.yaml import YAML

yaml = YAML()
with open('config.yaml') as f:
    config = yaml.load(f)

# 修改內容
config['database']['port'] = 5433

# 寫回（保留原有註釋、縮進等）
with open('config.yaml', 'w') as f:
    yaml.dump(config, f)

注意：必須使用 ruamel.yaml.YAML() 實例（而不是 yaml.load/dump 函數），才能保留格式。

配置選項

YAML 對象支持多種配置：

yaml = YAML()
yaml.indent(mapping=2, sequence=4, offset=2)  # 控制縮進
yaml.preserve_quotes = True                   # 保留字符串引號
yaml.width = 100                              # 行寬限制
yaml.explicit_start = True                    # 添加 --- 開頭
yaml.explicit_end = True                      # 添加 ... 結尾

與 PyYAML 的對比

特性

ruamel.yaml

PyYAML

保留註釋

✅ 是

❌ 否

保留鍵順序

✅（默認 dict 有序）

✅（Python 3.7+）

支持 YAML 1.2

✅

❌（僅 1.1）

安全加載（防任意代碼）

✅（默認安全）

❌（yaml.load 危險）

性能

稍慢

稍快

ruamel.yaml 默認使用安全加載，無需擔心 !!python/object 等反序列化風險。

高級用法：Round-trip 模式（推薦用於配置編輯）

ruamel.yaml 默認使用 round-trip loader/dumper，專門用於“讀-改-寫”場景：

from ruamel.yaml import YAML

yaml = YAML(typ='rt')  # 'rt' = round-trip（默認值）

該模式會保留：

  • 註釋（行內和行間）
  • 鍵的順序
  • 空行
  • 縮進風格
  • 字符串樣式（單引號、雙引號、無引號）

示例：帶註釋的 YAML 文件處理

原始 app.yaml：

# 應用配置
app:
  name: myapp
  version: 1.0  # 當前版本
  debug: false

Python 代碼：

from ruamel.yaml import YAML

yaml = YAML()
with open('app.yaml') as f:
    cfg = yaml.load(f)

cfg['app']['version'] = '1.1'
cfg['app']['debug'] = True

with open('app.yaml', 'w') as f:
    yaml.dump(cfg, f)

輸出仍保留註釋：

# 應用配置
app:
  name: myapp
  version: 1.1  # 當前版本
  debug: true

總結

  • 如果你只是讀取或生成 YAML，PyYAML 足夠；
  • 如果你需要編輯現有 YAML 文件並保留格式/註釋（如配置管理工具），強烈推薦 ruamel.yaml；
  • 它是 DevOps 工具、CI/CD 腳本、配置生成器等場景的理想選擇。