严格的 YAML 解析器：StrictYAML 使用指南

StrictYAML

Source | HN Comments

StrictYAML 是一个类型安全的 YAML 解析器，它拒绝解析 YAML 中不安全的功能，并提供严格的标记验证和类型转换。它具有优美的 API，清晰的异常信息，并支持修改和写回 YAML 文件，同时保留注释。可以使用 schema 进行数据验证，如果存在语法错误或 schema 违例，会抛出异常。 StrictYAML 旨在提供更安全、更易于维护的 YAML 解析体验，并提供了丰富的验证器和使用指南。

StrictYAML

PyPI - Downloads

StrictYAML 是一个类型安全的 YAML 解析器，它解析并验证 YAML 规范的一个受限子集。

主要特性：

优美的 API
拒绝解析 YAML 中丑陋、难以阅读且不安全的功能，例如 Norway problem。
严格的标记验证和直接的类型转换。
清晰易读的异常信息，包含代码片段和行号。
可以作为 pyyaml、ruamel.yaml 或 poyo 的近似替代品。
能够读取 YAML，进行修改并写回，同时保留注释。
当前不以速度为优先。

简单示例：

# All about the character
name:Ford Prefect
age:42
possessions:
-Towel

from strictyaml import load, Map, Str, Int, Seq, YAMLError

默认解析结果：

>>> load(yaml_snippet)
YAML({'name': 'Ford Prefect', 'age': '42', 'possessions': ['Towel']})

所有数据都是字符串、列表或 OrderedDict 类型：

>>> load(yaml_snippet).data
{'name': 'Ford Prefect', 'age': '42', 'possessions': ['Towel']}

使用 schema 的快速入门：

from strictyaml import load, Map, Str, Int, Seq, YAMLError
schema = Map({"name": Str(), "age": Int(), "possessions": Seq(Str())})

42 现在被解析为整数：

>>> person = load(yaml_snippet, schema)
>>> person.data
{'name': 'Ford Prefect', 'age': 42, 'possessions': ['Towel']}

如果存在语法问题、违反 schema 或使用了不允许的 YAML 特性，将会抛出 YAMLError 异常：

# All about the character
name:Ford Prefect
age:42

例如，一个 schema 违例：

try:
  person = load(yaml_snippet, schema)
except YAMLError as error:
  print(error)

while parsing a mapping
in "<unicode string>", line 1, column 1:
# All about the character
^ (line:1)
required key(s) 'possessions' not found
in "<unicode string>", line 3, column 1:
age:'42'
^ (line:3)

如果解析正确：

from strictyaml import load, Map, Str, Int, Seq, YAMLError, as_document
schema = Map({"name": Str(), "age": Int(), "possessions": Seq(Str())})

您可以修改值并写出 YAML，同时保留注释：

person = load(yaml_snippet, schema)
person['age'] = 43
print(person.as_yaml())

# All about the character
name:Ford Prefect
age:43
possessions:
-Towel

以及查找行号：

>>> person = load(yaml_snippet, schema)
>>> person['possessions'][0].start_line
5

还可以从 dict 或 list 构建 YAML 文档：

print(as_document({"x": 1}).as_yaml())

x:1

安装

$ pip install strictyaml

为什么选择 StrictYAML？

有许多格式和方法可以实现与 StrictYAML 大致相同的目的。我已尝试使其成为最好的一个。以下是一系列有据可查的理由：

使用 StrictYAML

使用方法：

复合验证器：

标量验证器：

限制：

设计依据

StrictYAML 中有一些有争议和/或不明显的设计决策。这些记录在此处：

Star 贡献者

@wwoods
@chrisburr
@jnichols0

其他贡献者

@eulores
@WaltWoods
@ChristopherGS
@gvx
@AlexandreDecan
@lots0logs
@tobbez
@jaredsampson
@BoboTIG

贡献

在编写任何代码之前，请阅读有关向 hitchdev 库贡献的教程。
在编写任何代码之前，如果您要提出新功能，请在 github 上提出。如果是现有功能/错误，请评论并简要描述您将如何实现它。
所有代码都需要附带一个 story 来练习它，或者修改现有的 story。这既用于测试代码，也用于构建文档。

由 Material for MkDocs 构建。