From fa388eec6258b399b719eea7b18a24266e7121ec Mon Sep 17 00:00:00 2001 From: Richard Chien Date: Fri, 22 Feb 2019 17:50:29 +0800 Subject: [PATCH] Update docs --- docs/api.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++- docs/changelog.md | 7 +++++ 2 files changed, 84 insertions(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index 179b3b90..2b83d814 100644 --- a/docs/api.md +++ b/docs/api.md @@ -335,6 +335,58 @@ sidebar: auto 设置更亲切的默认错误提示。 +### `MAX_VALIDATION_FAILURES` + +- **类型:** `int` + +- **默认值:** `3` + +- **说明:** + + 命令参数验证允许的最大失败次数，用户输入错误达到这个次数之后，将会提示用户输入错误太多次，并结束命令会话。 + + 设置为 `0` 将不会检查验证失败次数。 + +### `TOO_MANY_VALIDATION_FAILURES_EXPRESSION` + +- **类型:** `Expression_T` + +- **默认值:** `'您输入错误太多次啦，如需重试，请重新触发本功能'` + +- **说明:** + + 命令参数验证失败达到 `MAX_VALIDATION_FAILURES` 次之后，向用户发送的提示。 + +- **用法:** + + ```python + TOO_MANY_VALIDATION_FAILURES_EXPRESSION = ( + '你输错太多次啦，需要的时候再叫我吧', + '你输错太多次了，建议先看看使用帮助哦～', + ) + ``` + +### `SESSION_CANCEL_EXPRESSION` + +- **类型:** `Expression_T` + +- **默认值:** `'好的'` + +- **说明:** + + `nonebot.command.argfilter.controllers.handle_cancellation()` 控制器在用户发送了 `算了`、`取消` 等取消指令后，结束当前命令会话时，向用户发送的提示。 + +- **用法:** + + ```python + SESSION_CANCEL_EXPRESSION = ( + '好的', + '好的吧', + '好吧，那奶茶就不打扰啦', + '那奶茶先不打扰小主人啦', + ) + ``` + ### `APSCHEDULER_CONFIG` - **类型:** `Dict[str, Any]` @@ -1251,7 +1303,7 @@ sidebar: auto - `name: Union[str, CommandName_T]`: 命令名，如果传入的是字符串则会自动转为元组 - `aliases: Iterable[str]`: 命令别名 - `permission: int`: 命令所需要的权限，不满足权限的用户将无法触发该命令 - - `only_to_me: bool`: 是否只响应确定是在和「我」（机器人）说话的命令（在开头或结尾 @ 了机器人） + - `only_to_me: bool`: 是否只响应确定是在和「我」（机器人）说话的命令（在开头或结尾 @ 了机器人，或在开头称呼了机器人昵称） - `privileged: bool`: 是否特权命令，若是，则无论当前是否有命令会话正在运行，都会运行该命令，但运行不会覆盖已有会话，也不会保留新创建的会话 - `shell_like: bool`: 是否使用类 shell 语法，若是，则会自动使用 `shlex` 模块进行分割（无需手动编写参数解析器），分割后的参数列表放入 `session.args['argv']` @@ -1510,6 +1562,7 @@ sidebar: auto 'time', prompt='你需要我在什么时间提醒你呢？', arg_filters=[ extractors.extract_text, # 取纯文本部分 + controllers.handle_cancellation(session), # 处理用户可能的取消指令 str.strip, # 去掉两边空白字符 # 正则匹配输入格式 validators.match_regex(r'^\d{4}-\d{2}-\d{2}$', '格式不对啦，请重新输入') @@ -1674,6 +1727,7 @@ sidebar: auto - 修剪器，将用户输入的原始参数内容进行适当修建，例如 `str.strip` 可以去掉两遍的空白字符 - 验证器，验证参数的格式、长度等是否符合要求，`validators` 子模块中提供了一些常用验证器 - 转换器，将参数进行类型或格式上的转换，例如 `int` 可以将字符串转换成整数，`converters` 子模块中提供了一些常用转换器 +- 控制器，根据用户输入或当前会话状态对会话进行相关控制，例如当用户发送 `算了` 时停止当前会话，`controllers` 子模块中提供了一些常用控制器 ### _class_ `ValidateError` @@ -1838,6 +1892,28 @@ session.get('arg1', prompt='请输入 arg1：', - **输出类型:** `List[str]` +## `nonebot.command.argfilter.controllers` 模块 + +提供几种常用的控制器。 + +这些验证器通常需要提供一些参数进行一次调用，返回的结果才是真正的验证器，其中的技巧在于通过闭包使要控制的对象能够被内部函数访问。 + +### `handle_cancellation(session)` + +- **说明:** + + 在用户发送 `算了`、`不用了`、`取消吧`、`停` 之类的话的时候，结束当前传入的命令会话（调用 `session.finish()`），并发送配置项 `SESSION_CANCEL_EXPRESSION` 所填的内容。 + + 如果不是上述取消指令，则将输入原样输出。 + +- **参数:** + + - `session: CommandSession`: 要控制的命令会话 + +- **输入类型:** `Any` + +- **输出类型:** `Any` + ## `nonebot.natural_language` 模块 ### _decorator_ `on_natural_language(keywords=None, *, permission=EVERYBODY, only_to_me=True, only_short_message=True, allow_empty_message=False)` diff --git a/docs/changelog.md b/docs/changelog.md index 949ba532..91598c4d 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -4,6 +4,13 @@ sidebar: auto # 更新日志 +## v1.3.0 + +- 允许机器人昵称和消息主体之间不使用空格或逗号分隔，即支持 `奶茶帮我查下天气` 这种用法 +- 在处理命令之前检查机器人昵称，即在不编写自然语言处理器的情况下可以通过 `奶茶，echo 喵` 触发 `echo` 命令，而不再强制需要 at，其它命令同理 +- 新增一种命令参数过滤器——控制器，在 `nonebot.command.argfilter.controllers` 模块，用于在过滤命令参数时对命令会话进行控制，内置了 `handle_cancellation()` 控制器允许用户取消正在进行的命令 +- 新增命令参数验证失败次数的检查，可通过配置项 `MAX_VALIDATION_FAILURES` 和 `TOO_MANY_VALIDATION_FAILURES_EXPRESSION` 来配置最大失败次数和失败过多后的提示 + ## v1.2.3 - 修复 `nonebot.scheduler` 过早启动导致使用 Hypercorn 部署时计划任务无法运行的问题