diff --git a/docs/guide/creating-a-handler.md b/docs/guide/creating-a-handler.md index ca65b1a6..56bc11e0 100644 --- a/docs/guide/creating-a-handler.md +++ b/docs/guide/creating-a-handler.md @@ -6,14 +6,14 @@ ```python{1,2,8,9} @weather.handle() -async def handle_first_receive(bot: Bot, event: Event, state: dict): +async def handle_first_receive(bot: Bot, event: Event, state: State): args = str(event.message).strip() # 首次发送命令时跟随的参数,例:/天气 上海,则args为上海 if args: state["city"] = args # 如果用户发送了参数则直接赋值 @weather.got("city", prompt="你想查询哪个城市的天气呢?") -async def handle_city(bot: Bot, event: Event, state: dict): +async def handle_city(bot: Bot, event: Event, state: State): city = state["city"] if city not in ["上海", "北京"]: await weather.reject("你想查询的城市暂不支持,请重新输入!") @@ -53,12 +53,12 @@ async def handle_city(bot: Bot, event: Event, state: dict): ```python @matcher.receive() -async def handle(bot: Bot, event: Event, state: dict): +async def handle(bot: Bot, event: Event, state: State): state["key"] = "hello" @matcher.got("key2", prompt="{key}!") -async def handle2(bot: Bot, event: Event, state: dict): +async def handle2(bot: Bot, event: Event, state: State): pass ``` @@ -69,19 +69,19 @@ async def handle2(bot: Bot, event: Event, state: dict): ```python @matcher.got("key1") @matcher.got("key2") -async def handle(bot: Bot, event: Event, state: dict): +async def handle(bot: Bot, event: Event, state: State): pass ``` ### 事件处理函数参数 -事件处理函数类型为 `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` 。 +事件处理函数类型为 `Callable[[Bot, Event, State], Union[Awaitable[None], Awaitable[NoReturn]]]` 。 参数分别为: -1. [nonebot.typing.Bot](../api/typing.md#bot): 即事件上报连接对应的 Bot 对象,为 BaseBot 的子类。特别注意,此处的类型注释可以替换为指定的 Bot 类型,例如:`nonebot.adapters.cqhttp.Bot`,只有在上报事件的 Bot 类型与类型注释相符时才会执行该处理函数!可用于多平台进行不同的处理。 -2. [nonebot.typing.Event](../api/typing.md#event): 即上报事件对象,可以获取到上报的所有信息。 -3. `state`: 状态字典,可以存储任意的信息,其中还包含一些特殊的值以获取 NoneBot 内部处理时的一些信息,如: +1. [nonebot.adapters.Bot](../api/adapters/#class-bot): 即事件上报连接对应的 Bot 对象,为 BaseBot 的子类。特别注意,此处的类型注释可以替换为指定的 Bot 类型,例如:`nonebot.adapters.cqhttp.Bot`,只有在上报事件的 Bot 类型与类型注释相符时才会执行该处理函数!可用于多平台进行不同的处理。 +2. [nonebot.adapters.Event](../api/adapters/#class-event): 即上报事件对象,可以获取到上报的所有信息。 +3. [state](../api/typing.md#state): 状态字典,可以存储任意的信息,其中还包含一些特殊的值以获取 NoneBot 内部处理时的一些信息,如: - `state["_current_key"]`: 存储当前 `got` 获取的参数名 - `state["_prefix"]`, `state["_suffix"]`: 存储当前 TRIE 匹配的前缀/后缀,可以通过该值获取用户命令的原始命令 @@ -93,10 +93,10 @@ async def handle(bot: Bot, event: Event, state: dict): - `@matcher.args_parser` 装饰器:直接装饰一个函数作为参数处理器 - `got(key, prompt, args_parser)`:直接把函数作为参数传入 -参数处理函数类型为:`Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`,即: +参数处理函数类型为:`Callable[[Bot, Event, State], Union[Awaitable[None], Awaitable[NoReturn]]]`,即: ```python -async def parser(bot: Bot, event: Event, state: dict): +async def parser(bot: Bot, event: Event, state: State): state[state["_current_key"]] = str(event.message) ``` @@ -131,12 +131,12 @@ matcher = on_command("test") # 修改默认参数处理 @matcher.args_parser -async def parse(bot: Bot, event: Event, state: dict): +async def parse(bot: Bot, event: Event, state: State): print(state["_current_key"], ":", str(event.message)) state[state["_current_key"]] = str(event.message) @matcher.handle() -async def first_receive(bot: Bot, event: Event, state: dict): +async def first_receive(bot: Bot, event: Event, state: State): # 获取用户原始命令,如:/test print(state["_prefix"]["raw_command"]) # 处理用户输入参数,如:/test arg1 arg2 @@ -148,7 +148,7 @@ async def first_receive(bot: Bot, event: Event, state: dict): @matcher.got("arg1", prompt="参数?") -async def arg_handle(bot: Bot, event: Event, state: dict): +async def arg_handle(bot: Bot, event: Event, state: State): # 在这里对参数进行验证 if state["arg1"] not in ["allow", "list"]: await matcher.reject("参数不正确!请重新输入") diff --git a/docs/guide/creating-a-matcher.md b/docs/guide/creating-a-matcher.md index b603449a..e505bf0c 100644 --- a/docs/guide/creating-a-matcher.md +++ b/docs/guide/creating-a-matcher.md @@ -7,20 +7,21 @@ ```python from nonebot import on_command from nonebot.rule import to_me +from nonebot.typing import State from nonebot.adapters.cqhttp import Bot, Event weather = on_command("天气", rule=to_me(), priority=5) @weather.handle() -async def handle_first_receive(bot: Bot, event: Event, state: dict): +async def handle_first_receive(bot: Bot, event: Event, state: State): args = str(event.message).strip() # 首次发送命令时跟随的参数,例:/天气 上海,则args为上海 if args: state["city"] = args # 如果用户发送了参数则直接赋值 @weather.got("city", prompt="你想查询哪个城市的天气呢?") -async def handle_city(bot: Bot, event: Event, state: dict): +async def handle_city(bot: Bot, event: Event, state: State): city = state["city"] if city not in ["上海", "北京"]: await weather.reject("你想查询的城市暂不支持,请重新输入!") @@ -115,15 +116,15 @@ rule 的出现使得 nonebot 对事件的响应可以非常自由,nonebot 内 ```python from nonebot.rule import Rule -async def async_checker(bot: Bot, event: Event, state: dict) -> bool: +async def async_checker(bot: Bot, event: Event, state: State) -> bool: return True -def sync_checker(bot: Bot, event: Event, state: dict) -> bool: +def sync_checker(bot: Bot, event: Event, state: State) -> bool: return True def check(arg1, args2): - async def _checker(bot: Bot, event: Event, state: dict) -> bool: + async def _checker(bot: Bot, event: Event, state: State) -> bool: return bool(arg1 + arg2) return Rule(_check) diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 8ed182eb..6a4e4ac5 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -14,7 +14,7 @@ nb create 如果未安装 `nb-cli`,使用你最熟悉的编辑器或 IDE,创建一个名为 `bot.py` 的文件,内容如下: -```python{3,4,7} +```python{4,6,7,10} import nonebot from nonebot.adapters.cqhttp import Bot as CQHTTPBot @@ -32,8 +32,9 @@ if __name__ == "__main__": 在上方 `bot.py` 中,这几行高亮代码将依次: 1. 使用默认配置初始化 NoneBot -2. 加载 NoneBot 内置的插件 -3. 在地址 `127.0.0.1:8080` 运行 NoneBot +2. 加载 NoneBot 内置的 CQHTTP 协议适配组件 +3. 加载 NoneBot 内置的插件 +4. 在地址 `127.0.0.1:8080` 运行 NoneBot 在命令行使用如下命令即可运行这个 NoneBot 实例: diff --git a/nonebot/typing.py b/nonebot/typing.py index be11e1f4..d9d0151f 100644 --- a/nonebot/typing.py +++ b/nonebot/typing.py @@ -102,9 +102,10 @@ Handler = Callable[["Bot", "Event", State], Union[Awaitable[None], Handler 即事件的处理函数。 """ -ArgsParser = Callable[["Bot", "Event", State], Awaitable[None]] +ArgsParser = Callable[["Bot", "Event", State], Union[Awaitable[None], + Awaitable[NoReturn]]] """ -:类型: ``Callable[[Bot, Event, State], Awaitable[None]]`` +:类型: ``Callable[[Bot, Event, State], Union[Awaitable[None], Awaitable[NoReturn]]]`` :说明: