如何使用ruamel.yaml为CommentedMap嵌套配置字段批量添加注释

问题根因 #

你之前调用yaml_add_eol_comment未生效有两个核心原因：

1. 该方法是用来添加行尾注释的，和你需要的「键上方的前置注释」需求不匹配
2. 调用对象错误：给某个配置键加前置注释，需要在该键的父级CommentedMap对象上调用yaml_set_comment_before_key方法，不能在键对应的value对象上操作。

实现方案 #

通过递归遍历嵌套结构的方式，自动对齐配置和元数据的层级，即可实现任意深度的注释批量添加，完整可运行代码如下：

from ruamel.yaml import YAML

def add_config_comments(config_node, meta_node):
    """
    递归给嵌套的CommentedMap添加注释
    :param config_node: 当前层级的CommentedMap配置节点
    :param meta_node: 当前层级对齐的元数据节点
    """
    for key, meta_val in meta_node.items():
        if isinstance(meta_val, dict):
            # 嵌套结构，递归处理下一层
            add_config_comments(config_node[key], meta_val)
        else:
            # 处理多行注释格式，按换行拆分，每行统一加#前缀
            comment_lines = []
            for line in meta_val.strip().split('\n'):
                line = line.strip().lstrip('#').strip()
                comment_lines.append(f'# {line}')
            comment_str = '\n'.join(comment_lines)
            # 给当前键添加前置注释
            config_node.yaml_set_comment_before_key(key, comment_str)

# 示例使用
if __name__ == '__main__':
    yaml = YAML()
    yaml.indent(mapping=4) # 匹配预期输出的缩进规则

    # 1. 传入默认配置字典，转成支持注释的CommentedMap
    default_config = {'auth': {'api_key': '', 'api_secret': ''}}
    yaml_config = yaml.round_trip_load(yaml.round_trip_dump(default_config))

    # 2. 传入结构对齐的元数据字典
    comment_meta = {
        "auth": {
            "api_key": "Think of this as the user name that represents your account when using the app.\nHead over to XXX.com, register an app and get your auth keys!",
            "api_secret": "Think of this as the password that represents your account when using the app.\nHead over to XXX.com, register an app and get your auth keys!"
        }
    }

    # 3. 批量添加注释
    add_config_comments(yaml_config, comment_meta)

    # 输出到文件/控制台
    yaml.dump(yaml_config, open('config.yaml', 'w', encoding='utf-8'))

输出结果 #

运行后生成的yaml文件完全符合预期：

auth:
    # Think of this as the user name that represents your account when using the app.
    # Head over to XXX.com, register an app and get your auth keys!
    api_key: ''
    # Think of this as the password that represents your account when using the app.
    # Head over to XXX.com, register an app and get your auth keys!
    api_secret: ''

内容的提问来源于stack exchange，提问作者Shivansh-007