From 1527fb55f50c672ee4ef4cfadf9f1cf517a5d1a5 Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Sat, 20 Mar 2021 15:41:50 +0800 Subject: [PATCH] :bulb: update handler docstring --- docs/.vuepress/config.js | 4 ++ docs/api/README.md | 3 ++ docs/api/handler.md | 111 +++++++++++++++++++++++++++++++++++++++ docs_build/README.rst | 1 + docs_build/handler.rst | 13 +++++ nonebot/handler.py | 53 ++++++++++++++++--- nonebot/matcher.py | 2 +- 7 files changed, 179 insertions(+), 8 deletions(-) create mode 100644 docs/api/handler.md create mode 100644 docs_build/handler.rst diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index c2efeb3e..fdfac5b0 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -166,6 +166,10 @@ module.exports = context => ({ title: "nonebot.matcher 模块", path: "matcher" }, + { + title: "nonebot.handler 模块", + path: "handler" + }, { title: "nonebot.rule 模块", path: "rule" diff --git a/docs/api/README.md b/docs/api/README.md index e12dd0ff..3d5a6497 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -19,6 +19,9 @@ * [nonebot.matcher](matcher.html) + * [nonebot.handler](handler.html) + + * [nonebot.rule](rule.html) diff --git a/docs/api/handler.md b/docs/api/handler.md new file mode 100644 index 00000000..dc2ab74f --- /dev/null +++ b/docs/api/handler.md @@ -0,0 +1,111 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.handler 模块 + +## 事件处理函数 + +该模块实现事件处理函数的封装，以实现动态参数等功能。 + + +## _class_ `Handler` + +基类：`object` + +事件处理函数类 + + +### `__init__(func)` + +装饰事件处理函数以便根据动态参数运行 + + +### `func` + + +* **类型** + + `T_Handler` + + + +* **说明** + + 事件处理函数 + + + +### `signature` + + +* **类型** + + `inspect.Signature` + + + +* **说明** + + 事件处理函数签名 + + + +### _property_ `bot_type` + + +* **类型** + + `Union[Type["Bot"], inspect.Parameter.empty]` + + + +* **说明** + + 事件处理函数接受的 Bot 对象类型 + + + +### _property_ `event_type` + + +* **类型** + + `Optional[Union[Type[Event], inspect.Parameter.empty]]` + + + +* **说明** + + 事件处理函数接受的 event 类型 / 不需要 event 参数 + + + +### _property_ `state_type` + + +* **类型** + + `Optional[Union[T_State, inspect.Parameter.empty]]` + + + +* **说明** + + 事件处理函数是否接受 state 参数 + + + +### _property_ `matcher_type` + + +* **类型** + + `Optional[Union[Type["Matcher"], inspect.Parameter.empty]]` + + + +* **说明** + + 事件处理函数是否接受 matcher 参数 diff --git a/docs_build/README.rst b/docs_build/README.rst index 0e029d9b..745fc781 100644 --- a/docs_build/README.rst +++ b/docs_build/README.rst @@ -7,6 +7,7 @@ NoneBot Api Reference - `nonebot.plugin `_ - `nonebot.message `_ - `nonebot.matcher `_ + - `nonebot.handler `_ - `nonebot.rule `_ - `nonebot.permission `_ - `nonebot.log `_ diff --git a/docs_build/handler.rst b/docs_build/handler.rst new file mode 100644 index 00000000..d7376b97 --- /dev/null +++ b/docs_build/handler.rst @@ -0,0 +1,13 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +NoneBot.handler 模块 +==================== + +.. automodule:: nonebot.handler + :members: + :private-members: + :special-members: __init__ + :show-inheritance: diff --git a/nonebot/handler.py b/nonebot/handler.py index 946b9fe6..366e0bfc 100644 --- a/nonebot/handler.py +++ b/nonebot/handler.py @@ -6,7 +6,6 @@ """ import inspect -from typing_extensions import Literal from typing import Any, List, Dict, Type, Union, Optional, TYPE_CHECKING from typing import ForwardRef, _eval_type # type: ignore @@ -19,13 +18,28 @@ if TYPE_CHECKING: class HandlerMeta(type): - ... + if TYPE_CHECKING: + func: T_Handler + signature: inspect.Signature + bot_type: Type["Bot"] + event_type: Optional[Type["Event"]] + state_type: Optional[T_State] + matcher_type: Optional[Type["Matcher"]] + + def __repr__(self) -> str: + return (f"") + + def __str__(self) -> str: + return self.__repr__() class Handler(metaclass=HandlerMeta): """事件处理函数类""" def __init__(self, func: T_Handler): + """装饰事件处理函数以便根据动态参数运行""" self.func: T_Handler = func """ :类型: ``T_Handler`` @@ -37,6 +51,14 @@ class Handler(metaclass=HandlerMeta): :说明: 事件处理函数签名 """ + def __repr__(self) -> str: + return (f"") + + def __str__(self) -> str: + return self.__repr__() + async def __call__(self, matcher: "Matcher", bot: "Bot", event: "Event", state: T_State): params = { @@ -65,23 +87,40 @@ class Handler(metaclass=HandlerMeta): **{k: v for k, v in args.items() if params[k] is not None}) @property - def bot_type(self) -> Type["Bot"]: + def bot_type(self) -> Union[Type["Bot"], inspect.Parameter.empty]: + """ + :类型: ``Union[Type["Bot"], inspect.Parameter.empty]`` + :说明: 事件处理函数接受的 Bot 对象类型""" return self.signature.parameters["bot"].annotation @property - def event_type(self) -> Optional[Type["Event"]]: + def event_type( + self) -> Optional[Union[Type["Event"], inspect.Parameter.empty]]: + """ + :类型: ``Optional[Union[Type[Event], inspect.Parameter.empty]]`` + :说明: 事件处理函数接受的 event 类型 / 不需要 event 参数 + """ if "event" not in self.signature.parameters: return None return self.signature.parameters["event"].annotation @property - def state_type(self) -> Optional[T_State]: + def state_type(self) -> Optional[Union[T_State, inspect.Parameter.empty]]: + """ + :类型: ``Optional[Union[T_State, inspect.Parameter.empty]]`` + :说明: 事件处理函数是否接受 state 参数 + """ if "state" not in self.signature.parameters: return None return self.signature.parameters["state"].annotation @property - def matcher_type(self) -> Optional[Type["Matcher"]]: + def matcher_type( + self) -> Optional[Union[Type["Matcher"], inspect.Parameter.empty]]: + """ + :类型: ``Optional[Union[Type["Matcher"], inspect.Parameter.empty]]`` + :说明: 事件处理函数是否接受 matcher 参数 + """ if "matcher" not in self.signature.parameters: return None return self.signature.parameters["matcher"].annotation @@ -101,7 +140,7 @@ class Handler(metaclass=HandlerMeta): def update_signature( self, **kwargs: Union[None, Type["Bot"], Type["Event"], Type["Matcher"], - T_State] + T_State, inspect.Parameter.empty] ) -> None: params: List[inspect.Parameter] = [] for param in ["bot", "event", "state", "matcher"]: diff --git a/nonebot/matcher.py b/nonebot/matcher.py index 2aac333c..d59b8871 100644 --- a/nonebot/matcher.py +++ b/nonebot/matcher.py @@ -50,7 +50,7 @@ class MatcherMeta(type): f"temp={self.temp}>") def __str__(self) -> str: - return repr(self) + return self.__repr__() class Matcher(metaclass=MatcherMeta):