ruamel.yaml 中 yaml 的注释结构

Question

我试图理解 ruamel.yaml 库中的评论结构，以便我可以正确地操作评论。我不明白的是为什么 .ca 中的评论在 4 项列表中？那些其他项目是什么？为什么它们总是 None？

例如，附加到序列的评论是这样的，第一个是CommentToken，其余是None：

Comment(
  start=None,
  items={
    2: [CommentToken('\n\n########### Foo ###########\n', line: 294, col: 0), None, None, None]
  })

对于附加到地图的评论，它似乎总是放在第 3 个索引处？

Comment(
  start=None,
  items={
    bar: [None, None, CommentToken('\n\n########## Bar ###########\n', line: 87, col: 0), None]
  })

它们之间有什么区别，它们的放置顺序有什么意义？

Answer 1

在您看来，对于 YAML 映射，注释被放在相同的位置，因为您倾向于将注释放在 YAML 文件中的相同位置（即在值之后的行尾） .我在 2014 年开始 ruamel.yaml 时也做过同样的事情，但多年来针对包的问题报告指出，一些用户（YAML）倾向于将他们的评论放在不同的地方（例如在键和值之间）下一行，最初根本没有处理过的东西）。

重要的是表示器在转储数据结构时尝试将注释插入回 YAML 输出流。这样做的代码在过去几年中得到了发展，可以处理更多最初未处理的评论放置（即评论在 round-trip 上丢失或被替换）。

没有关于此的记录 API，创建 Comment 实例的代码与处理它们的代码一起更改，因此原则上任何位置的含义都可能更改，这些含义实际上已经在过去发生了变化。该列表结构也可能被带有键的字典替换，这些键比索引更能指示注释（存储在相应值中）from/has 被插入的位置。 dict 也可以取消指示空槽的 None 值。

我不能保证源代码文档是最新的，但 this 就是它所说的：

# map key (mapping/omap/dict) or index (sequence/list) to a  list of
# dict: post_key, pre_key, post_value, pre_value
# list: pre item, post item

IIRC 其中一些职位已不再使用。

您应该固定您使用的 ruamel.yaml 的版本号。 ruamel.yaml 遵循语义版本控制，但没有 API 用于处理评论，并且它是 1.0 之前的版本，因此任何内容都可以随时更改。然而，次要数量往往会因主要（内部）更改或放弃对不再维护的 Python 版本的支持而增加。因此，如果您的代码可以与 0.17.21 一起使用，请坚持使用 ruamel.yaml<0.18，并广泛测试，如果 0.18 及更高版本仍能满足您的要求。

用于处理评论的 API 将在某个时候出现，除了处理更多（异国情调的）评论放置之外，还有一种方法可以指定如何处理 multi-line 评论所以它们不一定像现在一样附加到前面的节点，但可以分配给后面的节点或根据某些规则（例如第一个空行）在这些节点之间拆分。

ruamel.yaml 中 yaml 的注释结构

comment structure of yaml in ruamel.yaml

ruamel.yaml