From e5463cc564aa302118332005c6bac3e6e42a1956 Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Mon, 30 Nov 2020 11:08:00 +0800 Subject: [PATCH] :art: format docstring --- nonebot/adapters/__init__.py | 28 ++++++++++ nonebot/adapters/cqhttp/__init__.py | 1 + nonebot/config.py | 19 +++++++ nonebot/drivers/__init__.py | 6 ++ nonebot/exception.py | 1 - nonebot/matcher.py | 44 ++++++++++++++- nonebot/message.py | 16 ++++++ nonebot/permission.py | 12 ++++ nonebot/plugin.py | 87 +++++++++++++++++++++++++++++ nonebot/rule.py | 32 +++++++++++ nonebot/sched.py | 3 + nonebot/utils.py | 11 ++++ 12 files changed, 257 insertions(+), 3 deletions(-) diff --git a/nonebot/adapters/__init__.py b/nonebot/adapters/__init__.py index 2ca5505f..60fda096 100644 --- a/nonebot/adapters/__init__.py +++ b/nonebot/adapters/__init__.py @@ -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: """ :说明: + 提取消息内纯文本消息 """ diff --git a/nonebot/adapters/cqhttp/__init__.py b/nonebot/adapters/cqhttp/__init__.py index 714e9f62..f1c7c8fe 100644 --- a/nonebot/adapters/cqhttp/__init__.py +++ b/nonebot/adapters/cqhttp/__init__.py @@ -303,6 +303,7 @@ class Bot(BaseBot): body: Optional[dict]) -> Union[str, NoReturn]: """ :说明: + CQHTTP (OneBot) 协议鉴权。参考 `鉴权 `_ """ x_self_id = headers.get("x-self-id") diff --git a/nonebot/config.py b/nonebot/config.py index 252b39ad..020b94d5 100644 --- a/nonebot/config.py +++ b/nonebot/config.py @@ -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: diff --git a/nonebot/drivers/__init__.py b/nonebot/drivers/__init__.py index ce6097ff..8e309b64 100644 --- a/nonebot/drivers/__init__.py +++ b/nonebot/drivers/__init__.py @@ -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`` diff --git a/nonebot/exception.py b/nonebot/exception.py index f16cbcd0..cc65e6da 100644 --- a/nonebot/exception.py +++ b/nonebot/exception.py @@ -18,7 +18,6 @@ class IgnoredException(Exception): :参数: * ``reason``: 忽略事件的原因 - """ def __init__(self, reason): diff --git a/nonebot/matcher.py b/nonebot/matcher.py index 92238af9..b38ef47e 100644 --- a/nonebot/matcher.py +++ b/nonebot/matcher.py @@ -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 警告 diff --git a/nonebot/message.py b/nonebot/message.py index 1b102633..425b476a 100644 --- a/nonebot/message.py +++ b/nonebot/message.py @@ -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 diff --git a/nonebot/permission.py b/nonebot/permission.py index df6c099b..f4c793b0 100644 --- a/nonebot/permission.py +++ b/nonebot/permission.py @@ -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``: 需要同时满足的权限 """ diff --git a/nonebot/plugin.py b/nonebot/plugin.py index f063726c..95db5ce4 100644 --- a/nonebot/plugin.py +++ b/nonebot/plugin.py @@ -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]: """ :说明: + 注册一个消息事件响应器，并且当消息以指定命令开头时响应。 命令匹配规则参考: `命令形式匹配 `_ + :参数: + * ``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]: """ :说明: + 注册一个消息事件响应器，并且当消息匹配正则表达式时响应。 命令匹配规则参考: `正则匹配 `_ + :参数: + * ``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) diff --git a/nonebot/rule.py b/nonebot/rule.py index faefbd76..28d05abf 100644 --- a/nonebot/rule.py +++ b/nonebot/rule.py @@ -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`` 判断消息是否是发送给机器人 + :参数: + * 无 """ diff --git a/nonebot/sched.py b/nonebot/sched.py index e47d95b7..4129f36c 100644 --- a/nonebot/sched.py +++ b/nonebot/sched.py @@ -19,8 +19,11 @@ if AsyncIOScheduler: scheduler = AsyncIOScheduler() """ :类型: + ``Optional[apscheduler.schedulers.asyncio.AsyncIOScheduler]`` + :说明: + 当可选依赖 ``APScheduler`` 未安装时，``scheduler`` 为 None 使用 ``pip install nonebot[scheduler]`` 安装可选依赖 diff --git a/nonebot/utils.py b/nonebot/utils.py index db447401..4fdc9f47 100644 --- a/nonebot/utils.py +++ b/nonebot/utils.py @@ -10,10 +10,15 @@ from nonebot.typing import Any, Callable, Awaitable, overrides def escape_tag(s: str) -> str: """ :说明: + 用于记录带颜色日志时转义 ```` 类型特殊标签 + :参数: + * ``s: str``: 需要转义的字符串 + :返回: + - ``str`` """ return re.sub(r"\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`` """