内联注释ruamel.yaml

Question

我正在使用ruamel.yaml为我的个人项目添加评论到我的自动配置生成功能。关于这个问题，我将用一个类似的例子来说明这个问题。

比方说，您有一个默认配置字典(自动生成)：

{'auth': {'api_key': '', 'api_secret': ''}}

现在，我以以下方式将这个dict加载到一个CommentedMap对象中：

yaml_config = yaml.round_trip_load(yaml.round_trip_dump(dump))

现在，我有了一个元数据dict，其中包括dict中这些配置值的多行/单行描述：

{
  "auth": {
    "api_key": "Think of this as the user name that represents your account when using the app.\n# Head 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.\n# Head over to XXX.com, register an app and get your auth keys!"
  }
}

现在，我希望加载这些元数据项，并将注释添加到yaml_config中的各个字段。请记住，metadata和dump模式是相同的。dump和metadata可以是任意数量的嵌套dicts，我只提供了上面的一个示例。

我试过下面的代码来使它工作，但它只是不起作用.没有任何注释或任何错误/异常。

previous_config[field_name].yaml_add_eol_comment(description, _field_name)

上述示例的正确输出应该是：

auth:
    # 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_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: ''

Answer 1

我建议永远包括一个完整的工作例子，说明什么不能做你想做的事情，因为现在还不完全清楚到底哪里出了问题。使用ruamel.yaml的新开发不应该使用旧的API (round_trip_load/round_trip_dump)，而应该使用API几年前引入的新API (实例化YAML())，您没有给出使用需要使用有限的旧API的古老ruamel.yaml版本的指示。

通过对最终结果YAML文档进行往返检查，可以对您想要做的事情做一些琐碎的检查，并看到它可以保持不变：

import sys
import ruamel.yaml

yaml_str = """\
auth:
    # 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_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: ''
"""

yaml = ruamel.yaml.YAML()
yaml.indent(mapping=4)
data = yaml.load(yaml_str)
yaml.dump(data, sys.stdout)

这意味着：

auth:
    # 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_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: ''

您可以检查注释属性：

print(data['auth'].ca)

其中的指纹：

Comment(comment=[None, [CommentToken('# Think of this as the password that represents your account when using the app.\n', line: 1, col: 4), CommentToken('# Head over to XXX.com, register an app and get your auth keys!\n', line: 2, col: 4)]],
  items={'api_key': [None, None, CommentToken('\n    # Think of this as the password that represents your account when using the app.\n    # Head over to XXX.com, register an app and get your auth keys!\n', line: 4, col: 4), None]})

行尾注释发生在其他数据之后，这就是名称的含义。在ruamel.yaml中，行尾注释通常与键值对的键相关联，并且这些注释被期望在一行和同一行上，并且注释可以扩展到以下行，包括任何空行。对于ruamel.yaml和行尾注释，在起始行的末尾不一定有注释(即可以是空的)。

您还应该意识到，这些(内部)例程不是固定的，会改变，并可能停止工作，希望不会，但有时没有警告(因此在您的安装中修正版本号)。

通过将注释元数据关联到元数据(最终必须在键值对api-key的api_key: ''之后)，将元数据中的键api-secret与键api-secret相关联，就会使事情变得不必要。我会让那个自我引发的问题得不到解决。

yaml_add_eol_comment()总是添加一个缺失的初始#，不能添加“真正的”行尾部分为emtpy的多行注释，并要求您自己缩进多行注释的行。

您还可以在上面的输出中看到，与“用户名”有关的注释与其他注释完全不同，因为此注释出现在键(auth)和与该键关联的值(两个键值相关联的值)之间。因此，需要添加与键api_key上的注释不同的注释。

import sys
import ruamel.yaml

yaml_str = """\
auth:
    api_key: ''
    api_secret: ''
"""

def indent_comment(s, indent):
    return s.replace('\n', '\n' + ' ' * indent)

MAPIND = 4

yaml = ruamel.yaml.YAML()
yaml.indent(mapping=MAPIND)
data = yaml.load(yaml_str)
auth = data['auth']
auth.yaml_set_start_comment(
    "Think of this as the user name that represents your account when using the app.\n"
    "# Head over to XXX.com, register an app and get your auth keys!",
    indent=MAPIND,
)
auth.yaml_add_eol_comment('place_holder', 'api_key')
# correct the assigned comment token
cai = auth.ca.items['api_key'][2]
cai.value = indent_comment('\n# Think of this as the password that represents your account when using the app.\n# Head over to XXX.com, register an app and get your auth keys!', MAPIND)

yaml.dump(data, sys.stdout)

这给出了你所需的结果：

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: ''

上述操作是用ruamel.yaml==0.17.17完成的，其他版本可能需要修改。