A Python SDK for CQHTTP.
Project description
CQHTTP Python SDK
本项目为 CQHTTP 插件的 Python SDK,封装了 web server 相关的代码,让使用 Python 的开发者能方便地开发插件。
关于 CQHTTP 插件,见 richardchien/coolq-http-api。
用法
首先安装 cqhttp
包:
pip install cqhttp
注意可能需要把 pip
换成 pip3
。本 SDK 依赖于 Flask
和 requests
包,因此它们也会被安装。
也可以克隆本仓库之后用 python setup.py install
来安装。
然后新建 Python 文件,运行 bot:
from cqhttp import CQHttp
bot = CQHttp(api_root='http://127.0.0.1:5700/',
access_token='your-token',
secret='your-secret')
@bot.on_message
def handle_msg(event):
bot.send(event, '你好呀,下面一条是你刚刚发的:')
return {'reply': event['message'], 'at_sender': False}
@bot.on_notice('group_increase') # 如果插件版本是 3.x,这里需要使用 @bot.on_event
def handle_group_increase(event):
bot.send(event, message='欢迎新人~', auto_escape=True) # 发送欢迎新人
@bot.on_request('group', 'friend')
def handle_request(event):
return {'approve': True} # 同意所有加群、加好友请求
bot.run(host='127.0.0.1', port=8080, debug=True)
创建实例
首先创建 CQHttp
类的实例,传入 api_root
,即为 CQHTTP 插件的监听地址,例如 http://127.0.0.1:5700
,如果你不需要调用 API,也可以不传入。Access token 和签名密钥也在这里传入,如果没有配置 access_token
或 secret
项,则不传。
事件处理
on_message
、on_notice
、on_request
、on_meta_event
装饰器分别对应插件的四个上报类型(post_type
),括号中指出要处理的消息类型(message_type
)、通知类型(notice_type
)、请求类型(request_type
)、元事件类型(meta_event_type
),一次可指定多个,如果留空,则会处理所有这个上报类型的上报。在上面的例子中 handle_msg
函数将会在收到任意渠道的消息时被调用,handle_group_increase
函数会在群成员增加时调用。
上面装饰器装饰的函数,统一接受一个参数,即为上报的数据,具体数据内容见 事件上报;返回值可以是一个字典,会被自动作为 JSON 响应返回给 CQHTTP 插件,具体见 上报请求的响应数据格式。
API 调用
在设置了 api_root
的情况下,直接在 CQHttp
类的实例上就可以调用 API,例如 bot.send_private_msg(user_id=123456, message='hello')
,这里的 send_private_msg
即为 /send_private_msg
发送私聊消息 中的 /send_private_msg
,API 所需参数直接通过命名参数(keyword argument)传入。其它 API 见 API 列表。
为了简化发送消息的操作,提供了 send(context, message)
函数,这里的第一个参数 context
也就是上报数据,传入之后函数会自己判断当前需要发送到哪里(哪个好友,或哪个群),无需手动再指定,其它参数仍然可以从 keyword argument 指定,例如 auto_escape=True
。
每个 API 调用最后都会由 requests
库来发出请求,如果网络无法连接,它可能会抛出 ConnectionError
等异常,见 错误与异常。而一旦请求成功,本 SDK 会判断 HTTP 响应状态码,只有当状态码为 200,且 status
字段为 ok
或 async
时,会返回 data
字段的内容,否则抛出 cqhttp.Error
异常,在这个异常中你可以通过 status_code
和 retcode
属性来获取 HTTP 状态码和插件的 retcode
(如果状态码不为 200,则 retcode
为 None),具体响应状态码和 retcode
的含义,见 响应说明。
运行实例
使用装饰器定义好处理函数之后,调用 bot.run()
即可运行。你需要传入 host
和 port
参数,来指定服务端需要运行在哪个地址,然后在 CQHTTP 插件的配置文件中,在 post_url
项填写此地址(http://host:port/
)。
CQHttp Helper
项目根目录下的 cqhttp_helper.py
文件是 SuperMarioSF 贡献的帮助类,在 CQHttp
类的基础上提供了每个 API 调用的具体函数,以便在支持的代码编辑器中使用代码补全和文档速览。
注意,此文件不在 pip 安装的包中,需单独下载,如果以后插件新增接口,此文件可能没有及时更新,但不影响使用,你仍然可以像使用原始的 CQHttp
一样使用它。
部署
bot.run()
只适用于开发环境,不建议用于生产环境,因此 SDK 从 1.2.1 版本开始提供 bot.wsgi
属性以获取其内部兼容 WSGI 的 app 对象,从而可以使用 Gunicorn、uWSGI 等软件来部署。
添加路由
CQHttp
内部使用 Flask 来提供 web server,默认添加了 bot 所需的 /
路由,如需添加其它路由,例如在 /admin/
提供管理面板访问,可以通过 bot.server_app
访问内部的 Flask
实例来做到:
app = bot.server_app
@app.route('/admin')
async def admin():
return 'This is the admin page.'
目前 bot.server_app
和 bot.wsgi
等价。
更新日志
更新日志见 CHANGELOG.md。
遇到问题
本 SDK 的代码非常简单,如果发现有问题可以参考下源码,可以自行做一些修复,也欢迎提交 pull request 或 issue。
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file cqhttp-1.3.1.tar.gz
.
File metadata
- Download URL: cqhttp-1.3.1.tar.gz
- Upload date:
- Size: 6.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.42.0 CPython/3.8.1
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
4cb0dae03872162df395ef49f3bb2ec69501cc0d686193dfb1b413097b062821
|
|
MD5 |
307ee51afcfe4ce3310561dde70a2e66
|
|
BLAKE2b-256 |
6251a2967893f89e7c196a5dca7d50dbac4d9c1cb441dc56f94f888da0fa8baf
|