💡 add rule utils docstring

This commit is contained in:
yanyongyu 2020-09-13 13:01:23 +08:00
parent ce2700c1d2
commit f79eabdc61
15 changed files with 212 additions and 89 deletions

View File

@ -88,6 +88,10 @@ module.exports = context => ({
title: "nonebot.log 模块", title: "nonebot.log 模块",
path: "log" path: "log"
}, },
{
title: "nonebot.rule 模块",
path: "rule"
},
{ {
title: "nonebot.utils 模块", title: "nonebot.utils 模块",
path: "utils" path: "utils"

View File

@ -19,6 +19,9 @@
* [nonebot.log](log.html) * [nonebot.log](log.html)
* [nonebot.rule](rule.html)
* [nonebot.utils](utils.html) * [nonebot.utils](utils.html)

View File

@ -156,7 +156,7 @@ bots = nonebot.get_bots()
* **返回** * **返回**
* None * `None`
@ -196,7 +196,7 @@ nonebot.init(database=Database(...))
* **返回** * **返回**
* None * `None`

90
docs/api/rule.md Normal file
View File

@ -0,0 +1,90 @@
---
contentSidebar: true
sidebarDepth: 0
---
# NoneBot.rule 模块
## 规则
每个 `Matcher` 拥有一个 `Rule` ,其中是 `RuleChecker` 的集合,只有当所有 `RuleChecker` 检查结果为 `True` 时继续运行。
:::tip 提示
`RuleChecker` 既可以是 async function 也可以是 sync function
:::
## _class_ `Rule`
基类:`object`
* **说明**
`Matcher` 规则类,当事件传递时,在 `Matcher` 运行前进行检查。
* **示例**
```python
Rule(async_function) & sync_function
# 等价于
from nonebot.utils import run_sync
Rule(async_function, run_sync(sync_function))
```
### `__init__(*checkers)`
* **参数**
* `*checkers: Callable[[Bot, Event, dict], Awaitable[bool]]`: **异步** RuleChecker
### `checkers`
* **说明**
存储 `RuleChecker`
* **类型**
* `Set[Callable[[Bot, Event, dict], Awaitable[bool]]]`
### _async_ `__call__(bot, event, state)`
* **说明**
检查是否符合所有规则
* **参数**
* `bot: Bot`: Bot 对象
* `event: Event`: Event 对象
* `state: dict`: 当前 State
* **返回**
* `bool`

View File

@ -19,7 +19,7 @@ sidebarDepth: 0
* **类型** * **类型**
BaseDriver `BaseDriver`
@ -35,7 +35,7 @@ sidebarDepth: 0
* **类型** * **类型**
BaseWebSocket `BaseWebSocket`
@ -51,7 +51,7 @@ sidebarDepth: 0
* **类型** * **类型**
BaseBot `BaseBot`
@ -67,7 +67,7 @@ sidebarDepth: 0
* **类型** * **类型**
BaseEvent `BaseEvent`
@ -83,7 +83,7 @@ sidebarDepth: 0
* **类型** * **类型**
BaseMessage `BaseMessage`
@ -99,7 +99,7 @@ sidebarDepth: 0
* **类型** * **类型**
BaseMessageSegment `BaseMessageSegment`
@ -115,7 +115,7 @@ sidebarDepth: 0
* **类型** * **类型**
Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]] `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`
@ -131,7 +131,7 @@ sidebarDepth: 0
* **类型** * **类型**
Matcher `Matcher`
@ -147,7 +147,7 @@ sidebarDepth: 0
* **类型** * **类型**
Rule `Rule`
@ -163,7 +163,7 @@ sidebarDepth: 0
* **类型** * **类型**
Callable[[Bot, Event, dict], Awaitable[bool]] `Callable[[Bot, Event, dict], Union[bool, Awaitable[bool]]]`
@ -179,7 +179,7 @@ sidebarDepth: 0
* **类型** * **类型**
Permission `Permission`
@ -195,7 +195,7 @@ sidebarDepth: 0
* **类型** * **类型**
Callable[[Bot, Event], Awaitable[bool]] `Callable[[Bot, Event], Union[bool, Awaitable[bool]]]`
@ -211,7 +211,7 @@ sidebarDepth: 0
* **类型** * **类型**
Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]] `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`
@ -227,7 +227,7 @@ sidebarDepth: 0
* **类型** * **类型**
Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]] `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`

View File

@ -25,7 +25,7 @@ sidebarDepth: 0
* **返回** * **返回**
* Callable[..., Awaitable[Any]] * `Callable[..., Awaitable[Any]]`
@ -34,35 +34,6 @@ sidebarDepth: 0
基类:`json.encoder.JSONEncoder` 基类:`json.encoder.JSONEncoder`
* **类型**
`json.JSONEncoder`
* **说明** * **说明**
`JSONEncoder` used when encoding `Message` (List of dataclasses) 在JSON序列化 `Message` (List[Dataclass]) 时使用的 `JSONEncoder`
### `default(o)`
Implement this method in a subclass such that it returns
a serializable object for `o`, or calls the base implementation
(to raise a `TypeError`).
For example, to support arbitrary iterators, you could
implement default like this:
```default
def default(self, o):
try:
iterable = iter(o)
except TypeError:
pass
else:
return list(iterable)
# Let the base class default method raise the TypeError
return JSONEncoder.default(self, o)
```

View File

@ -7,5 +7,6 @@ NoneBot Api Reference
- `nonebot.config <config.html>`_ - `nonebot.config <config.html>`_
- `nonebot.sched <sched.html>`_ - `nonebot.sched <sched.html>`_
- `nonebot.log <log.html>`_ - `nonebot.log <log.html>`_
- `nonebot.rule <rule.html>`_
- `nonebot.utils <utils.html>`_ - `nonebot.utils <utils.html>`_
- `nonebot.exception <exception.html>`_ - `nonebot.exception <exception.html>`_

12
docs_build/rule.rst Normal file
View File

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

View File

@ -4,8 +4,9 @@ sidebarDepth: 0
--- ---
NoneBot.utils 模块 NoneBot.utils 模块
================= ==================
.. automodule:: nonebot.utils
:members: .. autodecorator:: nonebot.utils.run_sync
:show-inheritance: .. autoclass:: nonebot.utils.DataclassEncoder
:show-inheritance:

View File

@ -136,7 +136,7 @@ def init(*, _env_file: Optional[str] = None, **kwargs):
:返回: :返回:
- `None` - ``None``
:用法: :用法:
@ -192,7 +192,7 @@ def run(host: Optional[str] = None,
:返回: :返回:
- `None` - ``None``
:用法: :用法:

View File

@ -4,14 +4,15 @@
import asyncio import asyncio
from nonebot.utils import run_sync from nonebot.utils import run_sync
from nonebot.typing import Bot, Event, Union, NoReturn, PermissionChecker from nonebot.typing import Bot, Event, Union, NoReturn, Callable, Awaitable, PermissionChecker
class Permission: class Permission:
__slots__ = ("checkers",) __slots__ = ("checkers",)
def __init__(self, *checkers: PermissionChecker) -> None: def __init__(self, *checkers: Callable[[Bot, Event],
self.checkers = list(checkers) Awaitable[bool]]) -> None:
self.checkers = set(checkers)
async def __call__(self, bot: Bot, event: Event) -> bool: async def __call__(self, bot: Bot, event: Event) -> bool:
if not self.checkers: if not self.checkers:
@ -25,13 +26,13 @@ class Permission:
def __or__(self, other: Union["Permission", def __or__(self, other: Union["Permission",
PermissionChecker]) -> "Permission": PermissionChecker]) -> "Permission":
checkers = [*self.checkers] checkers = self.checkers.copy()
if isinstance(other, Permission): if isinstance(other, Permission):
checkers.extend(other.checkers) checkers |= other.checkers
elif asyncio.iscoroutinefunction(other): elif asyncio.iscoroutinefunction(other):
checkers.append(other) checkers.add(other)
else: else:
checkers.append(run_sync(other)) checkers.add(run_sync(other))
return Permission(*checkers) return Permission(*checkers)

View File

@ -151,8 +151,6 @@ def on_command(cmd: Union[str, Tuple[str, ...]],
async def _strip_cmd(bot, event, state: dict): async def _strip_cmd(bot, event, state: dict):
message = event.message message = event.message
print(message[0].data)
print(state["_prefix"])
event.message = message.__class__( event.message = message.__class__(
str(message)[len(state["_prefix"]["raw_command"]):].strip()) str(message)[len(state["_prefix"]["raw_command"]):].strip())

View File

@ -1,5 +1,15 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
"""
规则
====
每个 ``Matcher`` 拥有一个 ``Rule`` 其中是 ``RuleChecker`` 的集合只有当所有 ``RuleChecker`` 检查结果为 ``True`` 时继续运行
\:\:\:tip 提示
``RuleChecker`` 既可以是 async function 也可以是 sync function
\:\:\:
"""
import re import re
import asyncio import asyncio
@ -10,28 +20,62 @@ from pygtrie import CharTrie
from nonebot import get_driver from nonebot import get_driver
from nonebot.log import logger from nonebot.log import logger
from nonebot.utils import run_sync from nonebot.utils import run_sync
from nonebot.typing import Bot, Any, Dict, Event, Union, Tuple, NoReturn, RuleChecker from nonebot.typing import Bot, Any, Dict, Event, Union, Tuple, NoReturn, Callable, Awaitable, RuleChecker
class Rule: class Rule:
"""
:说明:
``Matcher`` 规则类当事件传递时 ``Matcher`` 运行前进行检查
:示例:
.. code-block:: python
Rule(async_function) & sync_function
# 等价于
from nonebot.utils import run_sync
Rule(async_function, run_sync(sync_function))
"""
__slots__ = ("checkers",) __slots__ = ("checkers",)
def __init__(self, *checkers: RuleChecker) -> None: def __init__(
self.checkers = list(checkers) self, *checkers: Callable[[Bot, Event, dict],
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: 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( results = await asyncio.gather(
*map(lambda c: c(bot, event, state), self.checkers)) *map(lambda c: c(bot, event, state), self.checkers))
return all(results) return all(results)
def __and__(self, other: Union["Rule", RuleChecker]) -> "Rule": def __and__(self, other: Union["Rule", RuleChecker]) -> "Rule":
checkers = [*self.checkers] checkers = self.checkers.copy()
if isinstance(other, Rule): if isinstance(other, Rule):
checkers.extend(other.checkers) checkers |= other.checkers
elif asyncio.iscoroutinefunction(other): elif asyncio.iscoroutinefunction(other):
checkers.append(other) checkers.add(other) # type: ignore
else: else:
checkers.append(run_sync(other)) checkers.add(run_sync(other))
return Rule(*checkers) return Rule(*checkers)
def __or__(self, other) -> NoReturn: def __or__(self, other) -> NoReturn:

View File

@ -46,7 +46,7 @@ def overrides(InterfaceClass: object):
Driver = TypeVar("Driver", bound="BaseDriver") Driver = TypeVar("Driver", bound="BaseDriver")
""" """
:类型: `BaseDriver` :类型: ``BaseDriver``
:说明: :说明:
@ -54,7 +54,7 @@ Driver = TypeVar("Driver", bound="BaseDriver")
""" """
WebSocket = TypeVar("WebSocket", bound="BaseWebSocket") WebSocket = TypeVar("WebSocket", bound="BaseWebSocket")
""" """
:类型: `BaseWebSocket` :类型: ``BaseWebSocket``
:说明: :说明:
@ -63,7 +63,7 @@ WebSocket = TypeVar("WebSocket", bound="BaseWebSocket")
Bot = TypeVar("Bot", bound="BaseBot") Bot = TypeVar("Bot", bound="BaseBot")
""" """
:类型: `BaseBot` :类型: ``BaseBot``
:说明: :说明:
@ -71,7 +71,7 @@ Bot = TypeVar("Bot", bound="BaseBot")
""" """
Event = TypeVar("Event", bound="BaseEvent") Event = TypeVar("Event", bound="BaseEvent")
""" """
:类型: `BaseEvent` :类型: ``BaseEvent``
:说明: :说明:
@ -79,7 +79,7 @@ Event = TypeVar("Event", bound="BaseEvent")
""" """
Message = TypeVar("Message", bound="BaseMessage") Message = TypeVar("Message", bound="BaseMessage")
""" """
:类型: `BaseMessage` :类型: ``BaseMessage``
:说明: :说明:
@ -87,7 +87,7 @@ Message = TypeVar("Message", bound="BaseMessage")
""" """
MessageSegment = TypeVar("MessageSegment", bound="BaseMessageSegment") MessageSegment = TypeVar("MessageSegment", bound="BaseMessageSegment")
""" """
:类型: `BaseMessageSegment` :类型: ``BaseMessageSegment``
:说明: :说明:
@ -97,7 +97,7 @@ MessageSegment = TypeVar("MessageSegment", bound="BaseMessageSegment")
PreProcessor = Callable[[Bot, Event, dict], Union[Awaitable[None], PreProcessor = Callable[[Bot, Event, dict], Union[Awaitable[None],
Awaitable[NoReturn]]] Awaitable[NoReturn]]]
""" """
:类型: `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` :类型: ``Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]``
:说明: :说明:
@ -106,7 +106,7 @@ PreProcessor = Callable[[Bot, Event, dict], Union[Awaitable[None],
Matcher = TypeVar("Matcher", bound="MatcherClass") Matcher = TypeVar("Matcher", bound="MatcherClass")
""" """
:类型: `Matcher` :类型: ``Matcher``
:说明: :说明:
@ -114,15 +114,15 @@ Matcher = TypeVar("Matcher", bound="MatcherClass")
""" """
Rule = TypeVar("Rule", bound="RuleClass") Rule = TypeVar("Rule", bound="RuleClass")
""" """
:类型: `Rule` :类型: ``Rule``
:说明: :说明:
Rule 即判断是否响应事件的处理类内部存储 RuleChecker 返回全为 True 则响应事件 Rule 即判断是否响应事件的处理类内部存储 RuleChecker 返回全为 True 则响应事件
""" """
RuleChecker = Callable[[Bot, Event, dict], Awaitable[bool]] RuleChecker = Callable[[Bot, Event, dict], Union[bool, Awaitable[bool]]]
""" """
:类型: `Callable[[Bot, Event, dict], Awaitable[bool]]` :类型: ``Callable[[Bot, Event, dict], Union[bool, Awaitable[bool]]]``
:说明: :说明:
@ -130,15 +130,15 @@ RuleChecker = Callable[[Bot, Event, dict], Awaitable[bool]]
""" """
Permission = TypeVar("Permission", bound="PermissionClass") Permission = TypeVar("Permission", bound="PermissionClass")
""" """
:类型: `Permission` :类型: ``Permission``
:说明: :说明:
Permission 即判断是否响应消息的处理类内部存储 PermissionChecker 返回只要有一个 True 则响应消息 Permission 即判断是否响应消息的处理类内部存储 PermissionChecker 返回只要有一个 True 则响应消息
""" """
PermissionChecker = Callable[[Bot, Event], Awaitable[bool]] PermissionChecker = Callable[[Bot, Event], Union[bool, Awaitable[bool]]]
""" """
:类型: `Callable[[Bot, Event], Awaitable[bool]]` :类型: ``Callable[[Bot, Event], Union[bool, Awaitable[bool]]]``
:说明: :说明:
@ -147,7 +147,7 @@ PermissionChecker = Callable[[Bot, Event], Awaitable[bool]]
Handler = Callable[[Bot, Event, dict], Union[Awaitable[None], Handler = Callable[[Bot, Event, dict], Union[Awaitable[None],
Awaitable[NoReturn]]] Awaitable[NoReturn]]]
""" """
:类型: `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` :类型: ``Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]``
:说明: :说明:
@ -156,7 +156,7 @@ Handler = Callable[[Bot, Event, dict], Union[Awaitable[None],
ArgsParser = Callable[[Bot, Event, dict], Union[Awaitable[None], ArgsParser = Callable[[Bot, Event, dict], Union[Awaitable[None],
Awaitable[NoReturn]]] Awaitable[NoReturn]]]
""" """
:类型: `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` :类型: ``Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]``
:说明: :说明:

View File

@ -16,7 +16,7 @@ def run_sync(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
:参数: :参数:
* ``func: Callable[..., Any]``: 被装饰的同步函数 * ``func: Callable[..., Any]``: 被装饰的同步函数
:返回: :返回:
- Callable[..., Awaitable[Any]] - ``Callable[..., Awaitable[Any]]``
""" """
@wraps(func) @wraps(func)
@ -31,10 +31,8 @@ def run_sync(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
class DataclassEncoder(json.JSONEncoder): class DataclassEncoder(json.JSONEncoder):
""" """
:类型:
``json.JSONEncoder``
:说明: :说明:
``JSONEncoder`` used when encoding ``Message`` (List of dataclasses) 在JSON序列化 ``Message`` (List[Dataclass]) 时使用的 ``JSONEncoder``
""" """
@overrides(json.JSONEncoder) @overrides(json.JSONEncoder)