pyparamvalidate 0.3.0

一个简单易用的 Python 函数参数验证器。提供多种内置验证器，支持自定义验证规则，帮助开发者轻松进行函数参数验证，提高代码的健壮性和可维护性。

pyparamvalidate 是一个简单易用的函数参数验证器。它提供了各种内置验证器，支持自定义验证规则，有助于 python 开发人员轻松进行函数参数验证，提高代码的健壮性和可维护性。

项目地址：github

一、安装

pip install pyparamvalidate

如果安装过程中提示 Failed to build numpy 错误：

Failed to build numpy
ERROR: Could not build wheels for numpy, which is required to install pyproject.toml-based projects

请先手动安装 numpy 库:

pip install numpy

二、使用示例

该示例可使用 pytest 执行:

import pytest
from pyparamvalidate import ParameterValidator


def test_complex_validator():
    @ParameterValidator("description").is_string().is_not_empty()
    @ParameterValidator("gender", "Invalid").is_allowed_value(["male", "female"],
                                                              "Gender must be either 'male' or 'female'")
    @ParameterValidator("age", param_rule_des="Age must be a positive number").is_int().is_positive()
    @ParameterValidator("name").is_string(exception_msg="Name must be a string").is_not_empty()
    def example_function(name, age, gender='male', **kwargs):
        description = kwargs.get("description")
        return name, age, gender, description

    # 正向测试用例
    result = example_function(name="John", age=25, gender="male", description="A person")
    assert result == ("John", 25, "male", "A person")

    # 反向测试用例：测试 name 不是字符串的情况
    with pytest.raises(ValueError) as exc_info:
        example_function(name=123, age=25, gender="male", description="A person")
    assert "Name must be a string" in str(exc_info.value)
    print('\n')
    print(exc_info.value)
    print('==================================')

    # 反向测试用例：测试 age 不是正整数的情况
    with pytest.raises(ValueError) as exc_info:
        example_function(name="John", age="25", gender="male", description="A person")
    assert "Age must be a positive number" in str(exc_info.value)
    print(exc_info.value)
    print('==================================')

    # 反向测试用例：测试 gender 不是预定义值的情况
    with pytest.raises(ValueError) as exc_info:
        example_function(name="John", age=25, gender="other", description="A person")
    assert "Gender must be either 'male' or 'female'" in str(exc_info.value)
    print(exc_info.value)
    print('==================================')

    # 反向测试用例：测试 description 不是字符串的情况
    with pytest.raises(ValueError) as exc_info:
        example_function(name="John", age=25, gender="male", description=123)
    assert "invalid" in str(exc_info.value)
    print(exc_info.value)
    print('==================================')

    # 反向测试用例：测试 description 是空字符串的情况
    with pytest.raises(ValueError) as exc_info:
        example_function(name="John", age=25, gender="male", description="  ")
    assert "invalid" in str(exc_info.value)
    print(exc_info.value)
    print('==================================')

输出结果：

============================= test session starts =============================
collecting ... collected 1 item

test_param_validator.py::test_complex_validator PASSED                   [100%]

name error: "123" is invalid. due to: Name must be a string
==================================
age error: "25" is invalid. due to: Age must be a positive number
==================================
gender error: "other" is invalid. due to: Gender must be either 'male' or 'female'
==================================
description error: "123" is invalid.
==================================
description error: "  " is invalid.
==================================


============================== 1 passed in 0.03s ==============================

三、特性说明

3.1 关于校验方法

• 支持链式调用

from pyparamvalidate import ParameterValidator


@ParameterValidator("name").is_string().is_not_empty()
def example_function(name, age, gender='male', **kwargs):
    ...

• 支持自定义校验方法

import pytest
from pyparamvalidate import ParameterValidator


def test_custom_validator():
    # ====================================== 使用 lambda 函数 ======================================
    @ParameterValidator("param").customize(lambda x: x % 2 == 0, exception_msg="Value must be an even number")
    def example_function(param):
        return param

    assert example_function(param=12) == 12

    with pytest.raises(ValueError) as exc_info:
        example_function(param=5)
    assert "Value must be an even number" in str(exc_info.value)

    # ====================================== 使用 自定义 函数 ======================================
    def even_number_validator(value, threshold):
        # 注意：如果自定义校验方法有多个参数，必须要将 `待校验参数` 放在第一位
        # 示例：本例中，将 `value` 参数放在第一位

        return value % 2 == 0 and value > threshold

    # 注意：
    # 1. 使用自定义校验方法时，不要给第一个参数传值，该值从被装饰函数的参数中获取。
    # 2. `customize` 方法中的 `exception_msg` 参数，必须使用 `关键字参数` 形式进行传值。
    @ParameterValidator("param").customize(even_number_validator, 10,
                                           exception_msg="Value must be an even number and greater than 10")
    def example_function(param):
        return param

    assert example_function(param=12) == 12

    with pytest.raises(ValueError) as exc_info:
        example_function(param=5)
    assert "Value must be an even number" in str(exc_info.value)

• 支持使用schema库进行较复杂校验，如：

import schema
import re
from pyparamvalidate import ParameterValidator


# 1. 定义 schema

def capitalize(value):
    return value.capitalize()


def validate_email(value):
    email_regex = re.compile(r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$')
    return bool(re.match(email_regex, value))


user_schema = schema.Schema({
    'username': schema.And(str, lambda s: len(s.strip()) > 0, error='Username cannot be empty or contain only spaces'),
    'phone_number': schema.Regex(r'^\d{11}$', error='Invalid phone number format. It should be a 10-digit number.'),
    'email': schema.And(schema.Or(str, None), lambda s: validate_email(s) if s is not None else True,
                        error='Invalid email format'),
    'age': schema.And(int, lambda n: 0 <= n <= 120, error='Age must be an integer between 0 and 120'),
    'gender': schema.And(str, lambda s: s.lower() in ['male', 'female', 'other'], error='Invalid gender'),
    'family_members': schema.And(schema.Use(list), [schema.Use(capitalize)]),
    'others': {
        'address': schema.And(str, lambda s: s.strip(), error='Address must be a non-empty string'),
        'blog': schema.Or(None, schema.Regex(r'^https?://\S+$', error='Invalid blog format. It should be a valid URL starting with http:// or https://')),
        'other': schema.Or(str, None)
    }
})


# 2. 使用 schema 进行校验

@ParameterValidator("user_data").schema_validate(user_schema)
def example_function(user_data):
    return user_data

3.2 关于校验错误的提示

• 可以在 ParameterValidator实例化时描述参数规则 param_rule_des：

@ParameterValidator("age", param_rule_des="Age must be a positive number")

• 也可以在 validate_method 中描述错误提示 exception_msg：

@ParameterValidator("name").is_string(exception_msg="Name must be a string")

• 如果 param_rule_des 和 exception_msg 同时为空，则默认提示 <param> error: "<value> is invalid."
• 如果 param_rule_des 和 exception_msg 同时为真，则优先使用 exception_msg 的值，提示 <param> error: "<value>" is invalid .due to: <exception_msg>

3.3 关于 ParameterValidator 类 和 Validator 类

• ParameterValidator 类使用 Validator 类中的校验方法；
• ParameterValidator 类中定义的校验方法，仅用于编辑器如 Pycharm 智能识别可调用的方法，无实际用途；
• 如果要扩展校验方法，需先继承 Validator 类添加校验方法，然后再将添加的方法复制粘贴至 ParameterValidator 类，用于编辑器智能识别可调用的方法。

四、内置验证器

• is_string：检查参数是否为字符串。
• is_int：检查参数是否为整数。
• is_positive：检查参数是否为正数。
• is_float：检查参数是否为浮点数。
• is_list：检查参数是否为列表。
• is_dict：检查参数是否为字典。
• is_set：检查参数是否为集合。
• is_tuple：检查参数是否为元组。
• is_not_none：检查参数是否不为None。
• is_not_empty：检查参数是否不为空（对于字符串、列表、字典、集合等）。
• is_allowed_value：检查参数是否在指定的允许值范围内。
• max_length：检查参数的长度是否不超过指定的最大值。
• min_length：检查参数的长度是否不小于指定的最小值。
• is_substring：检查参数是否为指定字符串的子串。
• is_subset：检查参数是否为指定集合的子集。
• is_sublist：检查参数是否为指定列表的子列表。
• contains_substring：检查参数是否包含指定字符串。
• contains_subset：检查参数是否包含指定集合。
• contains_sublist：检查参数是否包含指定列表。
• is_file：检查参数是否为有效的文件。
• is_dir：检查参数是否为有效的目录。
• is_file_suffix：检查参数是否以指定文件后缀结尾。
• is_method：检查参数是否为可调用的方法（函数）。
• schema_validate：使用schema库校验数据。
• customize：自定义校验器。

许可证

本项目采用 MIT 许可证授权。

Copyright (c) 2018 The Python Packaging Authority

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.