python-sdk文档pr

docs/.vuepress/config.js

@@ -1,5 +1,6 @@
 const { convertSummary } = require('./summary-sidebar');
 const nodesdkConfig = require('../develop/nodesdk/config');
+const pythonsdkConfig = require('../develop/pythonsdk/config');
 const commonConfig = require('./common');
 // openapi 外部文档隐藏的接口,注意不要携带.md后缀
 // 废弃，请使用 summary-public 来约束可以展示的内容
@@ -115,6 +116,7 @@ module.exports = ctx => ({
         text: 'SDK文档',
         items: [
           nodesdkConfig.nav,
+          pythonsdkConfig.nav,
           {
             text: 'GoSDK',
             link: 'https://pkg.go.dev/github.com/tencent-connect/botgo',
@@ -138,6 +140,7 @@ module.exports = ctx => ({
     sidebar: {
       '/develop/api/': convertSummary('./docs/develop/api/SUMMARY-PUBLIC.md', hiddenApi, 1, true),
       ...nodesdkConfig.sidebar,
+      ...pythonsdkConfig.sidebar,
       '/': [''],
     },
 

docs/develop/pythonsdk/README.md

@@ -0,0 +1,97 @@
+# Python SDK 接入指南
+
+## 当前版本
+![PyPI](https://img.shields.io/pypi/v/qq-bot)
+
+## 安装
+
+``` bash
+pip install qq-bot
+```
+
+更新包的话需要添加 ``--upgrade`` ``注：需要python3.7+``
+
+## 使用示例-API访问
+
+下面的例子，通过api获取当前机器人的相关信息：
+
+``` py
+import qqbot
+
+token = qqbot.Token("{appid}","{token}")
+api = qqbot.UserAPI(token, False)
+user = api.me()
+
+print(user.username)  # 打印机器人名字
+```
+
+## 使用示例-异步消息
+
+通过注册需要监听的事件并设置回调函数后，即可完成对事件的监听。
+
+比如下面这个例子：需要监听机器人被@后消息并进行相应的回复。
+
+``` py
+# 先初始化需要用的 `token` 对象
+t_token = qqbot.Token(test_config["token"]["appid"], test_config["token"]["token"])
+# 通过 `qqbot.HandlerType` 定义需要监听的事件（部分事件可能需要权限申请）可以注册多个
+qqbot_handler = qqbot.Handler(qqbot.HandlerType.AT_MESSAGE_EVENT_HANDLER, _message_handler)
+# 通过 `qqbot.listen_events` 注册需要监听的事件
+qqbot.listen_events(t_token, False, qqbot_handler)
+
+# 定义注册事件回调执行函数,如 `_message_handler`
+def _message_handler(event, message: Message):
+    msg_api = qqbot.MessageAPI(t_token, False)
+    # 打印返回信息
+    qqbot.logger.info("event %s" % event + ",receive message %s" % message.content)
+    # 构造消息发送请求数据对象
+    send = qqbot.MessageSendRequest("<@%s>谢谢你，加油" % message.author.id, message.id)
+    # 通过api发送回复消息
+    msg_api.post_message(message.channel_id, send)
+```
+
+注：当前支持事件及回调事件可参考[事件监听](websocket/listen_events.md#当前支持的事件类型)
+
+## 日志打印
+
+基于自带的 logging 模块封装的日志模块，提供了日志写入以及美化了打印格式，并支持通过设置 `QQBOT_LOG_LEVEL` 环境变量来调整日志打印级别（默认打印级别为 `INFO`）。
+
+### 使用方法
+
+``` py
+# 引用模块
+from core.util import logging
+
+# 获取 `logger` 实例
+logger = logging.getLogger(__name__)
+
+# 打印日志
+logger.info("hello world!")
+```
+
+### 设置日志级别
+
+通过 `export` 命令添加 `QQBOT_LOG_LEVEL` 环境变量可以设置日志级别。例如：
+
+``` bash
+export QQBOT_LOG_LEVEL=10  # 10表示DEBUG级别
+```
+
+几个可选取值（参考了[logging模块的取值](https://docs.python.org/3/library/logging.html#levels)）：
+
+| Level | 取值 |
+| ----- | ------------- |
+| CRITICAL  | 50  |
+| ERROR | 40 |
+| WARNING | 30 |
+| INFO | 20 |
+| DEBUG | 10 |
+| NOTSET | 0 |
+
+### 禁用日志文件输出
+
+默认情况下 qqbot 会在当前执行目录下生成格式为 `qqbot.log.*` 的日志文件。如果想禁用这些日志文件，可以通过设置 `QQBOT_DISABLE_LOG` 环境变量为 1 来关闭。
+
+``` bash
+export QQBOT_DISABLE_LOG=1  # 1表示禁用日志
+```

docs/develop/pythonsdk/api/audio/post_audio.md

@@ -0,0 +1,43 @@
+# 音频控制
+
+## 使用示例
+
+```py
+import qqbot
+
+token = qqbot.Token({appid}, {token})
+
+audioApi = qqbot.AudioAPI(token, False)
+result = audioApi.post_audio(channel_id, audio_control)
+```
+
+## 参数说明
+
+| 字段名       | 类型                                    | 描述           |
+| ------------ | ------------------------------------- | -------------- |
+| channel_id    | String                                | 子频道 id      |
+| audio_control | [AudioControl](#audiocontrol) | audio 控制参数 |
+
+## 返回说明
+
+字段参见 [AudioControl](#audiocontrol)
+
+
+# 语音对象
+
+## AudioControl
+
+| 字段名    | 类型   | 描述                                                                  |
+| --------- | ------ | --------------------------------------------------------------------- |
+| audio_url | string | 音频数据的 url status 为 0 时传                                       |
+| text      | string | 状态文本（比如：简单爱-周杰伦），可选，status 为 0 时传，其他操作不传 |
+| status    | STATUS | 播放状态，参考 [STATUS](#STATUS)                                                 |
+
+### STATUS
+
+| 字段名 | 值  | 描述         |
+| ------ | --- | ------------ |
+| START  | 0   | 开始播放操作 |
+| PAUSE  | 1   | 暂停播放操作 |
+| RESUME | 2   | 继续播放操作 |
+| STOP   | 3   | 停止播放操作 |

docs/develop/pythonsdk/api/channel/create_channel.md

@@ -0,0 +1,98 @@
+# 创建子频道
+
+创建一个子频道。
+<Warnning />
+
+## 使用示例
+
+```python
+import qqbot
+
+token = qqbot.Token({appid}, {token})
+
+api = qqbot.ChannelAPI(token, False)
+channel_res = api.create_channel(channel_id, channel)
+```
+
+::: warning 注意
+
+- 要求操作人具有管理频道的权限，如果是机器人，则需要将机器人设置为管理员。
+- 创建成功后，返回创建成功的子频道对象，同时会触发一个频道创建的事件通知。
+- 目前不支持创建的子频道类型
+    - 子频道分组
+    - 私密子频道
+
+:::
+
+## 参数说明
+
+| 字段名  | 必填 | 类型                | 描述       |
+| ------- | ---- | ------------------- | ---------- |
+| guildId | 是   | string              | 频道 ID    |
+| channel | 是   | [Channel](#channel) | 子频道对象 |
+
+### Channel
+
+| 字段名    | 类型   | 必填 | 描述                                           |
+| --------- | ------ | ---- | ---------------------------------------------- |
+| name      | string | 是   | 子频道名                                       |
+| type      | number | 是   | 子频道类型 [ChannelType](#channeltype)         |
+| sub_type  | number | 是   | 子频道子类型 [ChannelSubType](#channelsubtype) |
+| position  | number | 否   | 排序，必填，而且不能够和其他子频道的值重复     |
+| parent_id | string | 否   | 分组 ID                                        |
+
+### ChannelType
+
+| 值    | 描述         |
+| ----- | ------------ |
+| 0     | 文字子频道   |
+| 1     | 保留，不可用 |
+| 2     | 语音子频道   |
+| 3     | 保留，不可用 |
+| 4     | 子频道分组   |
+| 10005 | 直播子频道   |
+| 10006 | 应用子频道   |
+| 10007 | 论坛子频道   |
+
+注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。
+
+### ChannelSubType
+
+| 值  | 描述 |
+| --- | ---- |
+| 0   | 闲聊 |
+| 1   | 公告 |
+| 2   | 攻略 |
+| 3   | 开黑 |
+
+## 返回说明
+
+返回 [ChannelRes](#channelres) 对象。
+
+### ChannelRes
+
+| 字段名    | 类型   | 描述                                           |
+| --------- | ------ | ---------------------------------------------- |
+| id        | string | 子频道 ID                                      |
+| guild_id  | string | 频道 ID                                        |
+| name      | string | 子频道名                                       |
+| type      | number | 子频道类型 [ChannelType](#channeltype)         |
+| sub_type  | number | 子频道子类型 [ChannelSubType](#channelsubtype) |
+| position  | number | 排序，必填，而且不能够和其他子频道的值重复     |
+| owner_id | string | 创建者 ID                                        |
+
+## 返回示例
+
+`data`：
+
+```json
+{
+    "id": "channel_id",
+    "guild_id": "guild_id",
+    "name": "channel_test",
+    "type": 1,
+    "position": 1640240055,
+    "owner_id": "2854198244",
+    "sub_type": 0
+}
+```

docs/develop/pythonsdk/api/channel/delete_channel.md

@@ -0,0 +1,71 @@
+# 删除子频道
+
+移除一个子频道。
+
+<Warnning />
+
+## 使用示例
+
+```python
+import qqbot
+
+token = qqbot.Token({appid}, {token})
+
+api = qqbot.ChannelAPI(token, False)
+channel = api.delete_channel(channel_id)
+```
+
+::: warning 注意
+
+- 要求操作人具有`管理频道`的权限，如果是机器人，则需要将机器人设置为管理员。
+- 创建成功后，返回创建成功的子频道对象，同时会触发一个频道创建的事件通知。
+- 子频道的删除是无法撤回的，一旦删除，将无法恢复。
+
+:::
+
+## 参数说明
+
+| 字段名    | 必填 | 类型   | 描述      |
+| --------- | ---- | ------ | --------- |
+| channel_id | 是   | string | 子频道 ID |
+
+## 返回说明
+
+字段参见 [ChannelRes](#channelres)
+
+### ChannelRes
+
+| 字段名   | 类型   | 描述                                   |
+| -------- | ------ | -------------------------------------- |
+| id       | string | 子频道 ID                              |
+| guild_id | string | 频道 ID                                |
+| name     | string | 子频道名                               |
+| type     | number | 子频道类型 [ChannelType](#channeltype) |
+
+### ChannelType
+
+| 值    | 描述         |
+| ----- | ------------ |
+| 0     | 文字子频道   |
+| 1     | 保留，不可用 |
+| 2     | 语音子频道   |
+| 3     | 保留，不可用 |
+| 4     | 子频道分组   |
+| 10005 | 直播子频道   |
+| 10006 | 应用子频道   |
+| 10007 | 论坛子频道   |
+
+注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。
+
+## 返回示例
+
+`data`：
+
+```json
+{
+    "id":"channel_id",
+    "type":0,
+    "name":"update_channel",
+    "guild_id":"2020131797974366736"
+}
+```