PyCDDL：反序列化CBOR和/或进行CDDL模式验证

CDDL 是CBOR序列化格式的模式语言。 pycddl 允许您

• 根据Rust cddl 库，验证CBOR文档是否与特定的CDDL模式匹配。
• 可选地，解码CBOR文档。

用法

验证

这里我们使用 cbor2 库将字典序列化为CBOR，然后对其进行验证

from pycddl import Schema
import cbor2

uint_schema = Schema("""
    object = {
        xint: uint
    }
"""
)
uint_schema.validate_cbor(cbor2.dumps({"xint", -2}))

如果验证失败，将抛出 pycddl.ValidationError。

验证 + 反序列化

您可以使用 cbor.loads() 将CBOR反序列化为Python对象。然而

• cbor2 默认使用C代码，而C编程语言容易发生内存安全问题。如果您正在读取不受信任的CBOR，最好使用Rust库来解码数据。
• 您需要解析CBOR两次，一次用于验证，一次用于解码，这将增加性能开销。

通过使用 pycddl 进行反序列化，您解决了第一个问题，而 pycddl 的未来版本将解决第二个问题（请参阅 https://gitlab.com/tahoe-lafs/pycddl/-/issues/37）。

from pycddl import Schema
import cbor2

uint_schema = Schema("""
    object = {
        xint: uint
    }
"""
)
deserialized = uint_schema.validate_cbor(cbor2.dumps({"xint", -2}), True)
assert deserialized == {"xint": -2}

不进行模式验证的反序列化

如果您不关心模式，可以像这样直接反序列化CBOR

from pycddl import Schema

ACCEPT_ANYTHING = Schema("main = any")

def loads(encoded_cbor_bytes):
    return ACCEPT_ANYTHING.validate_cbor(encoded_cbor_bytes, True)

在未来的版本中，这将成为一个独立的、更高效的API，请参阅 https://gitlab.com/tahoe-lafs/pycddl/-/issues/36

减少内存使用和安全性限制

为了减少内存使用，您可以传递任何实现了buffer API并存储字节的Python对象，例如 memoryview() 或 mmap 对象。

传入的对象必须是只读的，数据在验证过程中不得更改！如果在验证过程中修改数据，结果可能导致内存损坏或其他未定义行为。

支持的反序列化CBOR类型

如果您将CBOR文档反序列化为Python对象，您可以反序列化

• 空/None。
• 布尔值。
• 浮点数。
• 64位整数以下的整数。尚未支持更大的整数。
• 字节。
• 字符串。
• 列表。
• 映射/字典。
• 集合。

如果用户有需求，将来会添加其他类型。

模式验证不仅限于此列表，而是受cddl Rust crate的功能限制。

发行说明

0.6.3

功能

• 支持最终版本3.13。

0.6.2

功能

• 增加了对Python 3.13的支持。

0.6.1

错误修复

• 允许PyPy反序列化CBOR。

0.6.0

功能

• validate_cbor(serialized_cbor, True)将CBOR文档反序列化为Python对象，因此您无需单独使用例如cbor2.loads(serialized_cbor)。

错误修复

• 以更有用的方式释放GIL。

杂项

• 升级到新的cddl crate (0.9.4)。

0.5.3

• 升级到新的cddl crate (0.9.3)。
• 添加Python 3.12支持。

0.5.2

• 升级到新的cddl crate (0.9.2)，改进了验证功能。

0.5.1

• 升级到新的cddl crate，修复了一些验证错误。

0.5.0

• 支持ARM macOS。
• 停止支持Python 3.7。

0.4.1

• 测试修复，没有用户相关的更改。

0.4.0

• validate_cbor()现在接受只读缓冲区，不仅仅是bytes。如果您想验证大文件，例如，这很有用，因为您可以使用mmap()它。
• 当解析大于10KiB的文档时，释放GIL。

0.3.0

• 修复了一个主要错误，即如果文档是有效的UTF-8，则库将尝试将其解析为JSON！
• 增加了对ARM macOS的支持。

0.2.2

• 更新到cddl 0.9.1。

0.2.1

• 添加了PyPy wheel。

0.2.0

• 现在模式仅在创建Schema对象时解析一次，而不是每次验证发生时，这应该会提高验证性能。
• 更新到基础 CDDL 库的新版本，这应该会使 CDDL 解析更加兼容。
• 为Schema添加了repr()实现，以便更容易调试。

0.1.11

• 初始发布。