💡 update docstring for several modules

This commit is contained in:
yanyongyu 2020-10-06 02:08:48 +08:00
parent 2e989b5fe1
commit 734d3cd333
13 changed files with 597 additions and 51 deletions

View File

@ -88,21 +88,13 @@ module.exports = context => ({
title: "nonebot 模块", title: "nonebot 模块",
path: "nonebot" path: "nonebot"
}, },
{
title: "nonebot.typing 模块",
path: "typing"
},
{ {
title: "nonebot.config 模块", title: "nonebot.config 模块",
path: "config" path: "config"
}, },
{ {
title: "nonebot.sched 模块", title: "nonebot.matcher 模块",
path: "sched" path: "matcher"
},
{
title: "nonebot.log 模块",
path: "log"
}, },
{ {
title: "nonebot.rule 模块", title: "nonebot.rule 模块",
@ -112,10 +104,22 @@ module.exports = context => ({
title: "nonebot.permission 模块", title: "nonebot.permission 模块",
path: "permission" path: "permission"
}, },
{
title: "nonebot.sched 模块",
path: "sched"
},
{
title: "nonebot.log 模块",
path: "log"
},
{ {
title: "nonebot.utils 模块", title: "nonebot.utils 模块",
path: "utils" path: "utils"
}, },
{
title: "nonebot.typing 模块",
path: "typing"
},
{ {
title: "nonebot.exception 模块", title: "nonebot.exception 模块",
path: "exception" path: "exception"

View File

@ -7,16 +7,10 @@
* [nonebot](nonebot.html) * [nonebot](nonebot.html)
* [nonebot.typing](typing.html)
* [nonebot.config](config.html) * [nonebot.config](config.html)
* [nonebot.sched](sched.html) * [nonebot.matcher](matcher.html)
* [nonebot.log](log.html)
* [nonebot.rule](rule.html) * [nonebot.rule](rule.html)
@ -25,10 +19,22 @@
* [nonebot.permission](permission.html) * [nonebot.permission](permission.html)
* [nonebot.sched](sched.html)
* [nonebot.log](log.html)
* [nonebot.utils](utils.html) * [nonebot.utils](utils.html)
* [nonebot.typing](typing.html)
* [nonebot.exception](exception.html) * [nonebot.exception](exception.html)
* [nonebot.adapters](adapters/)
* [nonebot.adapters.cqhttp](adapters/cqhttp.html) * [nonebot.adapters.cqhttp](adapters/cqhttp.html)

View File

@ -323,10 +323,10 @@ CQHTTP 协议 Event 适配。继承属性参考 [BaseEvent](./#class-baseevent)
### _property_ `sub_type` ### _property_ `sub_type`
* 类型: `str` * 类型: `Optional[str]`
* 说明: 事件类型 * 说明: 事件类型
### _property_ `user_id` ### _property_ `user_id`

328
docs/api/matcher.md Normal file
View File

@ -0,0 +1,328 @@
---
contentSidebar: true
sidebarDepth: 0
---
# NoneBot.matcher 模块
## 事件响应器
该模块实现事件响应器的创建与运行,并提供一些快捷方法来帮助用户更好的与机器人进行 对话 。
## `matchers`
* **类型**
`Dict[int, List[Type[Matcher]]]`
* **说明**
用于存储当前所有的事件响应器
## _class_ `Matcher`
基类:`object`
事件响应器类
### `module`
* **类型**
`Optional[str]`
* **说明**
事件响应器所在模块名称
### `type`
* **类型**
`str`
* **说明**
事件响应器类型
### `rule`
* **类型**
`Rule`
* **说明**
事件响应器匹配规则
### `permission`
* **类型**
`Permission`
* **说明**
事件响应器触发权限
### `priority`
* **类型**
`int`
* **说明**
事件响应器优先级
### `block`
* **类型**
`bool`
* **说明**
事件响应器是否阻止事件传播
### `temp`
* **类型**
`bool`
* **说明**
事件响应器是否为临时
### `expire_time`
* **类型**
`Optional[datetime]`
* **说明**
事件响应器过期时间点
### `_default_state`
* **类型**
`dict`
* **说明**
事件响应器默认状态
### `_default_parser`
* **类型**
`Optional[ArgsParser]`
* **说明**
事件响应器默认参数解析函数
### `handlers`
* **类型**
`List[Handler]`
* **说明**
事件响应器拥有的事件处理函数列表
### _classmethod_ `new(type_='', rule=None, permission=None, handlers=None, temp=False, priority=1, block=False, *, module=None, default_state=None, expire_time=None)`
* **说明**
创建一个新的事件响应器,并存储至 [matchers](#matchers)
* **参数**
* `type_: str`: 事件响应器类型,与 `event.type` 一致时触发,空字符串表示任意
* `rule: Optional[Rule]`: 匹配规则
* `permission: Optional[Permission]`: 权限
* `handlers: Optional[List[Handler]]`: 事件处理函数列表
* `temp: bool`: 是否为临时事件响应器,即触发一次后删除
* `priority: int`: 响应优先级
* `block: bool`: 是否阻止事件向更低优先级的响应器传播
* `module: Optional[str]`: 事件响应器所在模块名称
* `default_state: Optional[dict]`: 默认状态 `state`
* `expire_time: Optional[datetime]`: 事件响应器最终有效时间点,过时即被删除
* **返回**
* `Type[Matcher]`: 新的事件响应器类
### _async classmethod_ `check_perm(bot, event)`
* **说明**
检查是否满足触发权限
* **参数**
* `bot: Bot`: Bot 对象
* `event: Event`: 上报事件
* **返回**
* `bool`: 是否满足权限
### _async classmethod_ `check_rule(bot, event, state)`
* **说明**
检查是否满足匹配规则
* **参数**
* `bot: Bot`: Bot 对象
* `event: Event`: 上报事件
* `state: dict`: 当前状态
* **返回**
* `bool`: 是否满足匹配规则
### _classmethod_ `args_parser(func)`
* **说明**
用于装饰一个函数来更改当前事件响应器的默认参数解析函数
* **参数**
* `func: ArgsParser`: 参数解析函数
### _classmethod_ `handle()`
直接处理消息事件
### _classmethod_ `receive()`
接收一条新消息并处理

View File

@ -7,10 +7,10 @@ sidebarDepth: 0
## 规则 ## 规则
每个 `Matcher` 拥有一个 `Rule` ,其中是 **异步** `RuleChecker` 的集合,只有当所有 `RuleChecker` 检查结果为 `True` 时继续运行。 每个事件响应器 `Matcher` 拥有一个匹配规则 `Rule` ,其中是 **异步** `RuleChecker` 的集合,只有当所有 `RuleChecker` 检查结果为 `True` 时继续运行。
:::tip 提示 :::tip 提示
`RuleChecker` 既可以是 async function 也可以是 sync function `RuleChecker` 既可以是 async function 也可以是 sync function,但在最终会被 `nonebot.utils.run_sync` 转换为 async function
::: :::
@ -120,3 +120,83 @@ Rule(async_function, run_sync(sync_function))
* `msg: str`: 消息结尾字符串 * `msg: str`: 消息结尾字符串
## `keyword(msg)`
* **说明**
匹配消息关键词
* **参数**
* `msg: str`: 关键词
## `command(command)`
* **说明**
命令形式匹配,根据配置里提供的 `command_start`, `command_sep` 判断消息是否为命令。
* **参数**
* `command: Tuples[str, ...]`: 命令内容
* **示例**
使用默认 `command_start`, `command_sep` 配置
命令 `("test",)` 可以匹配:`/test` 开头的消息
命令 `("test", "sub")` 可以匹配”`/test.sub` 开头的消息
:::tip 提示
命令内容与后续消息间无需空格!
:::
## `regex(regex, flags=0)`
* **说明**
根据正则表达式进行匹配
* **参数**
* `regex: str`: 正则表达式
* `flags: Union[int, re.RegexFlag]`: 正则标志
## `to_me()`
* **说明**
通过 `event.to_me` 判断消息是否是发送给机器人
* **参数**
* 无

View File

@ -3,12 +3,14 @@ NoneBot Api Reference
:模块索引: :模块索引:
- `nonebot <nonebot.html>`_ - `nonebot <nonebot.html>`_
- `nonebot.typing <typing.html>`_
- `nonebot.config <config.html>`_ - `nonebot.config <config.html>`_
- `nonebot.sched <sched.html>`_ - `nonebot.matcher <matcher.html>`_
- `nonebot.log <log.html>`_
- `nonebot.rule <rule.html>`_ - `nonebot.rule <rule.html>`_
- `nonebot.permission <permission.html>`_ - `nonebot.permission <permission.html>`_
- `nonebot.sched <sched.html>`_
- `nonebot.log <log.html>`_
- `nonebot.utils <utils.html>`_ - `nonebot.utils <utils.html>`_
- `nonebot.typing <typing.html>`_
- `nonebot.exception <exception.html>`_ - `nonebot.exception <exception.html>`_
- `nonebot.adapters <adapters/>`_
- `nonebot.adapters.cqhttp <adapters/cqhttp.html>`_ - `nonebot.adapters.cqhttp <adapters/cqhttp.html>`_

View File

@ -4,7 +4,7 @@ sidebarDepth: 0
--- ---
NoneBot.adapters 模块 NoneBot.adapters 模块
================= =====================
.. automodule:: nonebot.adapters .. automodule:: nonebot.adapters
:members: :members:

View File

@ -4,7 +4,7 @@ sidebarDepth: 0
--- ---
NoneBot.adapters.cqhttp 模块 NoneBot.adapters.cqhttp 模块
================= ============================
.. automodule:: nonebot.adapters.cqhttp .. automodule:: nonebot.adapters.cqhttp
:members: :members:

12
docs_build/matcher.rst Normal file
View File

@ -0,0 +1,12 @@
---
contentSidebar: true
sidebarDepth: 0
---
NoneBot.matcher 模块
====================
.. automodule:: nonebot.matcher
:members:
:private-members:
:show-inheritance:

View File

@ -4,7 +4,7 @@ sidebarDepth: 0
--- ---
NoneBot.permission 模块 NoneBot.permission 模块
==================== =======================
.. automodule:: nonebot.permission .. automodule:: nonebot.permission
:members: :members:

View File

@ -2,7 +2,7 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """
协议适配基类 协议适配基类
=========== ============
各协议请继承以下基类并使用 ``driver.register_adapter`` 注册适配器 各协议请继承以下基类并使用 ``driver.register_adapter`` 注册适配器
""" """

View File

@ -1,5 +1,11 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
"""
事件响应器
==========
该模块实现事件响应器的创建与运行并提供一些快捷方法来帮助用户更好的与机器人进行 对话
"""
from nonebot.log import logger from nonebot.log import logger
import typing import typing
@ -18,7 +24,7 @@ from nonebot.exception import PausedException, RejectedException, FinishedExcept
matchers: Dict[int, List[Type["Matcher"]]] = defaultdict(list) matchers: Dict[int, List[Type["Matcher"]]] = defaultdict(list)
""" """
:类型: ``Dict[int, List[Type[Matcher]]]`` :类型: ``Dict[int, List[Type[Matcher]]]``
:说明: 用于存储当前所有的 ``Matcher`` :说明: 用于存储当前所有的事件响应器
""" """
current_bot: ContextVar = ContextVar("current_bot") current_bot: ContextVar = ContextVar("current_bot")
current_event: ContextVar = ContextVar("current_event") current_event: ContextVar = ContextVar("current_event")
@ -36,22 +42,65 @@ class MatcherMeta(type):
class Matcher(metaclass=MatcherMeta): class Matcher(metaclass=MatcherMeta):
"""`Matcher`类 """事件响应器类"""
"""
module: Optional[str] = None module: Optional[str] = None
"""
:类型: ``Optional[str]``
:说明: 事件响应器所在模块名称
"""
type: str = "" type: str = ""
"""
:类型: ``str``
:说明: 事件响应器类型
"""
rule: Rule = Rule() rule: Rule = Rule()
"""
:类型: ``Rule``
:说明: 事件响应器匹配规则
"""
permission: Permission = Permission() permission: Permission = Permission()
"""
:类型: ``Permission``
:说明: 事件响应器触发权限
"""
handlers: List[Handler] = [] handlers: List[Handler] = []
temp: bool = False """
expire_time: Optional[datetime] = None :类型: ``List[Handler]``
:说明: 事件响应器拥有的事件处理函数列表
"""
priority: int = 1 priority: int = 1
"""
:类型: ``int``
:说明: 事件响应器优先级
"""
block: bool = False block: bool = False
"""
:类型: ``bool``
:说明: 事件响应器是否阻止事件传播
"""
temp: bool = False
"""
:类型: ``bool``
:说明: 事件响应器是否为临时
"""
expire_time: Optional[datetime] = None
"""
:类型: ``Optional[datetime]``
:说明: 事件响应器过期时间点
"""
_default_state: dict = {} _default_state: dict = {}
"""
:类型: ``dict``
:说明: 事件响应器默认状态
"""
_default_parser: Optional[ArgsParser] = None _default_parser: Optional[ArgsParser] = None
"""
:类型: ``Optional[ArgsParser]``
:说明: 事件响应器默认参数解析函数
"""
def __init__(self): def __init__(self):
"""实例化 Matcher 以便运行 """实例化 Matcher 以便运行
@ -69,9 +118,9 @@ class Matcher(metaclass=MatcherMeta):
@classmethod @classmethod
def new(cls, def new(cls,
type_: str = "", type_: str = "",
rule: Rule = Rule(), rule: Optional[Rule] = None,
permission: Permission = Permission(), permission: Optional[Permission] = None,
handlers: Optional[list] = None, handlers: Optional[List[Handler]] = None,
temp: bool = False, temp: bool = False,
priority: int = 1, priority: int = 1,
block: bool = False, block: bool = False,
@ -79,18 +128,30 @@ class Matcher(metaclass=MatcherMeta):
module: Optional[str] = None, module: Optional[str] = None,
default_state: Optional[dict] = None, default_state: Optional[dict] = None,
expire_time: Optional[datetime] = None) -> Type["Matcher"]: expire_time: Optional[datetime] = None) -> Type["Matcher"]:
"""创建新的 Matcher """
:说明:
Returns: 创建一个新的事件响应器并存储至 `matchers <#matchers>`_
Type["Matcher"]: 新的 Matcher :参数:
* ``type_: str``: 事件响应器类型 ``event.type`` 一致时触发空字符串表示任意
* ``rule: Optional[Rule]``: 匹配规则
* ``permission: Optional[Permission]``: 权限
* ``handlers: Optional[List[Handler]]``: 事件处理函数列表
* ``temp: bool``: 是否为临时事件响应器即触发一次后删除
* ``priority: int``: 响应优先级
* ``block: bool``: 是否阻止事件向更低优先级的响应器传播
* ``module: Optional[str]``: 事件响应器所在模块名称
* ``default_state: Optional[dict]``: 默认状态 ``state``
* ``expire_time: Optional[datetime]``: 事件响应器最终有效时间点过时即被删除
:返回:
- ``Type[Matcher]``: 新的事件响应器类
""" """
NewMatcher = type( NewMatcher = type(
"Matcher", (Matcher,), { "Matcher", (Matcher,), {
"module": module, "module": module,
"type": type_, "type": type_,
"rule": rule, "rule": rule or Rule(),
"permission": permission, "permission": permission or Permission(),
"handlers": handlers or [], "handlers": handlers or [],
"temp": temp, "temp": temp,
"expire_time": expire_time, "expire_time": expire_time,
@ -105,23 +166,40 @@ class Matcher(metaclass=MatcherMeta):
@classmethod @classmethod
async def check_perm(cls, bot: Bot, event: Event) -> bool: async def check_perm(cls, bot: Bot, event: Event) -> bool:
"""
:说明:
检查是否满足触发权限
:参数:
* ``bot: Bot``: Bot 对象
* ``event: Event``: 上报事件
:返回:
- ``bool``: 是否满足权限
"""
return await cls.permission(bot, event) return await cls.permission(bot, event)
@classmethod @classmethod
async def check_rule(cls, bot: Bot, event: Event, state: dict) -> bool: async def check_rule(cls, bot: Bot, event: Event, state: dict) -> bool:
"""检查 Matcher 的 Rule 是否成立 """
:说明:
Args: 检查是否满足匹配规则
event (Event): 消息事件 :参数:
* ``bot: Bot``: Bot 对象
Returns: * ``event: Event``: 上报事件
bool: 条件成立与否 * ``state: dict``: 当前状态
:返回:
- ``bool``: 是否满足匹配规则
""" """
return (event.type == (cls.type or event.type) and return (event.type == (cls.type or event.type) and
await cls.rule(bot, event, state)) await cls.rule(bot, event, state))
@classmethod @classmethod
def args_parser(cls, func: ArgsParser) -> ArgsParser: def args_parser(cls, func: ArgsParser) -> ArgsParser:
"""
:说明:
用于装饰一个函数来更改当前事件响应器的默认参数解析函数
:参数:
* ``func: ArgsParser``: 参数解析函数
"""
cls._default_parser = func cls._default_parser = func
return func return func

View File

@ -4,10 +4,10 @@
规则 规则
==== ====
每个 ``Matcher`` 拥有一个 ``Rule`` 其中是 **异步** ``RuleChecker`` 的集合只有当所有 ``RuleChecker`` 检查结果为 ``True`` 时继续运行 每个事件响应器 ``Matcher`` 拥有一个匹配规则 ``Rule`` 其中是 **异步** ``RuleChecker`` 的集合只有当所有 ``RuleChecker`` 检查结果为 ``True`` 时继续运行
\:\:\:tip 提示 \:\:\:tip 提示
``RuleChecker`` 既可以是 async function 也可以是 sync function ``RuleChecker`` 既可以是 async function 也可以是 sync function但在最终会被 ``nonebot.utils.run_sync`` 转换为 async function
\:\:\: \:\:\:
""" """
@ -185,6 +185,12 @@ def endswith(msg: str) -> Rule:
def keyword(msg: str) -> Rule: def keyword(msg: str) -> Rule:
"""
:说明:
匹配消息关键词
:参数:
* ``msg: str``: 关键词
"""
async def _keyword(bot: Bot, event: Event, state: dict) -> bool: async def _keyword(bot: Bot, event: Event, state: dict) -> bool:
return bool(event.plain_text and msg in event.plain_text) return bool(event.plain_text and msg in event.plain_text)
@ -193,6 +199,22 @@ def keyword(msg: str) -> Rule:
def command(command: Tuple[str, ...]) -> Rule: def command(command: Tuple[str, ...]) -> Rule:
"""
:说明:
命令形式匹配根据配置里提供的 ``command_start``, ``command_sep`` 判断消息是否为命令
:参数:
* ``command: Tuples[str, ...]``: 命令内容
:示例:
使用默认 ``command_start``, ``command_sep`` 配置
命令 ``("test",)`` 可以匹配``/test`` 开头的消息
命令 ``("test", "sub")`` 可以匹配``/test.sub`` 开头的消息
\:\:\:tip 提示
命令内容与后续消息间无需空格
\:\:\:
"""
config = get_driver().config config = get_driver().config
command_start = config.command_start command_start = config.command_start
command_sep = config.command_sep command_sep = config.command_sep
@ -210,6 +232,14 @@ def command(command: Tuple[str, ...]) -> Rule:
def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule: def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule:
"""
:说明:
根据正则表达式进行匹配
:参数:
* ``regex: str``: 正则表达式
* ``flags: Union[int, re.RegexFlag]``: 正则标志
"""
pattern = re.compile(regex, flags) pattern = re.compile(regex, flags)
async def _regex(bot: Bot, event: Event, state: dict) -> bool: async def _regex(bot: Bot, event: Event, state: dict) -> bool:
@ -219,6 +249,12 @@ def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule:
def to_me() -> Rule: def to_me() -> Rule:
"""
:说明:
通过 ``event.to_me`` 判断消息是否是发送给机器人
:参数:
*
"""
async def _to_me(bot: Bot, event: Event, state: dict) -> bool: async def _to_me(bot: Bot, event: Event, state: dict) -> bool:
return bool(event.to_me) return bool(event.to_me)