每日一模块：voluptuous

一、简介

voluptuous是一个Python数据验证库，它允许你定义复杂的数据结构验证规则，并使用这些规则来验证数据。voluptuous非常适合用于配置文件验证、API输入验证等场景。它提供了丰富的验证器和类型，支持嵌套数据结构的验证，并且允许你自定义验证函数。

二、安装

使用pip安装voluptuous：

pip install voluptuous

三、基本使用

3.1 导入voluptuous

首先，你需要导入voluptuous模块：

from voluptuous import Schema, Invalid, Required, All, Any, Range

3.2 定义模式

使用voluptuous的Schema类来定义验证模式。你可以使用内置的验证器（如str、int、bool等）或者自定义的验证器来定义字段的验证规则。

示例：简单模式

schema = Schema({
    Required('name'): str,
    'age': All(int, Range(min=0, max=150)),
})

在这个例子中，我们定义了一个模式，它要求一个包含name和age字段的字典。name字段是必需的，并且必须是字符串类型；age字段是可选的，它必须是整数类型，并且值在0到150之间。

示例：嵌套模式

schema = Schema({
    'person': {
        Required('name'): str,
        'age': All(int, Range(min=0, max=150)),
        'address': {
            'street': str,
            'city': str,
        },
    },
    'hobbies': All(list, [str]),
})

在这个例子中，我们定义了一个更复杂的模式，它包含一个嵌套的person字段和一个hobbies列表。person字段本身是一个字典，包含name、age和address字段。hobbies字段是一个字符串列表。

3.3 验证数据

使用定义好的模式来验证数据。如果数据不符合模式，voluptuous会抛出一个Invalid异常。

data = {
    'person': {
        'name': 'beiJin',
        'age': 30,
        'address': {
            'street': '123 Main St',
            'city': 'Anytown',
        },
    },
    'hobbies': ['reading', 'coding'],
}

try:
    schema(data)  # 如果数据符合模式，这行代码将不会抛出异常
    print("Data is valid")
except Invalid as e:
    print("Data is invalid:", e)

四、voluptuous的验证器

voluptuous提供了许多内置的验证器，以下是一些常用的验证器示例：

4.1 字段类型

• str：字符串类型
• int：整数类型
• float：浮点数类型
• bool：布尔类型
• 'email'：电子邮件地址类型（使用内置的 email 验证器）
• 'url'：URL 类型（使用内置的 URL 验证器）

4.2 复杂类型

• List(subtype)：列表类型，subtype 指定列表中元素的类型
• Dict(mapping)：字典类型，mapping 是一个字典，其键是字段名，值是字段的验证规则

4.3 修饰符

• Required(...)：指定字段是必需的
• Optional(...)：指定字段是可选的（默认所有字段都是可选的）
• All(*validators)：组合多个验证器，数据必须依次通过所有验证器
• Any(*validators)：数据只需通过其中一个验证器即可
• Coerce(type, conversion_func=None)：尝试将数据类型转换为指定的类型，如果转换失败则抛出 Invalid 异常
• Length(min=None, max=None, exact=None)：验证字符串、列表、元组等的长度
• Range(min=None, max=None)：验证数字是否在指定范围内
• Match(pattern)：验证字符串是否与正则表达式匹配

4.4 自定义验证器

你可以定义自己的验证函数，并将其作为验证器使用。

def is_positive(value):
    if value <= 0:
        raise Invalid('Value must be positive')
    return value

schema = Schema({
    'amount': is_positive
})


# 验证
data = {"amount": 1}
try:
    r = schema(data)
except Invalid as e:
    print(e)
else:
    print(r)