From 727eef9a340443adf098d15e76a34d0ec0ff8148 Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Tue, 6 Oct 2020 17:03:05 +0800 Subject: [PATCH] :bulb: add matcher docstring --- docs/api/adapters/README.md | 7 +- docs/api/matcher.md | 163 ++++++++++++++++++++++++++++++++++- docs_build/matcher.rst | 1 + nonebot/adapters/__init__.py | 7 +- nonebot/matcher.py | 106 ++++++++++++++++++----- 5 files changed, 255 insertions(+), 29 deletions(-) diff --git a/docs/api/adapters/README.md b/docs/api/adapters/README.md index 2b386503..f3f937ec 100644 --- a/docs/api/adapters/README.md +++ b/docs/api/adapters/README.md @@ -113,7 +113,7 @@ await bot.send_msg(message="hello world") ``` -### _abstract async_ `send(*args, **kwargs)` +### _abstract async_ `send(event, message, **kwargs)` * **说明** @@ -125,7 +125,10 @@ await bot.send_msg(message="hello world") * **参数** - * `*args` + * `event: Event`: 上报事件 + + + * `message: Union[str, Message, MessageSegment]`: 要发送的消息 * `**kwargs` diff --git a/docs/api/matcher.md b/docs/api/matcher.md index d0f5199d..c1176030 100644 --- a/docs/api/matcher.md +++ b/docs/api/matcher.md @@ -182,6 +182,11 @@ sidebarDepth: 0 +### `__init__()` + +实例化 Matcher 以便运行 + + ### `handlers` @@ -307,7 +312,7 @@ sidebarDepth: 0 * **说明** - 用于装饰一个函数来更改当前事件响应器的默认参数解析函数 + 装饰一个函数来更改当前事件响应器的默认参数解析函数 @@ -320,9 +325,161 @@ sidebarDepth: 0 ### _classmethod_ `handle()` -直接处理消息事件 + +* **说明** + + 装饰一个函数来向事件响应器直接添加一个处理函数 + + + +* **参数** + + + * 无 + ### _classmethod_ `receive()` -接收一条新消息并处理 + +* **说明** + + 装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数 + + + +* **参数** + + + * 无 + + + +### _classmethod_ `got(key, prompt=None, args_parser=None)` + + +* **说明** + + 装饰一个函数来指示 NoneBot 当要获取的 `key` 不存在时接收用户新的一条消息并经过 `ArgsParser` 处理后再运行该函数，如果 `key` 已存在则直接继续运行 + + + +* **参数** + + + * `key: str`: 参数名 + + + * `prompt: Optional[Union[str, Message, MessageSegment]]`: 在参数不存在时向用户发送的消息 + + + * `args_parser: Optional[ArgsParser]`: 可选参数解析函数，空则使用默认解析函数 + + + +### _async classmethod_ `send(message)` + + +* **说明** + + 发送一条消息给当前交互用户 + + + +* **参数** + + + * `message: Union[str, Message, MessageSegment]`: 消息内容 + + + +### _async classmethod_ `finish(message=None)` + + +* **说明** + + 发送一条消息给当前交互用户并结束当前事件响应器 + + + +* **参数** + + + * `message: Union[str, Message, MessageSegment]`: 消息内容 + + + +### _async classmethod_ `pause(prompt=None)` + + +* **说明** + + 发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数 + + + +* **参数** + + + * `prompt: Union[str, Message, MessageSegment]`: 消息内容 + + + +### _async classmethod_ `reject(prompt=None)` + + +* **说明** + + 发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后重新运行当前处理函数 + + + +* **参数** + + + * `prompt: Union[str, Message, MessageSegment]`: 消息内容 + + + +## _class_ `MatcherGroup` + +基类：`object` + +事件响应器组合，统一管理。用法同 `Matcher` + + +### `__init__(type_='', rule=None, permission=None, handlers=None, temp=False, priority=1, block=False, *, module=None, default_state=None, expire_time=None)` + + +* **说明** + + 创建一个事件响应器组合，参数为默认值，与 `Matcher.new` 一致 + + + +### `matchers` + + +* **类型** + + `List[Type[Matcher]]` + + + +* **说明** + + 组内事件响应器列表 + + + +### `new(type_='', rule=None, permission=None, handlers=None, temp=False, priority=1, block=False, *, module=None, default_state=None, expire_time=None)` + + +* **说明** + + 在组中创建一个新的事件响应器，参数留空则使用组合默认值 + + +:::danger 警告 +如果使用 handlers 参数覆盖组合默认值则该事件响应器不会随组合一起添加新的事件处理函数 +::: diff --git a/docs_build/matcher.rst b/docs_build/matcher.rst index ef45dfe8..edc42bfe 100644 --- a/docs_build/matcher.rst +++ b/docs_build/matcher.rst @@ -9,4 +9,5 @@ NoneBot.matcher 模块 .. automodule:: nonebot.matcher :members: :private-members: + :special-members: __init__ :show-inheritance: diff --git a/nonebot/adapters/__init__.py b/nonebot/adapters/__init__.py index d4635181..78177825 100644 --- a/nonebot/adapters/__init__.py +++ b/nonebot/adapters/__init__.py @@ -85,12 +85,15 @@ class BaseBot(abc.ABC): raise NotImplementedError @abc.abstractmethod - async def send(self, *args, **kwargs): + async def send(self, event: "BaseEvent", + message: Union[str, "BaseMessage", + "BaseMessageSegment"], **kwargs): """ :说明: 调用机器人基础发送消息接口 :参数: - * ``*args`` + * ``event: Event``: 上报事件 + * ``message: Union[str, Message, MessageSegment]``: 要发送的消息 * ``**kwargs`` """ raise NotImplementedError diff --git a/nonebot/matcher.py b/nonebot/matcher.py index 04dea30e..9f0d7a9d 100644 --- a/nonebot/matcher.py +++ b/nonebot/matcher.py @@ -196,7 +196,7 @@ class Matcher(metaclass=MatcherMeta): def args_parser(cls, func: ArgsParser) -> ArgsParser: """ :说明: - 用于装饰一个函数来更改当前事件响应器的默认参数解析函数 + 装饰一个函数来更改当前事件响应器的默认参数解析函数 :参数: * ``func: ArgsParser``: 参数解析函数 """ @@ -205,7 +205,12 @@ class Matcher(metaclass=MatcherMeta): @classmethod def handle(cls) -> Callable[[Handler], Handler]: - """直接处理消息事件""" + """ + :说明: + 装饰一个函数来向事件响应器直接添加一个处理函数 + :参数: + * 无 + """ def _decorator(func: Handler) -> Handler: cls.handlers.append(func) @@ -215,7 +220,12 @@ class Matcher(metaclass=MatcherMeta): @classmethod def receive(cls) -> Callable[[Handler], Handler]: - """接收一条新消息并处理""" + """ + :说明: + 装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数 + :参数: + * 无 + """ async def _receive(bot: Bot, event: Event, state: dict) -> NoReturn: raise PausedException @@ -236,9 +246,17 @@ class Matcher(metaclass=MatcherMeta): def got( cls, key: str, - prompt: Optional[str] = None, + prompt: Optional[Union[str, Message, MessageSegment]] = None, args_parser: Optional[ArgsParser] = None ) -> Callable[[Handler], Handler]: + """ + :说明: + 装饰一个函数来指示 NoneBot 当要获取的 ``key`` 不存在时接收用户新的一条消息并经过 ``ArgsParser`` 处理后再运行该函数，如果 ``key`` 已存在则直接继续运行 + :参数: + * ``key: str``: 参数名 + * ``prompt: Optional[Union[str, Message, MessageSegment]]``: 在参数不存在时向用户发送的消息 + * ``args_parser: Optional[ArgsParser]``: 可选参数解析函数，空则使用默认解析函数 + """ async def _key_getter(bot: Bot, event: Event, state: dict): state["_current_key"] = key @@ -281,6 +299,12 @@ class Matcher(metaclass=MatcherMeta): @classmethod async def send(cls, message: Union[str, Message, MessageSegment]): + """ + :说明: + 发送一条消息给当前交互用户 + :参数: + * ``message: Union[str, Message, MessageSegment]``: 消息内容 + """ bot = current_bot.get() event = current_event.get() await bot.send(event=event, message=message) @@ -288,12 +312,18 @@ class Matcher(metaclass=MatcherMeta): @classmethod async def finish( cls, - prompt: Optional[Union[str, Message, - MessageSegment]] = None) -> NoReturn: + message: Optional[Union[str, Message, + MessageSegment]] = None) -> NoReturn: + """ + :说明: + 发送一条消息给当前交互用户并结束当前事件响应器 + :参数: + * ``message: Union[str, Message, MessageSegment]``: 消息内容 + """ bot = current_bot.get() event = current_event.get() - if prompt: - await bot.send(event=event, message=prompt) + if message: + await bot.send(event=event, message=message) raise FinishedException @classmethod @@ -301,6 +331,12 @@ class Matcher(metaclass=MatcherMeta): cls, prompt: Optional[Union[str, Message, MessageSegment]] = None) -> NoReturn: + """ + :说明: + 发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数 + :参数: + * ``prompt: Union[str, Message, MessageSegment]``: 消息内容 + """ bot = current_bot.get() event = current_event.get() if prompt: @@ -312,6 +348,12 @@ class Matcher(metaclass=MatcherMeta): cls, prompt: Optional[Union[str, Message, MessageSegment]] = None) -> NoReturn: + """ + :说明: + 发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后重新运行当前处理函数 + :参数: + * ``prompt: Union[str, Message, MessageSegment]``: 消息内容 + """ bot = current_bot.get() event = current_event.get() if prompt: @@ -369,11 +411,12 @@ class Matcher(metaclass=MatcherMeta): class MatcherGroup: + """事件响应器组合，统一管理。用法同 ``Matcher``""" def __init__(self, type_: str = "", - rule: Rule = Rule(), - permission: Permission = Permission(), + rule: Optional[Rule] = None, + permission: Optional[Permission] = None, handlers: Optional[list] = None, temp: bool = False, priority: int = 1, @@ -382,11 +425,19 @@ class MatcherGroup: module: Optional[str] = None, default_state: Optional[dict] = None, expire_time: Optional[datetime] = None): + """ + :说明: + 创建一个事件响应器组合，参数为默认值，与 ``Matcher.new`` 一致 + """ self.matchers: List[Type[Matcher]] = [] + """ + :类型: ``List[Type[Matcher]]`` + :说明: 组内事件响应器列表 + """ self.type = type_ - self.rule = rule - self.permission = permission + self.rule = rule or Rule() + self.permission = permission or Permission() self.handlers = handlers self.temp = temp self.priority = priority @@ -408,8 +459,8 @@ class MatcherGroup: def new(self, type_: str = "", - rule: Rule = Rule(), - permission: Permission = Permission(), + rule: Optional[Rule] = None, + permission: Optional[Permission] = None, handlers: Optional[list] = None, temp: bool = False, priority: int = 1, @@ -418,6 +469,14 @@ class MatcherGroup: module: Optional[str] = None, default_state: Optional[dict] = None, expire_time: Optional[datetime] = None) -> Type[Matcher]: + """ + :说明: + 在组中创建一个新的事件响应器，参数留空则使用组合默认值 + + \:\:\:danger 警告 + 如果使用 handlers 参数覆盖组合默认值则该事件响应器不会随组合一起添加新的事件处理函数 + \:\:\: + """ matcher = Matcher.new(type_=type_ or self.type, rule=self.rule & rule, permission=permission or self.permission, @@ -438,7 +497,6 @@ class MatcherGroup: return func def handle(self) -> Callable[[Handler], Handler]: - """直接处理消息事件""" def _decorator(func: Handler) -> Handler: self.handlers.append(func) @@ -447,7 +505,6 @@ class MatcherGroup: return _decorator def receive(self) -> Callable[[Handler], Handler]: - """接收一条新消息并处理""" async def _receive(bot: Bot, event: Event, state: dict) -> NoReturn: raise PausedException @@ -510,14 +567,19 @@ class MatcherGroup: return _decorator - async def finish( - self, - prompt: Optional[Union[str, Message, - MessageSegment]] = None) -> NoReturn: + async def send(self, message: Union[str, Message, MessageSegment]): bot = current_bot.get() event = current_event.get() - if prompt: - await bot.send(event=event, message=prompt) + await bot.send(event=event, message=message) + + async def finish( + self, + message: Optional[Union[str, Message, + MessageSegment]] = None) -> NoReturn: + bot = current_bot.get() + event = current_event.get() + if message: + await bot.send(event=event, message=message) raise FinishedException async def pause(