Python使用yaml模块读写YAML配置文件的完整指南

YAML基础规范与数据结构映射

YAML是一种专为数据序列化设计的轻量级标记语言，凭借其清晰的文件结构与人类友好的排版，成为各类工程配置文件的首选。其文件通常使用.yaml或.yml后缀。解析器会按照以下规则转换内容：

• 大小写敏感，且仅允许空格缩进（不可使用Tab），同级元素左侧对齐即可。
• 键值对（字典）使用冒号分隔，key: value的冒号后方必须有一个空格。
• 数组/列表使用短横线引导，- value的短横后方需留空格。
• 纯量（标量）包含字符串、数值、布尔值及时间等，特殊字符需加引号。空值可表示为null或波浪号~。

基础结构对照示例如下：

# 映射（对象/字典）
user: admin
pwd: "admin@123"

# 序列（数组/列表）
students:
  - student_1
  - student_2

# 纯量与空值
score: 98.5
is_active: true
optional_field: ~

第1步：安装PyYAML运行环境

打开终端或命令行界面，执行以下指令下载并安装官方维护的解析库：

pip install pyyaml

验证安装是否成功可运行import yaml; print(yaml.__version__)，无报错即代表环境就绪。

第2步：解析字典、列表与多文档配置

针对单文件内的常规嵌套结构或独立列表，推荐使用安全的加载接口。

import yaml

def read_config(file_path):
    with open(file_path, 'r', encoding='utf-8') as f:
        # safe_load会自动将YAML转为Python的dict或list类型
        return yaml.safe_load(f)

data = read_config('config.yaml')
print(type(data))  # 输出：
print(data)

处理同一文件内的多个YAML文档

当配置文件使用---分割符存放多组独立配置时，需使用迭代器加载：

def read_multi_docs(file_path):
    with open(file_path, 'r', encoding='utf-8') as f:
        contents = yaml.safe_load_all(f)
        for doc in contents:
            print(doc)

read_multi_docs('multi_config.yaml')

完成判断：控制台逐行打印出对应的字典对象，且类型检查返回正确结构。

第3步：创建新文件与安全修改原有配置

利用yaml.dump()可将Python对象还原为标准YAML文本。执行覆盖写入前，务必提前备份源文件以防配置丢失。

import yaml
import shutil
import os

def generate_yaml(target_path, py_object):
    # 备份原始文件
    if os.path.exists(target_path):
        shutil.copy2(target_path, target_path + '.bak')
        
    with open(target_path, 'w', encoding='utf-8') as f:
        yaml.safe_dump(py_object, f, allow_unicode=True, default_flow_style=False)

new_config = {
    'school': 'Test University',
    'student_list': ['stu_101', 'stu_102']
}
generate_yaml('output.yaml', new_config)

动态更新特定字段

读取内存后修改数据结构，再重新落盘即可完成更新：

def update_field(path, key, new_value):
    current_data = read_config(path)
    current_data[key] = new_value  # 不存在则自动追加，存在则覆盖
    
    # 再次备份以防止二次错误
    shutil.copy2(path, path + '_modified.bak')
    
    with open(path, 'w', encoding='utf-8') as f:
        yaml.safe_dump(current_data, f, allow_unicode=True, default_flow_style=False)

update_field('output.yaml', 'school', 'Target College')

完成判断：目标目录下生成符合规范的.yaml文件，内部键值对顺序与缩进整齐，且备份文件与原文件内容一致。

第4步：使用ruamel.yaml保留原始排版风格

标准pyyaml库重写时会重置注释和空白排版。若需严格保留业务人员编写的原始格式（如保留注释、自定义换行），需安装高级库：

pip install ruamel.yaml

配合RoundTripDumper可实现无损读写：

from ruamel.yaml import YAML
import os

def preserve_format_write(target_path, data_dict):
    yaml_handler = YAML()
    yaml_handler.default_flow_style = False
    yaml_handler.preserve_quotes = True
    
    # 指定编码避免中文乱码
    with open(target_path, 'w', encoding='utf-8') as f:
        yaml_handler.dump(data_dict, f)

write_data = {'project_name': 'AI_Platform', 'version': '1.2.0'}
preserve_format_write('template.yaml', write_data)

完成后查看文件，发现原有的缩进风格与注释将被原样保留。

常见异常排查建议

1. IndentationError / Bad indent：YAML强依赖空格层级。检查代码块起始位置是否混用了Tab键，或上下级缩进格数不一致。
2. Key重复警告：若同层出现相同键名，后出现的值会静默覆盖前者。建议在导入阶段加入数据校验逻辑。
3. 日期解析异常：YAML默认会将形如2023-02-03的值转为datetime.date对象。如需保持字符串格式，请用单双引号包裹日期值。

简要总结

掌握YAML的缩进规范与基础数据类型映射是高效管理配置的前提。通过结合safe_load的安全读取、带备份机制的覆盖写入以及ruamel.yaml的格式保留方案，开发者可在不同业务场景中稳定落地自动化配置流程。以上就是Python操作YAML配置文件的详细内容，更多关于YAML基础语法与自动化配置管理的资料请关注本站其它相关文章！