1"""
  2# PigBotFramework文档
  3这是 PigBotFramework（后简称PBF） Next 的文档。 <br>
  4由此文档，您可以查阅到PBF Next的接口定义。 <br>
  5接下来的内容将带您运行PBF服务器以及创建一个简单插件。
  6
  7
  8
  9# 快速开始
 10## 运行PBF服务器
 11### Step 1: 前置准备
 12- 安装Python3.8及以上版本
 13- 通过pip安装`PigBotFramework`模块
 14    ```shell
 15    pip install PigBotFramework --upgrade
 16    ```
 17- 创建一个新的目录`/app`，用于存放PBF的配置文件和插件
 18
 19### Step 2: 创建主文件
 20在`/app`目录下创建一个`main.py`文件，并写入以下内容
 21```python
 22# Step 1: import config and modify it
 23from pbf import config
 24
 25config.logs_level = "DEBUG"
 26# modify more config here
 27
 28# Step 2: import setup and setup PBF
 29from pbf import setup
 30setup.setup(__name__)
 31
 32# Step 3: import driver and start it
 33if __name__ == "__main__":
 34    from pbf.driver import Fastapi
 35
 36    Fastapi.start()
 37```
 38接下来，我将为您逐行解释这段代码
 39- Step 1: 导入PBF的配置模块，并修改配置
 40    - `from pbf import config`：导入PBF的配置模块
 41    - `config.logs_level = "DEBUG"`：将日志等级设置为`DEBUG`
 42    - 您还可以在这部分设置更多的配置，详见[具体配置](/pbf/docs/config.html)
 43- Step 2: 初始化PBF
 44    - `from pbf import setup`：导入PBF的初始化模块
 45    - `setup.setup(__name__)`：初始化PBF
 46- Step 3: 导入驱动并启动
 47    - `from pbf.driver import Fastapi`：导入Fastapi驱动
 48    - `Fastapi.start()`：启动Fastapi驱动
 49
 50**注意：在导入pbf.setup以及.driver.*之前，您必须先导入pbf.config并修改配置，否则之后修改的配置将会无法生效**
 51
 52### Step 3: 运行主文件
 53运行刚刚编辑的`main.py`文件，服务器就会启动
 54- 默认的Fastapi驱动会监听在`http://localhost:8000`上
 55- PBF默认会从`~/.pbf/plugins`目录下加载插件
 56- 日志文件默认会输出到`~/.pbf/logs`目录下
 57
 58
 59
 60## 创建一个简单插件
 61### Step 1: 创建插件
 621. 在`/app`目录下创建一个`plugins`目录，用于存放插件
 632. 在`~/.pbf/plugins`目录下创建一个`foo.py`文件，这就是我们要完成的新插件
 64
 65### Step 2: 创建元数据
 66我们需要创建一个`meta_data`变量，来声明插件的元数据
 67```python
 68from pbf.utils import MetaData
 69# 插件元数据
 70meta_data = MetaData(
 71    name="test",
 72    version="0.1.0",
 73    versionCode=10,
 74    description="PBF Plugin",
 75    author="XzyStudio",
 76    license="MIT",
 77    keywords=["pbf", "plugin"],
 78    readme=\"\"\"
 79    # PBF Plugin
 80    hi
 81    \"\"\"
 82)
 83```
 84MetaData的参数如下：
 85- `name` (str)：插件名称
 86- `version` (str)：插件版本
 87- `versionCode` (int)：插件版本号
 88- `description` (str)：插件描述
 89- `author` (str)：插件作者
 90- `license` (str)：插件许可证
 91- `keywords` (List[str])：插件关键字
 92- `readme` (str)：插件README
 93
 94### Step 3.1: 创建`_enter`
 95有的时候，我们需要让插件在被装载时执行某些操作，这时我们需要定义`_enter`函数
 96```python
 97from pbf.setup import logger
 98# 在PBF启动时、插件被装载时调用
 99def _enter():  # 如不需要可以删除
100    logger.info("Test PBF Plugin loaded")
101```
102这里我们从`pbf.setup`中导入了`logger`，此后我们都可以使用`logger`来输出日志。 <br>
103当然，如果您不需要`_enter`，也完全可以不定义他。
104
105> **Tip: 确切来说，`_enter`函数会在插件被装载时调用，而非PBF启动时** <br>
106> 因为对于Fastapi来说，执行的文件`main.py`会有两次被调用， <br>
107> 第一次的`__name__`为`"__main__"`，这也就是运行`python main.py`的那次 <br>
108> 在启动Fastapi后，uvicorn会再次调用`main.py`，这次的`__name__`为`"__mp_main__"`， <br>
109> 而`_enter`（以及下文的`_exit`）函数会在`"__mp_main__"`时调用 <br>
110> 同时，如果uvicorn开启了debug模式，重载时会先`shutdown application`，此时.controller.PluginsManager会调用`_exit`卸载插件， <br>
111> 然后，会`startup application`，此时调用`_enter`
112
113### Step 3.2: 创建`_exit`
114顾名思义，`_exit`函数会在插件卸载时调用
115```python
116def _exit():  # 如不需要可以删除
117    logger.info("Test PBF Plugin unloaded")
118```
119当然，如果您不需要`_exit`，也完全可以不定义他。
120
121### Step 4: 创建接口
122有的时候，我们需要在插件之间进行互通，这时我们可以定义一些开放给其他插件使用的接口
123```python
124# 插件开放给其他插件调用的接口
125class Api:  # 如不需要可以删除
126    @staticmethod
127    def foo():  # 可以在其他插件中通过 `pbf.pluginsManager.require("this_plugin_name").foo()` 调用
128        return "bar"
129```
130这里我们定义了一个`Api`类，开放的接口都需要在这个类中定义。 <br>
131需要注意的是，这里的接口都是静态方法。 <br>
132我们在其他插件中可以通过`pbf.pluginsManager.require("this_plugin_name(foo)").foo()`来调用这个接口。 <br>
133当然，如果您不需要开放接口，也完全可以不定义他。
134
135### Step 5: 创建监听器
136插件的主体功能就是处理某些事件。这里有五类事件：`Command`, `Message`, `Notice`, `Request`, `Meta`。 <br>
137我们使用`pbf.Register`装饰器来注册监听器：
138```python
139from pbf.utils.Register import Command, Message, Notice, Request, Meta
140from pbf.controller.Data import Event
141# 注册指令，匹配消息文本开头的"test"
142@Command(name="test", description="test command")
143def testCommand(event: Event):
144    logger.info(f"test command was called: {event}")
145    # do something
146    logger.info(
147        Msg("恭喜！当你收到这条消息，意味着您的第一个插件成功运行！", event=event).send())
148    # 这是发送一条消息，Msg类是基于Client类的封装，具体使用请见文档
149```
150这里我们定义了一个`test`指令，当用户发送`test`开头的文本时，这个指令就会被调用。 <br>
151您可以注意到`event`对象，这个对象里面包含了这个事件的所有信息。您可以在[这里](/pbf/controller/Data.html#Event)了解到更多信息。 <br>
152`Command`以及`Message`, `Notice`, `Request`, `Meta`封装自`pbf.utils.Register`，接受参数如下：
153- `name` (str)：指令名称
154- `description` (str)：指令描述
155- `permission` (str)：指令权限
156- `usage` (str)：指令使用方法
157- `alias` (List[str])：指令别名 默认为空
158- `hidden` (bool)：是否隐藏指令 默认为False
159- `enabled` (bool)：是否启用指令 默认为True
160
161同样的，我们还可以创建`Message`, `Notice`, `Request`, `Meta`监听器：
162```python
163@Message(name="message handler")  # 注册消息处理器，会处理所有消息
164def messageHandler(event: Event):
165    logger.info(f"message handler was called: {event}")
166    # do something
167
168
169@Notice(name="notice handler")  # 注册通知处理器，会处理所有通知
170def noticeHandler(event: Event):
171    logger.info(f"notice handler was called: {event}")
172    # do something
173
174
175@Request(name="request handler")  # 注册请求处理器，会处理所有请求
176def requestHandler(event: Event):
177    logger.info(f"request handler was called: {event}")
178    # do something
179
180
181@Meta(name="meta handler")  # 注册元数据处理器，会处理所有元数据
182def metaHandler(event: Event):
183    logger.info(f"meta handler was called: {event}")
184    # do something
185```
186您还可以设置指令别名、使用正则匹配、自定义权限、隐藏指令、添加调用限制等等，具体参见 pbf.docs
187
188### Step 6: 重新加载插件
189如果您的PBF服务器已启动，您可以访问`{your_server_address}/plugins/load_all`来重新加载插件
190
191### Step 7: 测试插件
192对机器人发送`test`，如果您收到回复，恭喜您，您的插件已经成功运行了
193
194### Step 8: 其他
195- 通常情况下，我们的插件并不是以单文件方式呈现，因此我们可以在`~/.pbf/plugins`目录下创建一个包，在这个包里面编写插件（目录结构如下）
196    ```
197    /.pbf
198    ├── plugins
199    |   └── foo
200    |       ├── __init__.py  # 你的插件主体
201    |       ├── README.md
202    |       └── LICENSE
203    └── logs
204    ```
205- 我们有一个插件模板，您可以在[PigBotFrameworkPlugins/template](https://github.com/PigBotFrameworkPlugins/template)找到。
206
207
208
209# 更多内容
210关于插件及PBF开发的更多内容，您可以点击左侧的模块列表查看。 <br>
211这里有一些进阶使用教程参见 [Xzy's Blog](https://blog.xzynb.top/tag/PBFNext/)
212"""
213
214
215# Version
216version = "5.0.12"
217version_code = 241130
218version_name = version