mirror of
https://github.com/nonebot/nonebot2.git
synced 2024-11-28 03:15:24 +08:00
🎨 format docstring
This commit is contained in:
yanyongyu
parent
96cdb9c23e
commit
e5463cc564
@ -29,6 +29,7 @@ class BaseBot(abc.ABC):
|
||||
websocket: Optional[WebSocket] = None):
|
||||
"""
|
||||
:参数:
|
||||
|
||||
* ``driver: Driver``: Driver 对象
|
||||
* ``connection_type: str``: http 或者 websocket
|
||||
* ``config: Config``: Config 对象
|
||||
@ -62,15 +63,22 @@ class BaseBot(abc.ABC):
|
||||
body: Optional[dict]) -> Union[str, NoReturn]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
检查连接请求是否合法的函数，如果合法则返回当前连接 ``唯一标识符``，通常为机器人 ID；如果不合法则抛出 ``RequestDenied`` 异常。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``driver: Driver``: Driver 对象
|
||||
* ``connection_type: str``: 连接类型
|
||||
* ``headers: dict``: 请求头
|
||||
* ``body: Optional[dict]``: 请求数据，WebSocket 连接该部分为空
|
||||
|
||||
:返回:
|
||||
|
||||
- ``str``: 连接唯一标识符
|
||||
|
||||
:异常:
|
||||
|
||||
- ``RequestDenied``: 请求非法
|
||||
"""
|
||||
raise NotImplementedError
|
||||
@ -79,8 +87,11 @@ class BaseBot(abc.ABC):
|
||||
async def handle_message(self, message: dict):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
处理上报消息的函数，转换为 ``Event`` 事件后调用 ``nonebot.message.handle_event`` 进一步处理事件。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``message: dict``: 收到的上报消息
|
||||
"""
|
||||
raise NotImplementedError
|
||||
@ -89,10 +100,14 @@ class BaseBot(abc.ABC):
|
||||
async def call_api(self, api: str, **data):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
调用机器人 API 接口，可以通过该函数或直接通过 bot 属性进行调用
|
||||
|
||||
:参数:
|
||||
|
||||
* ``api: str``: API 名称
|
||||
* ``**data``: API 数据
|
||||
|
||||
:示例:
|
||||
|
||||
.. code-block:: python
|
||||
@ -108,8 +123,11 @@ class BaseBot(abc.ABC):
|
||||
"BaseMessageSegment"], **kwargs):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
调用机器人基础发送消息接口
|
||||
|
||||
:参数:
|
||||
|
||||
* ``event: Event``: 上报事件
|
||||
* ``message: Union[str, Message, MessageSegment]``: 要发送的消息
|
||||
* ``**kwargs``
|
||||
@ -125,6 +143,7 @@ class BaseEvent(abc.ABC):
|
||||
def __init__(self, raw_event: dict):
|
||||
"""
|
||||
:参数:
|
||||
|
||||
* ``raw_event: dict``: 原始上报消息
|
||||
"""
|
||||
self._raw_event = raw_event
|
||||
@ -325,6 +344,7 @@ class BaseMessage(list, abc.ABC):
|
||||
**kwargs):
|
||||
"""
|
||||
:参数:
|
||||
|
||||
* ``message: Union[str, dict, list, MessageSegment, Message]``: 消息内容
|
||||
"""
|
||||
super().__init__(*args, **kwargs)
|
||||
@ -362,8 +382,11 @@ class BaseMessage(list, abc.ABC):
|
||||
def append(self, obj: Union[str, BaseMessageSegment]) -> "BaseMessage":
|
||||
"""
|
||||
:说明:
|
||||
|
||||
添加一个消息段到消息数组末尾
|
||||
|
||||
:参数:
|
||||
|
||||
* ``obj: Union[str, MessageSegment]``: 要添加的消息段
|
||||
"""
|
||||
if isinstance(obj, BaseMessageSegment):
|
||||
@ -382,8 +405,11 @@ class BaseMessage(list, abc.ABC):
|
||||
Iterable[BaseMessageSegment]]) -> "BaseMessage":
|
||||
"""
|
||||
:说明:
|
||||
|
||||
拼接一个消息数组或多个消息段到消息数组末尾
|
||||
|
||||
:参数:
|
||||
|
||||
* ``obj: Union[Message, Iterable[MessageSegment]]``: 要添加的消息数组
|
||||
"""
|
||||
for segment in obj:
|
||||
@ -393,6 +419,7 @@ class BaseMessage(list, abc.ABC):
|
||||
def reduce(self) -> None:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
缩减消息数组，即拼接相邻纯文本消息段
|
||||
"""
|
||||
index = 0
|
||||
@ -407,6 +434,7 @@ class BaseMessage(list, abc.ABC):
|
||||
def extract_plain_text(self) -> str:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
提取消息内纯文本消息
|
||||
"""
|
||||
|
||||
|
||||
@ -303,6 +303,7 @@ class Bot(BaseBot):
|
||||
body: Optional[dict]) -> Union[str, NoReturn]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
CQHTTP (OneBot) 协议鉴权。参考 `鉴权 <https://github.com/howmanybots/onebot/blob/master/v11/specs/communication/authorization.md>`_
|
||||
"""
|
||||
x_self_id = headers.get("x-self-id")
|
||||
|
||||
@ -125,6 +125,7 @@ class Config(BaseConfig):
|
||||
- 类型: ``str``
|
||||
- 默认值: ``"nonebot.drivers.fastapi"``
|
||||
- 说明:
|
||||
|
||||
NoneBot 运行所使用的 ``Driver`` 。继承自 ``nonebot.driver.BaseDriver`` 。
|
||||
"""
|
||||
host: IPvAnyAddress = IPv4Address("127.0.0.1") # type: ignore
|
||||
@ -132,6 +133,7 @@ class Config(BaseConfig):
|
||||
- 类型: ``IPvAnyAddress``
|
||||
- 默认值: ``127.0.0.1``
|
||||
- 说明:
|
||||
|
||||
NoneBot 的 HTTP 和 WebSocket 服务端监听的 IP/主机名。
|
||||
"""
|
||||
port: int = 8080
|
||||
@ -139,6 +141,7 @@ class Config(BaseConfig):
|
||||
- 类型: ``int``
|
||||
- 默认值: ``8080``
|
||||
- 说明:
|
||||
|
||||
NoneBot 的 HTTP 和 WebSocket 服务端监听的端口。
|
||||
"""
|
||||
debug: bool = False
|
||||
@ -146,6 +149,7 @@ class Config(BaseConfig):
|
||||
- 类型: ``bool``
|
||||
- 默认值: ``False``
|
||||
- 说明:
|
||||
|
||||
是否以调试模式运行 NoneBot。
|
||||
"""
|
||||
|
||||
@ -155,7 +159,9 @@ class Config(BaseConfig):
|
||||
- 类型: ``Dict[str, str]``
|
||||
- 默认值: ``{}``
|
||||
- 说明:
|
||||
|
||||
以机器人 ID 为键，上报地址为值的字典，环境变量或文件中应使用 json 序列化。
|
||||
|
||||
- 示例:
|
||||
|
||||
.. code-block:: default
|
||||
@ -167,6 +173,7 @@ class Config(BaseConfig):
|
||||
- 类型: ``Optional[float]``
|
||||
- 默认值: ``30.``
|
||||
- 说明:
|
||||
|
||||
API 请求超时时间，单位: 秒。
|
||||
"""
|
||||
access_token: Optional[str] = None
|
||||
@ -174,7 +181,9 @@ class Config(BaseConfig):
|
||||
- 类型: ``Optional[str]``
|
||||
- 默认值: ``None``
|
||||
- 说明:
|
||||
|
||||
API 请求以及上报所需密钥，在请求头中携带。
|
||||
|
||||
- 示例:
|
||||
|
||||
.. code-block:: http
|
||||
@ -187,7 +196,9 @@ class Config(BaseConfig):
|
||||
- 类型: ``Optional[str]``
|
||||
- 默认值: ``None``
|
||||
- 说明:
|
||||
|
||||
HTTP POST 形式上报所需签名，在请求头中携带。
|
||||
|
||||
- 示例:
|
||||
|
||||
.. code-block:: http
|
||||
@ -202,7 +213,9 @@ class Config(BaseConfig):
|
||||
- 类型: ``Set[int]``
|
||||
- 默认值: ``set()``
|
||||
- 说明:
|
||||
|
||||
机器人超级用户。
|
||||
|
||||
- 示例:
|
||||
|
||||
.. code-block:: default
|
||||
@ -214,6 +227,7 @@ class Config(BaseConfig):
|
||||
- 类型: ``Set[str]``
|
||||
- 默认值: ``set()``
|
||||
- 说明:
|
||||
|
||||
机器人昵称。
|
||||
"""
|
||||
command_start: Set[str] = {"/"}
|
||||
@ -221,6 +235,7 @@ class Config(BaseConfig):
|
||||
- 类型: ``Set[str]``
|
||||
- 默认值: ``{"/"}``
|
||||
- 说明:
|
||||
|
||||
命令的起始标记，用于判断一条消息是不是命令。
|
||||
"""
|
||||
command_sep: Set[str] = {"."}
|
||||
@ -228,6 +243,7 @@ class Config(BaseConfig):
|
||||
- 类型: ``Set[str]``
|
||||
- 默认值: ``{"."}``
|
||||
- 说明:
|
||||
|
||||
命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。
|
||||
"""
|
||||
session_expire_timeout: timedelta = timedelta(minutes=2)
|
||||
@ -235,7 +251,9 @@ class Config(BaseConfig):
|
||||
- 类型: ``timedelta``
|
||||
- 默认值: ``timedelta(minutes=2)``
|
||||
- 说明:
|
||||
|
||||
等待用户回复的超时时间。
|
||||
|
||||
- 示例:
|
||||
|
||||
.. code-block:: default
|
||||
@ -249,6 +267,7 @@ class Config(BaseConfig):
|
||||
- 类型: ``dict``
|
||||
- 默认值: ``{"apscheduler.timezone": "Asia/Shanghai"}``
|
||||
- 说明:
|
||||
|
||||
APScheduler 的配置对象，见 `Configuring the Scheduler`_
|
||||
|
||||
.. _Configuring the Scheduler:
|
||||
|
||||
@ -51,8 +51,11 @@ class BaseDriver(abc.ABC):
|
||||
def register_adapter(cls, name: str, adapter: Type[Bot]):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个协议适配器
|
||||
|
||||
:参数:
|
||||
|
||||
* ``name: str``: 适配器名称，用于在连接时进行识别
|
||||
* ``adapter: Type[Bot]``: 适配器 Class
|
||||
"""
|
||||
@ -110,8 +113,11 @@ class BaseDriver(abc.ABC):
|
||||
**kwargs):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
启动驱动框架
|
||||
|
||||
:参数:
|
||||
|
||||
* ``host: Optional[str]``: 驱动绑定 IP
|
||||
* ``post: Optional[int]``: 驱动绑定端口
|
||||
* ``*args``
|
||||
|
||||
@ -18,7 +18,6 @@ class IgnoredException(Exception):
|
||||
:参数:
|
||||
|
||||
* ``reason``: 忽略事件的原因
|
||||
|
||||
"""
|
||||
|
||||
def __init__(self, reason):
|
||||
|
||||
@ -101,8 +101,7 @@ class Matcher(metaclass=MatcherMeta):
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
"""实例化 Matcher 以便运行
|
||||
"""
|
||||
"""实例化 Matcher 以便运行"""
|
||||
self.handlers = self.handlers.copy()
|
||||
self.state = self._default_state.copy()
|
||||
|
||||
@ -128,8 +127,11 @@ class Matcher(metaclass=MatcherMeta):
|
||||
expire_time: Optional[datetime] = None) -> Type["Matcher"]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
创建一个新的事件响应器，并存储至 `matchers <#matchers>`_
|
||||
|
||||
:参数:
|
||||
|
||||
* ``type_: str``: 事件响应器类型，与 ``event.type`` 一致时触发，空字符串表示任意
|
||||
* ``rule: Optional[Rule]``: 匹配规则
|
||||
* ``permission: Optional[Permission]``: 权限
|
||||
@ -140,7 +142,9 @@ class Matcher(metaclass=MatcherMeta):
|
||||
* ``module: Optional[str]``: 事件响应器所在模块名称
|
||||
* ``default_state: Optional[dict]``: 默认状态 ``state``
|
||||
* ``expire_time: Optional[datetime]``: 事件响应器最终有效时间点，过时即被删除
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``: 新的事件响应器类
|
||||
"""
|
||||
|
||||
@ -166,11 +170,16 @@ class Matcher(metaclass=MatcherMeta):
|
||||
async def check_perm(cls, bot: Bot, event: Event) -> bool:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
检查是否满足触发权限
|
||||
|
||||
:参数:
|
||||
|
||||
* ``bot: Bot``: Bot 对象
|
||||
* ``event: Event``: 上报事件
|
||||
|
||||
:返回:
|
||||
|
||||
- ``bool``: 是否满足权限
|
||||
"""
|
||||
return await cls.permission(bot, event)
|
||||
@ -179,12 +188,17 @@ class Matcher(metaclass=MatcherMeta):
|
||||
async def check_rule(cls, bot: Bot, event: Event, state: dict) -> bool:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
检查是否满足匹配规则
|
||||
|
||||
:参数:
|
||||
|
||||
* ``bot: Bot``: Bot 对象
|
||||
* ``event: Event``: 上报事件
|
||||
* ``state: dict``: 当前状态
|
||||
|
||||
:返回:
|
||||
|
||||
- ``bool``: 是否满足匹配规则
|
||||
"""
|
||||
return (event.type == (cls.type or event.type) and
|
||||
@ -194,8 +208,11 @@ class Matcher(metaclass=MatcherMeta):
|
||||
def args_parser(cls, func: ArgsParser) -> ArgsParser:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
装饰一个函数来更改当前事件响应器的默认参数解析函数
|
||||
|
||||
:参数:
|
||||
|
||||
* ``func: ArgsParser``: 参数解析函数
|
||||
"""
|
||||
cls._default_parser = func
|
||||
@ -205,8 +222,11 @@ class Matcher(metaclass=MatcherMeta):
|
||||
def handle(cls) -> Callable[[Handler], Handler]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
装饰一个函数来向事件响应器直接添加一个处理函数
|
||||
|
||||
:参数:
|
||||
|
||||
* 无
|
||||
"""
|
||||
|
||||
@ -220,8 +240,11 @@ class Matcher(metaclass=MatcherMeta):
|
||||
def receive(cls) -> Callable[[Handler], Handler]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数
|
||||
|
||||
:参数:
|
||||
|
||||
* 无
|
||||
"""
|
||||
|
||||
@ -249,8 +272,11 @@ class Matcher(metaclass=MatcherMeta):
|
||||
) -> Callable[[Handler], Handler]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
装饰一个函数来指示 NoneBot 当要获取的 ``key`` 不存在时接收用户新的一条消息并经过 ``ArgsParser`` 处理后再运行该函数，如果 ``key`` 已存在则直接继续运行
|
||||
|
||||
:参数:
|
||||
|
||||
* ``key: str``: 参数名
|
||||
* ``prompt: Optional[Union[str, Message, MessageSegment]]``: 在参数不存在时向用户发送的消息
|
||||
* ``args_parser: Optional[ArgsParser]``: 可选参数解析函数，空则使用默认解析函数
|
||||
@ -300,8 +326,11 @@ class Matcher(metaclass=MatcherMeta):
|
||||
async def send(cls, message: Union[str, Message, MessageSegment], **kwargs):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
发送一条消息给当前交互用户
|
||||
|
||||
:参数:
|
||||
|
||||
* ``message: Union[str, Message, MessageSegment]``: 消息内容
|
||||
* ``**kwargs``: 其他传递给 ``bot.send`` 的参数，请参考对应 adapter 的 bot 对象 api
|
||||
"""
|
||||
@ -316,8 +345,11 @@ class Matcher(metaclass=MatcherMeta):
|
||||
**kwargs) -> NoReturn:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
发送一条消息给当前交互用户并结束当前事件响应器
|
||||
|
||||
:参数:
|
||||
|
||||
* ``message: Union[str, Message, MessageSegment]``: 消息内容
|
||||
* ``**kwargs``: 其他传递给 ``bot.send`` 的参数，请参考对应 adapter 的 bot 对象 api
|
||||
"""
|
||||
@ -334,8 +366,11 @@ class Matcher(metaclass=MatcherMeta):
|
||||
**kwargs) -> NoReturn:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数
|
||||
|
||||
:参数:
|
||||
|
||||
* ``prompt: Union[str, Message, MessageSegment]``: 消息内容
|
||||
* ``**kwargs``: 其他传递给 ``bot.send`` 的参数，请参考对应 adapter 的 bot 对象 api
|
||||
"""
|
||||
@ -352,8 +387,11 @@ class Matcher(metaclass=MatcherMeta):
|
||||
**kwargs) -> NoReturn:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后重新运行当前处理函数
|
||||
|
||||
:参数:
|
||||
|
||||
* ``prompt: Union[str, Message, MessageSegment]``: 消息内容
|
||||
* ``**kwargs``: 其他传递给 ``bot.send`` 的参数，请参考对应 adapter 的 bot 对象 api
|
||||
"""
|
||||
@ -430,6 +468,7 @@ class MatcherGroup:
|
||||
expire_time: Optional[datetime] = None):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
创建一个事件响应器组合，参数为默认值，与 ``Matcher.new`` 一致
|
||||
"""
|
||||
self.matchers: List[Type[Matcher]] = []
|
||||
@ -474,6 +513,7 @@ class MatcherGroup:
|
||||
expire_time: Optional[datetime] = None) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
在组中创建一个新的事件响应器，参数留空则使用组合默认值
|
||||
|
||||
\:\:\:danger 警告
|
||||
|
||||
@ -25,8 +25,11 @@ _run_postprocessors: Set[RunPostProcessor] = set()
|
||||
def event_preprocessor(func: EventPreProcessor) -> EventPreProcessor:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
事件预处理。装饰一个函数，使它在每次接收到事件并分发给各响应器之前执行。
|
||||
|
||||
:参数:
|
||||
|
||||
事件预处理函数接收三个参数。
|
||||
|
||||
* ``bot: Bot``: Bot 对象
|
||||
@ -40,8 +43,11 @@ def event_preprocessor(func: EventPreProcessor) -> EventPreProcessor:
|
||||
def event_postprocessor(func: EventPostProcessor) -> EventPostProcessor:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
事件后处理。装饰一个函数，使它在每次接收到事件并分发给各响应器之后执行。
|
||||
|
||||
:参数:
|
||||
|
||||
事件后处理函数接收三个参数。
|
||||
|
||||
* ``bot: Bot``: Bot 对象
|
||||
@ -55,8 +61,11 @@ def event_postprocessor(func: EventPostProcessor) -> EventPostProcessor:
|
||||
def run_preprocessor(func: RunPreProcessor) -> RunPreProcessor:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
运行预处理。装饰一个函数，使它在每次事件响应器运行前执行。
|
||||
|
||||
:参数:
|
||||
|
||||
运行预处理函数接收四个参数。
|
||||
|
||||
* ``matcher: Matcher``: 当前要运行的事件响应器
|
||||
@ -71,8 +80,11 @@ def run_preprocessor(func: RunPreProcessor) -> RunPreProcessor:
|
||||
def run_postprocessor(func: RunPostProcessor) -> RunPostProcessor:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
运行后处理。装饰一个函数，使它在每次事件响应器运行后执行。
|
||||
|
||||
:参数:
|
||||
|
||||
运行后处理函数接收五个参数。
|
||||
|
||||
* ``matcher: Matcher``: 运行完毕的事件响应器
|
||||
@ -176,10 +188,14 @@ async def _run_matcher(Matcher: Type[Matcher], bot: Bot, event: Event,
|
||||
async def handle_event(bot: Bot, event: Event):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
处理一个事件。调用该函数以实现分发事件。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``bot: Bot``: Bot 对象
|
||||
* ``event: Event``: Event 对象
|
||||
|
||||
:示例:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -22,24 +22,33 @@ class Permission:
|
||||
Awaitable[bool]]) -> None:
|
||||
"""
|
||||
:参数:
|
||||
|
||||
* ``*checkers: Callable[[Bot, Event], Awaitable[bool]]``: **异步** PermissionChecker
|
||||
"""
|
||||
self.checkers = set(checkers)
|
||||
"""
|
||||
:说明:
|
||||
|
||||
存储 ``PermissionChecker``
|
||||
|
||||
:类型:
|
||||
|
||||
* ``Set[Callable[[Bot, Event], Awaitable[bool]]]``
|
||||
"""
|
||||
|
||||
async def __call__(self, bot: Bot, event: Event) -> bool:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
检查是否满足某个权限
|
||||
|
||||
:参数:
|
||||
|
||||
* ``bot: Bot``: Bot 对象
|
||||
* ``event: Event``: Event 对象
|
||||
|
||||
:返回:
|
||||
|
||||
- ``bool``
|
||||
"""
|
||||
if not self.checkers:
|
||||
@ -103,8 +112,11 @@ METAEVENT = Permission(_metaevent)
|
||||
def USER(*user: int, perm: Permission = Permission()):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
在白名单内且满足 perm
|
||||
|
||||
:参数:
|
||||
|
||||
* ``*user: int``: 白名单
|
||||
* ``perm: Permission``: 需要同时满足的权限
|
||||
"""
|
||||
|
||||
@ -33,7 +33,9 @@ _export: ContextVar["Export"] = ContextVar("_export")
|
||||
class Export(dict):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
插件导出内容以使得其他插件可以获得。
|
||||
|
||||
:示例:
|
||||
|
||||
.. code-block:: python
|
||||
@ -107,8 +109,11 @@ def on(type: str = "",
|
||||
state: Optional[dict] = None) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个基础事件响应器，可自定义类型。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``type: str``: 事件响应器类型
|
||||
* ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
|
||||
* ``permission: Optional[Permission]``: 事件响应权限
|
||||
@ -117,7 +122,9 @@ def on(type: str = "",
|
||||
* ``priority: int``: 事件响应器优先级
|
||||
* ``block: bool``: 是否阻止事件向更低优先级传递
|
||||
* ``state: Optional[dict]``: 默认的 state
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
matcher = Matcher.new(type,
|
||||
@ -141,15 +148,20 @@ def on_metaevent(rule: Optional[Union[Rule, RuleChecker]] = None,
|
||||
state: Optional[dict] = None) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个元事件响应器。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
|
||||
* ``handlers: Optional[List[Handler]]``: 事件处理函数列表
|
||||
* ``temp: bool``: 是否为临时事件响应器（仅执行一次）
|
||||
* ``priority: int``: 事件响应器优先级
|
||||
* ``block: bool``: 是否阻止事件向更低优先级传递
|
||||
* ``state: Optional[dict]``: 默认的 state
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
matcher = Matcher.new("meta_event",
|
||||
@ -174,8 +186,11 @@ def on_message(rule: Optional[Union[Rule, RuleChecker]] = None,
|
||||
state: Optional[dict] = None) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个消息事件响应器。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
|
||||
* ``permission: Optional[Permission]``: 事件响应权限
|
||||
* ``handlers: Optional[List[Handler]]``: 事件处理函数列表
|
||||
@ -183,7 +198,9 @@ def on_message(rule: Optional[Union[Rule, RuleChecker]] = None,
|
||||
* ``priority: int``: 事件响应器优先级
|
||||
* ``block: bool``: 是否阻止事件向更低优先级传递
|
||||
* ``state: Optional[dict]``: 默认的 state
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
matcher = Matcher.new("message",
|
||||
@ -207,15 +224,20 @@ def on_notice(rule: Optional[Union[Rule, RuleChecker]] = None,
|
||||
state: Optional[dict] = None) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个通知事件响应器。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
|
||||
* ``handlers: Optional[List[Handler]]``: 事件处理函数列表
|
||||
* ``temp: bool``: 是否为临时事件响应器（仅执行一次）
|
||||
* ``priority: int``: 事件响应器优先级
|
||||
* ``block: bool``: 是否阻止事件向更低优先级传递
|
||||
* ``state: Optional[dict]``: 默认的 state
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
matcher = Matcher.new("notice",
|
||||
@ -239,15 +261,20 @@ def on_request(rule: Optional[Union[Rule, RuleChecker]] = None,
|
||||
state: Optional[dict] = None) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个请求事件响应器。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
|
||||
* ``handlers: Optional[List[Handler]]``: 事件处理函数列表
|
||||
* ``temp: bool``: 是否为临时事件响应器（仅执行一次）
|
||||
* ``priority: int``: 事件响应器优先级
|
||||
* ``block: bool``: 是否阻止事件向更低优先级传递
|
||||
* ``state: Optional[dict]``: 默认的 state
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
matcher = Matcher.new("request",
|
||||
@ -267,8 +294,11 @@ def on_startswith(msg: str,
|
||||
**kwargs) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个消息事件响应器，并且当消息的**文本部分**以指定内容开头时响应。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``msg: str``: 指定消息开头内容
|
||||
* ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
|
||||
* ``permission: Optional[Permission]``: 事件响应权限
|
||||
@ -277,7 +307,9 @@ def on_startswith(msg: str,
|
||||
* ``priority: int``: 事件响应器优先级
|
||||
* ``block: bool``: 是否阻止事件向更低优先级传递
|
||||
* ``state: Optional[dict]``: 默认的 state
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
return on_message(startswith(msg) & rule, **kwargs)
|
||||
@ -288,8 +320,11 @@ def on_endswith(msg: str,
|
||||
**kwargs) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个消息事件响应器，并且当消息的**文本部分**以指定内容结尾时响应。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``msg: str``: 指定消息结尾内容
|
||||
* ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
|
||||
* ``permission: Optional[Permission]``: 事件响应权限
|
||||
@ -298,7 +333,9 @@ def on_endswith(msg: str,
|
||||
* ``priority: int``: 事件响应器优先级
|
||||
* ``block: bool``: 是否阻止事件向更低优先级传递
|
||||
* ``state: Optional[dict]``: 默认的 state
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
return on_message(endswith(msg) & rule, **kwargs)
|
||||
@ -309,8 +346,11 @@ def on_keyword(keywords: Set[str],
|
||||
**kwargs) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个消息事件响应器，并且当消息纯文本部分包含关键词时响应。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``keywords: Set[str]``: 关键词列表
|
||||
* ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
|
||||
* ``permission: Optional[Permission]``: 事件响应权限
|
||||
@ -319,7 +359,9 @@ def on_keyword(keywords: Set[str],
|
||||
* ``priority: int``: 事件响应器优先级
|
||||
* ``block: bool``: 是否阻止事件向更低优先级传递
|
||||
* ``state: Optional[dict]``: 默认的 state
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
return on_message(keyword(*keywords) & rule, **kwargs)
|
||||
@ -331,10 +373,13 @@ def on_command(cmd: Union[str, Tuple[str, ...]],
|
||||
**kwargs) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个消息事件响应器，并且当消息以指定命令开头时响应。
|
||||
|
||||
命令匹配规则参考: `命令形式匹配 <rule.html#command-command>`_
|
||||
|
||||
:参数:
|
||||
|
||||
* ``cmd: Union[str, Tuple[str, ...]]``: 指定命令内容
|
||||
* ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
|
||||
* ``aliases: Optional[Set[Union[str, Tuple[str, ...]]]]``: 命令别名
|
||||
@ -344,7 +389,9 @@ def on_command(cmd: Union[str, Tuple[str, ...]],
|
||||
* ``priority: int``: 事件响应器优先级
|
||||
* ``block: bool``: 是否阻止事件向更低优先级传递
|
||||
* ``state: Optional[dict]``: 默认的 state
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
|
||||
@ -366,10 +413,13 @@ def on_regex(pattern: str,
|
||||
**kwargs) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个消息事件响应器，并且当消息匹配正则表达式时响应。
|
||||
|
||||
命令匹配规则参考: `正则匹配 <rule.html#regex-regex-flags-0>`_
|
||||
|
||||
:参数:
|
||||
|
||||
* ``pattern: str``: 正则表达式
|
||||
* ``flags: Union[int, re.RegexFlag]``: 正则匹配标志
|
||||
* ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
|
||||
@ -379,7 +429,9 @@ def on_regex(pattern: str,
|
||||
* ``priority: int``: 事件响应器优先级
|
||||
* ``block: bool``: 是否阻止事件向更低优先级传递
|
||||
* ``state: Optional[dict]``: 默认的 state
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
return on_message(regex(pattern, flags) & rule, **kwargs)
|
||||
@ -391,6 +443,7 @@ class CommandGroup:
|
||||
def __init__(self, cmd: Union[str, Tuple[str, ...]], **kwargs):
|
||||
"""
|
||||
:参数:
|
||||
|
||||
* ``cmd: Union[str, Tuple[str, ...]]``: 命令前缀
|
||||
* ``**kwargs``: 其他传递给 ``on_command`` 的参数默认值，参考 `on_command <#on-command-cmd-rule-none-aliases-none-kwargs>`_
|
||||
"""
|
||||
@ -411,11 +464,16 @@ class CommandGroup:
|
||||
**kwargs) -> Type[Matcher]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
注册一个新的命令。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``cmd: Union[str, Tuple[str, ...]]``: 命令前缀
|
||||
* ``**kwargs``: 其他传递给 ``on_command`` 的参数，将会覆盖命令组默认值
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Type[Matcher]``
|
||||
"""
|
||||
sub_cmd = (cmd,) if isinstance(cmd, str) else cmd
|
||||
@ -429,10 +487,15 @@ class CommandGroup:
|
||||
def load_plugin(module_path: str) -> Optional[Plugin]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
使用 ``importlib`` 加载单个插件，可以是本地插件或是通过 ``pip`` 安装的插件。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``module_path: str``: 插件名称 ``path.to.your.plugin``
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Optional[Plugin]``
|
||||
"""
|
||||
|
||||
@ -469,10 +532,15 @@ def load_plugin(module_path: str) -> Optional[Plugin]:
|
||||
def load_plugins(*plugin_dir: str) -> Set[Plugin]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
导入目录下多个插件，以 ``_`` 开头的插件不会被导入！
|
||||
|
||||
:参数:
|
||||
|
||||
- ``*plugin_dir: str``: 插件路径
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Set[Plugin]``
|
||||
"""
|
||||
|
||||
@ -517,8 +585,11 @@ def load_plugins(*plugin_dir: str) -> Set[Plugin]:
|
||||
def load_builtin_plugins() -> Optional[Plugin]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
导入 NoneBot 内置插件
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Plugin``
|
||||
"""
|
||||
return load_plugin("nonebot.plugins.base")
|
||||
@ -527,10 +598,15 @@ def load_builtin_plugins() -> Optional[Plugin]:
|
||||
def get_plugin(name: str) -> Optional[Plugin]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
获取当前导入的某个插件。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``name: str``: 插件名，与 ``load_plugin`` 参数一致。如果为 ``load_plugins`` 导入的插件，则为文件(夹)名。
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Optional[Plugin]``
|
||||
"""
|
||||
return plugins.get(name)
|
||||
@ -539,8 +615,11 @@ def get_plugin(name: str) -> Optional[Plugin]:
|
||||
def get_loaded_plugins() -> Set[Plugin]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
获取当前已导入的所有插件。
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Set[Plugin]``
|
||||
"""
|
||||
return set(plugins.values())
|
||||
@ -549,8 +628,11 @@ def get_loaded_plugins() -> Set[Plugin]:
|
||||
def export() -> Export:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
获取插件的导出内容对象
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Export``
|
||||
"""
|
||||
return _export.get()
|
||||
@ -559,10 +641,15 @@ def export() -> Export:
|
||||
def require(name: str) -> Optional[Export]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
获取一个插件的导出内容
|
||||
|
||||
:参数:
|
||||
|
||||
* ``name: str``: 插件名，与 ``load_plugin`` 参数一致。如果为 ``load_plugins`` 导入的插件，则为文件(夹)名。
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Optional[Export]``
|
||||
"""
|
||||
plugin = get_plugin(name)
|
||||
|
||||
@ -24,7 +24,9 @@ from nonebot.typing import Bot, Any, Dict, Event, Union, Tuple, NoReturn, Option
|
||||
class Rule:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
``Matcher`` 规则类，当事件传递时，在 ``Matcher`` 运行前进行检查。
|
||||
|
||||
:示例:
|
||||
|
||||
.. code-block:: python
|
||||
@ -41,25 +43,35 @@ class Rule:
|
||||
Awaitable[bool]]) -> None:
|
||||
"""
|
||||
:参数:
|
||||
|
||||
* ``*checkers: Callable[[Bot, Event, dict], Awaitable[bool]]``: **异步** RuleChecker
|
||||
|
||||
"""
|
||||
self.checkers = set(checkers)
|
||||
"""
|
||||
:说明:
|
||||
|
||||
存储 ``RuleChecker``
|
||||
|
||||
:类型:
|
||||
|
||||
* ``Set[Callable[[Bot, Event, dict], Awaitable[bool]]]``
|
||||
"""
|
||||
|
||||
async def __call__(self, bot: Bot, event: Event, state: dict) -> bool:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
检查是否符合所有规则
|
||||
|
||||
:参数:
|
||||
|
||||
* ``bot: Bot``: Bot 对象
|
||||
* ``event: Event``: Event 对象
|
||||
* ``state: dict``: 当前 State
|
||||
|
||||
:返回:
|
||||
|
||||
- ``bool``
|
||||
"""
|
||||
results = await asyncio.gather(
|
||||
@ -157,8 +169,11 @@ class TrieRule:
|
||||
def startswith(msg: str) -> Rule:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
匹配消息开头
|
||||
|
||||
:参数:
|
||||
|
||||
* ``msg: str``: 消息开头字符串
|
||||
"""
|
||||
|
||||
@ -171,8 +186,11 @@ def startswith(msg: str) -> Rule:
|
||||
def endswith(msg: str) -> Rule:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
匹配消息结尾
|
||||
|
||||
:参数:
|
||||
|
||||
* ``msg: str``: 消息结尾字符串
|
||||
"""
|
||||
|
||||
@ -185,8 +203,11 @@ def endswith(msg: str) -> Rule:
|
||||
def keyword(*keywords: str) -> Rule:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
匹配消息关键词
|
||||
|
||||
:参数:
|
||||
|
||||
* ``*keywords: str``: 关键词
|
||||
"""
|
||||
|
||||
@ -200,12 +221,17 @@ def keyword(*keywords: str) -> Rule:
|
||||
def command(*cmds: Union[str, Tuple[str, ...]]) -> Rule:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
命令形式匹配，根据配置里提供的 ``command_start``, ``command_sep`` 判断消息是否为命令。
|
||||
|
||||
可以通过 ``state["_prefix"]["command"]`` 获取匹配成功的命令（例：``("test",)``），通过 ``state["_prefix"]["raw_command"]`` 获取匹配成功的原始命令文本（例：``"/test"``）。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``*cmds: Union[str, Tuple[str, ...]]``: 命令内容
|
||||
|
||||
:示例:
|
||||
|
||||
使用默认 ``command_start``, ``command_sep`` 配置
|
||||
|
||||
命令 ``("test",)`` 可以匹配：``/test`` 开头的消息
|
||||
@ -240,10 +266,13 @@ def command(*cmds: Union[str, Tuple[str, ...]]) -> Rule:
|
||||
def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
根据正则表达式进行匹配。
|
||||
|
||||
可以通过 ``state["_matched"]`` 获取正则表达式匹配成功的文本。
|
||||
|
||||
:参数:
|
||||
|
||||
* ``regex: str``: 正则表达式
|
||||
* ``flags: Union[int, re.RegexFlag]``: 正则标志
|
||||
|
||||
@ -269,8 +298,11 @@ def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule:
|
||||
def to_me() -> Rule:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
通过 ``event.to_me`` 判断消息是否是发送给机器人
|
||||
|
||||
:参数:
|
||||
|
||||
* 无
|
||||
"""
|
||||
|
||||
|
||||
@ -19,8 +19,11 @@ if AsyncIOScheduler:
|
||||
scheduler = AsyncIOScheduler()
|
||||
"""
|
||||
:类型:
|
||||
|
||||
``Optional[apscheduler.schedulers.asyncio.AsyncIOScheduler]``
|
||||
|
||||
:说明:
|
||||
|
||||
当可选依赖 ``APScheduler`` 未安装时，``scheduler`` 为 None
|
||||
|
||||
使用 ``pip install nonebot[scheduler]`` 安装可选依赖
|
||||
|
||||
@ -10,10 +10,15 @@ from nonebot.typing import Any, Callable, Awaitable, overrides
|
||||
def escape_tag(s: str) -> str:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
用于记录带颜色日志时转义 ``<tag>`` 类型特殊标签
|
||||
|
||||
:参数:
|
||||
|
||||
* ``s: str``: 需要转义的字符串
|
||||
|
||||
:返回:
|
||||
|
||||
- ``str``
|
||||
"""
|
||||
return re.sub(r"</?((?:[fb]g\s)?[^<>\s]*)>", r"\\\g<0>", s)
|
||||
@ -22,10 +27,15 @@ def escape_tag(s: str) -> str:
|
||||
def run_sync(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
|
||||
"""
|
||||
:说明:
|
||||
|
||||
一个用于包装 sync function 为 async function 的装饰器
|
||||
|
||||
:参数:
|
||||
|
||||
* ``func: Callable[..., Any]``: 被装饰的同步函数
|
||||
|
||||
:返回:
|
||||
|
||||
- ``Callable[..., Awaitable[Any]]``
|
||||
"""
|
||||
|
||||
@ -42,6 +52,7 @@ def run_sync(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
|
||||
class DataclassEncoder(json.JSONEncoder):
|
||||
"""
|
||||
:说明:
|
||||
|
||||
在JSON序列化 ``Message`` (List[Dataclass]) 时使用的 ``JSONEncoder``
|
||||
"""
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user