From c8369f599f79edcc2ba805fdbabd4b7907014379 Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Mon, 24 Jan 2022 20:32:46 +0800 Subject: [PATCH] :memo: add configuration and matcher operation --- website/docs/tutorial/configuration.md | 58 +++++++++- website/docs/tutorial/custom-logger.md | 2 + .../docs/tutorial/plugin/create-handler.md | 79 ++++++++++++- .../docs/tutorial/plugin/matcher-operation.md | 109 ++++++++++++++++++ 4 files changed, 245 insertions(+), 3 deletions(-) diff --git a/website/docs/tutorial/configuration.md b/website/docs/tutorial/configuration.md index 78d718a6..1e558fcc 100644 --- a/website/docs/tutorial/configuration.md +++ b/website/docs/tutorial/configuration.md @@ -181,4 +181,60 @@ LOG_LEVEL=INFO 日志等级名称应为大写，如 `INFO`。 ::: - +### API Timeout + +- **类型**: `Optional[float]` +- **默认值**: `30.0` + +API 请求超时时间，单位为秒。 + +```env +API_TIMEOUT=30.0 +``` + +### SuperUsers + +- **类型**: `Set[str]` +- **默认值**: `set()` + +机器人超级用户，可以使用权限 {ref}`nonebot.permission.SUPERUSER`。 + +```env +SUPERUSERS=["1234567890"] +``` + +### Nickname + +- **类型**: `Set[str]` +- **默认值**: `set()` + +机器人昵称，通常协议适配器会根据用户是否 @user 或者是否以机器人昵称开头来判断是否是向机器人发送的消息。 + +```env +NICKNAME=["bot"] +``` + +### Command Start 和 Command Separator + +- **类型**: `Set[str]` +- **默认值**: + - Command Start: `{"/"}` + - Command Separator: `{"."}` + +命令消息的起始符和分隔符。用于 {ref}`nonebot.rule.command` 规则。 + +```env +COMMAND_START={"/", "!"} +COMMAND_SEP={".", "/"} +``` + +### Session Expire Timeout + +- **类型**: `timedelta` +- **默认值**: `timedelta(minutes=2)` + +用户会话超时时间，配置格式参考 [`Pydantic Field`](https://pydantic-docs.helpmanual.io/usage/types/#datetime-types) 。 + +```env +SESSION_EXPIRE_TIMEOUT=120 +``` diff --git a/website/docs/tutorial/custom-logger.md b/website/docs/tutorial/custom-logger.md index 649e42a0..ef963971 100644 --- a/website/docs/tutorial/custom-logger.md +++ b/website/docs/tutorial/custom-logger.md @@ -4,3 +4,5 @@ description: 修改日志级别与输出 --- # 自定义日志 + + diff --git a/website/docs/tutorial/plugin/create-handler.md b/website/docs/tutorial/plugin/create-handler.md index a0d344a9..15ecfdf6 100644 --- a/website/docs/tutorial/plugin/create-handler.md +++ b/website/docs/tutorial/plugin/create-handler.md @@ -119,6 +119,8 @@ matcher = on_message( ### Bot +获取当前事件的 Bot 对象。 + ```python {7-9} from typing import Union @@ -133,6 +135,8 @@ async def _(bot): ... # 兼容性处理 ### Event +获取当前事件。 + ```python {6-8} from typing import Union @@ -146,6 +150,8 @@ async def _(event): ... # 兼容性处理 ### EventType +获取当前事件的类型。 + ```python {3} from nonebot.params import EventType @@ -154,6 +160,8 @@ async def _(foo: str = EventType()): ... ### EventMessage +获取当前事件的消息。 + ```python {4} from nonebot.adapters import Message from nonebot.params import EventMessage @@ -163,6 +171,8 @@ async def _(foo: str = EventMessage()): ... ### EventPlainText +获取当前事件的消息纯文本部分。 + ```python {3} from nonebot.params import EventPlainText @@ -171,6 +181,8 @@ async def _(foo: str = EventPlainText()): ... ### EventToMe +获取当前事件是否与机器人相关。 + ```python {3} from nonebot.params import EventToMe @@ -179,15 +191,18 @@ async def _(foo: bool = EventToMe()): ... ### State +获取当前事件处理上下文状态。 + ```python {4} -from nonebot.params import State from nonebot.typing import T_State -async def _(foo: T_State = State()): ... +async def _(foo: T_State): ... ``` ### Command +获取当前命令型消息的元组形式命令名。 + ```python {7} from nonebot import on_command from nonebot.params import Command @@ -198,8 +213,32 @@ matcher = on_command("cmd") async def _(foo: Tuple[str, ...] = Command()): ... ``` +:::tip 提示 +命令详情只能在首次接收到命令型消息时获取，如果在事件处理后续流程中获取，则会获取到不同的值。 +::: + +### RawCommand + +获取当前命令型消息的文本形式命令名。 + +```python {7} +from nonebot import on_command +from nonebot.params import RawCommand + +matcher = on_command("cmd") + +@matcher.handle() +async def _(foo: str = RawCommand()): ... +``` + +:::tip 提示 +命令详情只能在首次接收到命令型消息时获取，如果在事件处理后续流程中获取，则会获取到不同的值。 +::: + ### CommandArg +获取命令型消息命令后跟随的参数。 + ```python {8} from nonebot import on_command from nonebot.adapters import Message @@ -211,8 +250,20 @@ matcher = on_command("cmd") async def _(foo: Message = CommandArg()): ... ``` +:::tip 提示 +命令详情只能在首次接收到命令型消息时获取，如果在事件处理后续流程中获取，则会获取到不同的值。 +::: + ### ShellCommandArgs +获取 shell 命令解析后的参数。 + +:::tip 提示 +如果参数解析失败，则为 {ref}`nonebot.exception.ParserExit` 异常，并携带错误码与错误信息。 + +由于 `ArgumentParser` 在解析到 `--help` 参数时也会抛出异常，这种情况下错误码为 `0` 且错误信息即为帮助信息。 +::: + ```python {7} from nonebot import on_shell_command from nonebot.params import ShellCommandArgs @@ -225,6 +276,8 @@ async def _(foo: Dict[str, Any] = ShellCommandArgs()): ... ### ShellCommandArgv +获取 shell 命令解析前的参数列表。 + ```python {7} from nonebot import on_shell_command from nonebot.params import ShellCommandArgs @@ -237,6 +290,8 @@ async def _(foo: List[str] = ShellCommandArgv()): ... ### RegexMatched +获取正则匹配结果。 + ```python {7} from nonebot import on_regex from nonebot.params import RegexMatched @@ -249,6 +304,8 @@ async def _(foo: str = RegexMatched()): ... ### RegexGroup +获取正则匹配结果的 group 元组。 + ```python {7} from nonebot import on_regex from nonebot.params import RegexGroup @@ -261,6 +318,8 @@ async def _(foo: Tuple[Any, ...] = RegexGroup()): ... ### RegexDict +获取正则匹配结果的 group 字典。 + ```python {7} from nonebot import on_regex from nonebot.params import RegexDict @@ -273,6 +332,8 @@ async def _(foo: Dict[str, Any] = RegexDict()): ... ### Matcher +获取当前事件响应器实例。 + ```python {7} from nonebot import on_message from nonebot.matcher import Matcher @@ -285,6 +346,8 @@ async def _(matcher: Matcher): ... ### Received +获取某次 `receive` 接收的事件。 + ```python {8} from nonebot import on_message from nonebot.adapters import Event @@ -298,6 +361,8 @@ async def _(foo: Event = Received("id")): ... ### LastReceived +获取最近一次 `receive` 接收的事件。 + ```python {8} from nonebot import on_message from nonebot.adapters import Event @@ -311,6 +376,8 @@ async def _(foo: Event = LastReceived()): ... ### Arg +获取某次 `got` 接收的参数。 + ```python {8-9} from nonebot.params import Arg from nonebot import on_message @@ -325,6 +392,8 @@ async def _(foo: Message = Arg("key")): ... ### ArgStr +获取某次 `got` 接收的参数，并转换为字符串。 + ```python {7-8} from nonebot import on_message from nonebot.params import ArgStr @@ -338,6 +407,8 @@ async def _(foo: str = ArgStr("key")): ... ### ArgPlainText +获取某次 `got` 接收的参数的纯文本部分。 + ```python {7-8} from nonebot import on_message from nonebot.params import ArgPlainText @@ -351,6 +422,8 @@ async def _(foo: str = ArgPlainText("key")): ... ### Exception +获取事件响应器运行中抛出的异常。 + ```python {4} from nonebot.message import run_postprocessor @@ -360,6 +433,8 @@ async def _(e: Exception): ... ### Default +带有默认值的参数，便于复用依赖。 + ```python {1} async def _(foo="bar"): ... ``` diff --git a/website/docs/tutorial/plugin/matcher-operation.md b/website/docs/tutorial/plugin/matcher-operation.md index 0d8d6551..3803d26b 100644 --- a/website/docs/tutorial/plugin/matcher-operation.md +++ b/website/docs/tutorial/plugin/matcher-operation.md @@ -10,28 +10,137 @@ options: # 事件响应器操作 +在事件处理流程中，我们可以使用事件响应器操作来进行一些交互或改变事件处理流程。 + ## send +向用户回复一条消息。回复的方式或途径由协议适配器自行实现。 + +可以是 `str`, {ref}`nonebot.adapters._message.Message`, {ref}`nonebot.adapters._message.MessageSegment` 或 {ref}`nonebot.adapters._template.MessageTemplate`。 + +这个操作等同于使用 `bot.send(event, message, **kwargs)` 但不需要自行传入 `event`。 + +```python {3} +@matcher.handle() +async def _(): + await matcher.send("Hello world!") +``` + ## finish +向用户回复一条消息（可选），并立即结束当前事件的整个处理流程。 + +参数与 [`send`](#send) 相同。 + +```python {3} +@matcher.handle() +async def _(): + await matcher.finish("Hello world!") + # something never run + ... +``` + ## pause +向用户回复一条消息（可选），并立即当前事件处理依赖并等待接收一个新的事件后进入下一个事件处理依赖。 + +类似于 `receive` 的行为但可以根据事件来决定是否接收新的事件。 + +```python {4} +@matcher.handle() +async def _(): + if serious: + await matcher.pause("Confirm?") + +@matcher.handle() +async def _(): + ... +``` + ## reject +向用户回复一条消息（可选），并立即当前事件处理依赖并等待接收一个新的事件后再次执行当前事件处理依赖。 + +通常用于拒绝当前 `receive` 接收的事件或 `got` 接收的参数（如：不符合格式或标准）。 + +```python {4} +@matcher.got("arg") +async def _(arg: str = ArgPlainText()): + if not is_valid(arg): + await matcher.reject("Invalid arg!") +``` + ## reject_arg +向用户回复一条消息（可选），并立即当前事件处理依赖并等待接收一个新的事件后再次执行当前事件处理依赖。 + +用于拒绝指定 `got` 接收的参数，通常在嵌套装饰器时使用。 + +```python {4} +@matcher.got("a") +@matcher.got("b") +async def _(a: str = ArgPlainText(), b: str = ArgPlainText()): + if a not in b: + await matcher.reject_arg("a", "Invalid a!") +``` + ## reject_receive +向用户回复一条消息（可选），并立即当前事件处理依赖并等待接收一个新的事件后再次执行当前事件处理依赖。 + +用于拒绝指定 `receive` 接收的事件，通常在嵌套装饰器时使用。 + +```python {4} +@matcher.receive("a") +@matcher.receive("b") +async def _(a: Event = Received("a"), b: Event = Received("b")): + if a.get_user_id() != b.get_user_id(): + await matcher.reject_receive("a") +``` + ## skip +立即结束当前事件处理依赖，进入下一个事件处理依赖。 + +通常在子依赖中使用，用于跳过当前事件处理依赖的执行。 + +```python {2} +async def dependency(matcher: Matcher): + matcher.skip() + + +@matcher.handle() +async def _(sub=Depends(dependency)): + # never run + ... +``` + ## get_receive +获取一个 `receive` 接收的事件。 + ## set_receive +设置/覆盖一个 `receive` 接收的事件。 + ## get_last_receive +获取最近一次 `receive` 接收的事件。 + ## get_arg +获取一个 `got` 接收的参数。 + ## set_arg +设置/覆盖一个 `got` 接收的参数。 + ## stop_propagation + +阻止事件向更低优先级的事件响应器传播。 + +```python +@foo.handle() +async def _(matcher: Matcher): + matcher.stop_propagation() +```