qq guild robot sdk with python3, support asyncio and synchronous
Project description
qq-bot-python
sdk安装
外发版本通过下面方式安装
pip install qq-bot # 注意是 qq-bot 而不是 qqbot!
更新包的话需要添加 --upgrade 注:需要python3.7+
sdk使用
需要使用的地方import SDK
import qqbot
示例机器人
``examples` <./examples/>`_ 目录下存放示例机器人,可供实现参考。
qqbot-API
基于 https://bot.q.qq.com/wiki/develop/api/ 机器人开放平台API实现的API接口封装。
使用方法
通过 import 对应API的类来进行使用,构造参数(Token 对象,是否沙盒模式)。
比如下面的例子,通过api当前机器人的相关信息:
import qqbot
token = qqbot.Token("{appid}","{token}")
api = qqbot.UserAPI(token, False)
user = api.me()
print(user.username) # 打印机器人名字
async 示例:
import qqbot
token = qqbot.Token("{appid}","{token}")
api = qqbot.AsyncUserAPI(token, False)
# 获取loop
loop = asyncio.get_event_loop()
user = loop.run_until_complete(api.me())
print(user.username) # 打印机器人名字
qqbot-事件监听
异步模块基于 websocket 技术用于监听频道内的相关事件,如消息、成员变化等事件,用于开发者对事件进行相应的处理。
使用方法
通过注册需要监听的事件并设置回调函数后,即可完成对事件的监听。
比如下面这个例子:需要监听机器人被@后消息并进行相应的回复。
先初始化需要用的 token 对象( appid和token参数从机器人管理端获取 )
通过 qqbot.listen_events 注册需要监听的事件
通过 qqbot.HandlerType 定义需要监听的事件(部分事件可能需要权限申请)
token = qqbot.Token("{appid}","{token}") # 注册事件类型和回调,可以注册多个 qqbot_handler = qqbot.Handler(qqbot.HandlerType.AT_MESSAGE_EVENT_HANDLER, _message_handler) qqbot.listen_events(token, False, qqbot_handler)
最后定义注册事件回调执行函数,如 _message_handler 。
def _message_handler(event, message: Message): msg_api = qqbot.MessageAPI(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)
async 示例:
# async的异步接口的使用示例 token = qqbot.Token("{appid}","{token}") qqbot_handler = qqbot.Handler(qqbot.HandlerType.AT_MESSAGE_EVENT_HANDLER, _message_handler) qqbot.async_listen_events(token, False, qqbot_handler)
async def _message_handler(event, message: qqbot.Message): """ 定义事件回调的处理 :param event: 事件类型 :param message: 事件对象(如监听消息是Message对象) """ msg_api = qqbot.AsyncMessageAPI(token, False) # 打印返回信息 qqbot.logger.info("event %s" % event + ",receive message %s" % message.content) for i in range(5): await asyncio.sleep(5) # 构造消息发送请求数据对象 send = qqbot.MessageSendRequest("<@%s>谢谢你,加油 " % message.author.id, message.id) # 通过api发送回复消息 await msg_api.post_message(message.channel_id, send)
注:当前支持事件及回调数据对象为:
class HandlerType(Enum): PLAIN_EVENT_HANDLER = 0 # 透传事件 GUILD_EVENT_HANDLER = 1 # 频道事件 GUILD_MEMBER_EVENT_HANDLER = 2 # 频道成员事件 CHANNEL_EVENT_HANDLER = 3 # 子频道事件 MESSAGE_EVENT_HANDLER = 4 # 消息事件 AT_MESSAGE_EVENT_HANDLER = 5 # At消息事件 # DIRECT_MESSAGE_EVENT_HANDLER = 6 # 私信消息事件 # AUDIO_EVENT_HANDLER = 7 # 音频事件
事件回调函数的参数 1 为事件名称,参数 2 返回具体的数据对象。
# 透传事件(无具体的数据对象,根据后台返回Json对象) def _plain_handler(event, data): # 频道事件 def _guild_handler(event, guild:Guild): # 频道成员事件 def _guild_member_handler(event, guild_member: GuildMember): # 子频道事件 def _channel_handler(event, channel: Channel): # 消息事件 # At消息事件 def _message_handler(event, message: Message):
日志打印
基于自带的 logging 模块封装的日志模块,提供了日志写入以及美化了打印格式,并支持通过设置 QQBOT_LOG_LEVEL 环境变量来调整日志打印级别(默认打印级别为 INFO)。
使用方法
引用模块,并获取 logger 实例:
from core.util import logging
logger = logging.getLogger()
或者通过qqbot.logger也可以获取logger对象
然后就可以愉快地使用 logger 进行打印。例如:
logger.info("hello world!")
设置日志级别
SDK默认的日志级别为INFO级别,需要修改请查看下面信息
Debug日志
命令行启动py后通过增加参数-d 或 --debug可以打开debug日志
python3 demo_at_reply.py -d
其他级别日志
通过 export 命令添加 QQBOT_LOG_LEVEL 环境变量可以设置日志级别。例如:
export QQBOT_LOG_LEVEL=10 # 10表示DEBUG级别
几个可选取值(参考了logging模块的取值):
Level |
取值 |
---|---|
CRITICAL |
50 |
ERROR |
40 |
WARNING |
30 |
INFO |
20 |
DEBUG |
10 |
NOTSET |
0 |
禁用日志文件输出
默认情况下 qqbot 会在当前执行目录下生成格式为 qqbot.log.* 的日志文件。如果想禁用这些日志文件,可以通过设置 QQBOT_DISABLE_LOG 环境变量为 1 来关闭。
export QQBOT_DISABLE_LOG=1 # 1表示禁用日志
修改日志输出路径
SDK也支持修改日志输出路径,由于实际路径不尽相同,所以此处使用 os 模块来设置临时环境变量。
import os
os.environ["QQBOT_LOG_PATH"] = os.path.join(os.getcwd(), "log", "%(name)s.log") # 日志将生成在执行目录下log文件夹内
修改日志格式
通过 export 命令添加 QQBOT_LOG_FILE_FORMAT 和 QQBOT_LOG_PRINT_FORMAT 环境变量可以设置日志格式。例如:
# 设置文件输出格式
export QQBOT_LOG_FILE_FORMAT="%(asctime)s [%(levelname)s] %(funcName)s (%(filename)s:%(lineno)s): %(message)s"
如需使用转义字符,可以使用 os 模块添加。例如:
# 设置控制台输出格式
import os
os.environ["QQBOT_LOG_PRINT_FORMAT"] = "%(asctime)s \033[1;33m[%(levelname)s] %(funcName)s (%(filename)s:%(lineno)s):\033[0m %(message)s"
sdk开发
环境配置
pip install -r requirements.txt # 安装依赖的pip包
pre-commit install # 安装格式化代码的钩子
单元测试
代码库提供API接口测试和 websocket 的单测用例,位于 tests 目录中。如果需要自己运行,可以在 tests 目录重命名 .test.yaml 文件后添加自己的测试参数启动测试:
# test yaml 用于设置test相关的参数,开源版本需要去掉参数
token:
appid: "xxx"
token: "xxxxx"
test_params:
guild_id: "xx"
guild_owner_id: "xx"
guild_owner_name: "xx"
guild_test_member_id: "xx"
guild_test_role_id: "xx"
channel_id: "xx"
channel_name: "xx"
robot_name: "xxx"
is_sandbox: False
单测执行方法:
先确保已安装 pytest :
pip install pytest
然后在项目根目录下执行单测:
pytest
加入官方社区
欢迎扫码加入QQ 频道开发者社区。
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file qq-bot-0.8.5.tar.gz
.
File metadata
- Download URL: qq-bot-0.8.5.tar.gz
- Upload date:
- Size: 38.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/34.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.9 tqdm/4.64.0 importlib-metadata/4.8.3 keyring/23.4.1 rfc3986/1.5.0 colorama/0.4.4 CPython/3.6.8
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | df9759abb621b42441539d31e460a8931edf33a83dab7ec256b6888d0b763544 |
|
MD5 | 8ee478ebe336cdfa5bcf37a3841a1acd |
|
BLAKE2b-256 | 0cc1f017fd94931386af0e98e1d8669e01761e3e89a6a325ad0544523fb6623b |
File details
Details for the file qq_bot-0.8.5-py3-none-any.whl
.
File metadata
- Download URL: qq_bot-0.8.5-py3-none-any.whl
- Upload date:
- Size: 53.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/34.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.9 tqdm/4.64.0 importlib-metadata/4.8.3 keyring/23.4.1 rfc3986/1.5.0 colorama/0.4.4 CPython/3.6.8
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9b4e1779b6d42e7d78733193de809fe035d864ecbd8ed6b67fc06aa23fa12442 |
|
MD5 | f58b6d2e6f373e42529c2ef229afb745 |
|
BLAKE2b-256 | 87fdba812ab4bdc9039d67d16d1d5e33a2536cbf1794b8cdfdd237bfdda0c81d |