NEPattern

WARNING

在目前的 Arclet 项目中, 仅 Alconna V2 使用了 NEPattern 的 v1 版本, 其他项目仍在使用 v0 版本.

NEPattern 是 Arclet Project 下的负责类型转换、类型验证的模块.

NEPattern 旨在提供一种简单的方式, 使得开发者可以在不了解正则表达式的情况下, 也能够轻松地进行类型转换与类型验证.

• 通过传入的 converter 和 validator 等实现了高效的类型转化与类型验证功能
• 提供了多种预置的实例, 例如常见的 INT FLOAT BOOL 等
• 提供了良好的 typing 支持, 使得开发者可以传入大多数 typing 模块中的类型:

from nepattern import parser

pat = parser(list[int])
assert pat.validate([1, 2, 3]).success

• NEPattern 引入了 Patterns 与 create_local_patterns 等函数, 使得开发者可以自由的控制当前环境下的 Pattern 实例

from nepattern import BasePattern

pat = Pattern(str).accept(int).convert(lambda _, x: str(x))
assert pat.execute(13).success
assert pat.execute(42).value() == '42'
assert not pat << 13.0

安装

pdm

pdm add nepattern

poetry

poetry add nepattern

pip

pip install nepattern

构造

一般而言，我们通过 nepattern.Pattern 来构造一个 NEPattern 实例。

from nepattern import Pattern

pat = Pattern(str).accept(int).convert(lambda _, x: str(x))

assert pat.execute("42").success

与 v0 版本不同，v1 版本的 NEPattern 不再显式声明匹配模式，而是通过调用 Pattern 的方法来自定义匹配过程。

具体而言：

from nepattern import Pattern

pat = Pattern(origin, alias)  # 构造一个 Pattern 实例, origin 为目标类型, alias 为别名
pat.accept(int)  # 设置可接受的类型为 int
pat.pre_convert(lambda x: x > 0)  # 在转换前执行的验证函数 `输入值大于 0`
pat.convert(lambda _, x: str(x))  # 设置转换函数为 `将传入的数字转换为字符串`
pat.post_convert(lambda x: x.isdigit())  # 在转换后执行的验证函数 `转换后的字符串仅包含数字`

assert pat.execute(42).success

on 方法

TIP

v0 版本的 BasePattern.of 方法在 v1 版本中应直接使用 Pattern 构造函数: Pattern(int)

Pattern.on 方法可以快捷创建一个只允许指定对象通过的 pattern:

pat = Pattern.on(123)
assert pat.execute(123).value() == 123
assert pat.execute(124).failed

regex_match 方法

Pattern.regex_match 方法可以快捷构造一个使用正则表达式匹配的 Pattern 实例。

from nepattern import Pattern

pat = Pattern.regex_match(r"\d+")
assert pat.validate("42").success
assert pat.validate("abc").failed

其等同于

pat = Pattern().accept(str).pre_convert(lambda x: re.match(r"\d+", x))

该模式下，即使正则表达式内声明了捕获组，Pattern 的返回值也只会是整个字符串。

regex_convert 方法

Pattern.regex_convert 方法可以快捷构造一个使用正则表达式匹配并进行类型转换的 Pattern 实例。

from nepattern import Pattern

pat = Pattern.regex_convert(r"\d+", int, lambda mat: int(mat[0]))
assert pat.validate("42").result() == 42
assert pat.validate("abc").failed

其等同于

pat = Pattern().accept(str).pre_convert(lambda x: re.match(r"\d+", x)).convert(lambda _, x: int(x))  # 实际情况下，匹配和转换都是在 convert 中完成的

regex_convert 额外有一个 allow_origin 参数，指定当输入类型不是字符串，但符合 origin 时，是否直接作为结果返回

pat = Pattern.regex_convert(r"\d+", int, lambda mat: int(mat[0]), allow_origin=True)
assert pat.validate(42).result() == 42