💡 add adapter docstring

This commit is contained in:
yanyongyu
2022-01-20 14:49:46 +08:00
parent 98ef09585a
commit aef585c60c
7 changed files with 115 additions and 98 deletions

View File

@ -21,26 +21,23 @@ class _ApiCall(Protocol):
class Bot(abc.ABC):
"""
Bot 基类。用于处理上报消息,并提供 API 调用接口。
"""Bot 基类。
用于处理上报消息,并提供 API 调用接口。
参数:
adapter: 协议适配器实例
self_id: 机器人 ID
"""
_calling_api_hook: Set[T_CallingAPIHook] = set()
"""
call_api 时执行的函数
"""
"""call_api 时执行的函数"""
_called_api_hook: Set[T_CalledAPIHook] = set()
"""
call_api 后执行的函数
"""
"""call_api 后执行的函数"""
def __init__(self, adapter: "Adapter", self_id: str):
"""
参数:
self_id: 机器人 ID
request: request 连接对象
"""
self.adapter: "Adapter" = adapter
"""协议适配器实例"""
self.self_id: str = self_id
"""机器人 ID"""
@ -49,19 +46,20 @@ class Bot(abc.ABC):
@property
def type(self) -> str:
"""协议适配器名称"""
return self.adapter.get_name()
@property
def config(self) -> Config:
"""全局 NoneBot 配置"""
return self.adapter.config
async def call_api(self, api: str, **data: Any) -> Any:
"""
调用机器人 API 接口,可以通过该函数或直接通过 bot 属性进行调用
"""调用机器人 API 接口,可以通过该函数或直接通过 bot 属性进行调用
参数:
api: API 名称
**data: API 数据
data: API 数据
用法:
```python
@ -121,41 +119,44 @@ class Bot(abc.ABC):
@abc.abstractmethod
async def send(
self, event: "Event", message: Union[str, "Message", "MessageSegment"], **kwargs
self,
event: "Event",
message: Union[str, "Message", "MessageSegment"],
**kwargs: Any,
) -> Any:
"""
调用机器人基础发送消息接口
"""调用机器人基础发送消息接口
参数:
event: 上报事件
message: 要发送的消息
kwargs: 任意额外参数
"""
raise NotImplementedError
@classmethod
def on_calling_api(cls, func: T_CallingAPIHook) -> T_CallingAPIHook:
"""
调用 api 预处理。
"""调用 api 预处理。
参数:
bot: 当前 bot 对象
api: 调用的 api 名称
data: api 调用的参数字典
插槽函数参数:
- bot: 当前 bot 对象
- api: 调用的 api 名称
- data: api 调用的参数字典
"""
cls._calling_api_hook.add(func)
return func
@classmethod
def on_called_api(cls, func: T_CalledAPIHook) -> T_CalledAPIHook:
"""
调用 api 后处理。
"""调用 api 后处理。
参数:
bot: 当前 bot 对象
exception: 调用 api 时发生的错误
api: 调用 api 名称
data: api 调用的参数字典
result: api 调用的返回
插槽函数参数:
- bot: 当前 bot 对象
- exception: 调用 api 时发生的错误
- api: 调用的 api 名称
- data: api 调用的参数字典
- result: api 调用的返回
"""
cls._called_api_hook.add(func)
return func