| Name | herta-villa-sdk JSON |
| Version |
0.9.0
JSON |
| download |
| home_page | |
| Summary | 大别野「黑塔」Python SDK |
| upload_time | 2023-12-16 15:53:52 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
mihoyo
miyoushe
bot
villa
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Herta-villa-SDK
[](https://github.com/Herta-villa/Herta-villa-SDK/blob/master/LICENSE)
[](https://pypi.python.org/pypi/herta-villa-sdk)
[](https://github.com/astral-sh/ruff)
[](https://app.fossa.com/projects/git%2Bgithub.com%2FHerta-villa%2FHerta-villa-SDK?ref=badge_shield)
大别野「黑塔」Python SDK
## 特性
- 多种服务器后端（内置 `aiohttp` 和 `fastapi` 后端），完整异步支持
- 完整类型注解支持
- ...
## 安装
```shell
pip install herta-villa-sdk
```
FastAPI 后端支持:
```shell
pip install herta-villa-sdk[fastapi]
```
WebSocket 支持:
```shell
pip install herta-villa-sdk[ws]
```
## 快速开始
你需要拥有一个[大别野](https://dby.miyoushe.com/chat)机器人。可前往大别野[「机器人开发者社区」](https://dby.miyoushe.com/chat/463/20020)（`OpenVilla`）申请。
```python
from hertavilla import MessageChain, SendMessageEvent, VillaBot, run, StartswithResult
from hertavilla.server import init_backend
PUB_KEY = """-----BEGIN PUBLIC KEY-----
aaa
bbb
ccc
-----END PUBLIC KEY-----
""" # 开放平台 pub_key
# 需要注意 `-----BEGIN PUBLIC KEY-----` 前没有换行符
# `-----END PUBLIC KEY-----` 后有一个换行符
# 目前从网页端复制下来的时候会为一串 pub_key，需要将空格转为换行
bot = VillaBot(
"bot_id", # 这里填写 bot_id
"bot_secret", # 这里填写 secret
PUB_KEY, # 开放平台提供的 pub_key
callback_endpoint="/", # bot 回调 endpoint
# use_websocket=True, # 使用 WebSocket
# test_villa_id=0, # 测试别野，上线后可填 0
)
@bot.startswith("/") # 注册一个消息匹配器，匹配前缀为 / 的消息
async def _(event: SendMessageEvent, bot: VillaBot, match_result: StartswithResult):
if match_result.text == "hello":
chain = MessageChain("world")
await bot.send(event.villa_id, event.room_id, chain)
init_backend() # 初始化后端
run(bot) # 运行 bot
```
可以向你的 bot 发送 `@Bot /hello`，bot 会回复 `world`。
## 示例
详见 [examples](./examples/) 文件夹。
## WebSocket 支持
需在开放平台的「回调方式」中选择 「websocket回调」。
在实例化 `VillaBot` 时传入参数：
- `use_websocket` (bool) 启用 WebSocket
- `test_villa_id` (int) 测试别野，上线后可填 0
启动时会自动登录并接收事件。
### 手动下线
调用 `VillaBot.logout` 方法。
### Loop 后端
在不需要 HTTP WebHook 时，Herta SDK 提供了 `LoopBackend`。
此后端仅依靠异步 `loop` 运行。
同时增加了监视 WS 连接（所有连接断开[^1]时会自动关闭应用）
[^1]:机器人主动 Logout 或者被服务器踢下线
- `auto_shutdown` (bool) 启用自动关闭
- `watch_interval` (int) 监视间隔
## 支持的 API
- [x] 鉴权
- [x] 校验用户机器人访问凭证 `/checkMemberBotAccessToken`
- [x] 大别野
- [x] 获取大别野信息 `/getVilla`
- [x] 用户
- [x] 获取用户信息 `/getMember`
- [x] 获取大别野成员列表 `/getVillaMembers`
- [x] 踢出大别野用户 `/deleteVillaMember`
- [x] 消息
- [x] 置顶消息 `/pinMessage`
- [x] 撤回消息 `/recallMessage`
- [x] 发送消息 `/sendMessage`
- [x] 房间
- [x] 创建分组 `/createGroup`
- [x] 编辑分组 `/editGroup`
- [x] 删除分组 `/deleteGroup`
- [x] 获取分组列表 `/getGroupList`
- [x] 编辑房间 `/editRoom`
- [x] 删除房间 `/deleteRoom`
- [x] 获取房间信息 `/getRoom`
- [x] 获取房间列表信息 `/getVillaGroupRoomList`
- [x] 身份组
- [x] 向身份组操作用户 `/operateMemberToRole`
- [x] 创建身份组 `/createMemberRole`
- [x] 编辑身份组 `/editMemberRole`
- [x] 删除身份组 `/deleteMemberRole`
- [x] 获取身份组 `/getMemberRoleInfo`
- [x] 获取大别野下所有身份组 `/getVillaMemberRoles`
- [x] 表态表情
- [x] 获取全量表情 `/getAllEmoticons`
- [x] 图片
- [x] 图片转存 `/transferImage`
- [x] 获取图片上传参数 `/getUploadImageParams`
- [x] 审核 `/audit`
- [x] 获取 WebSocket 接入信息 `/getWebsocketInfo`
## 支持的事件
- [x] [JoinVilla](https://webstatic.mihoyo.com/vila/bot/doc/callback.html###JoinVilla) 有新用户加入大别野
- [x] [SendMessage](https://webstatic.mihoyo.com/vila/bot/doc/callback.html###SendMessage) 用户@机器人发送消息
- [x] [CreateRobot](https://webstatic.mihoyo.com/vila/bot/doc/callback.html###CreateRobot) 大别野添加机器人实例
- [x] [DeleteRobot](https://webstatic.mihoyo.com/vila/bot/doc/callback.html###DeleteRobot) 大别野删除机器人实例
- [x] [AddQuickEmoticon](https://webstatic.mihoyo.com/vila/bot/doc/callback.html#AddQuickEmoticon) 用户使用表情回复消息表态
- [x] [AuditCallback](https://webstatic.mihoyo.com/vila/bot/doc/callback.html#AuditCallback) 审核结果回调
## Bug 反馈及建议
大别野 Bot 和 Herta SDK 均处于开发状态中，如遇到问题或有相关建议可通过 [Issue](https://github.com/Herta-villa/Herta-villa-SDK/issues/new) 提出，感谢支持！
有关提出 Issue 和 Pull Request 的要点，请查看 [贡献指南](./CONTRIBUTING.md)。
## 相关项目
- [CMHopeSunshine/villa-py](https://github.com/CMHopeSunshine/villa-py) 米游社大别野 Bot Python SDK（非官方）
- [CMHopeSunshine/nonebot-adapter-villa](https://github.com/CMHopeSunshine/nonebot-adapter-villa) NoneBot2 米游社大别野 Bot 适配器
## 交流
- 前往大别野[「斩尽芜杂」](https://dby.miyoushe.com/chat/1785/25317)（`aaUeZqd`）
## 许可证
[MIT License](./LICENSE)
[](https://app.fossa.com/projects/git%2Bgithub.com%2FHerta-villa%2FHerta-villa-SDK?ref=badge_large)
Raw data
{
"_id": null,
"home_page": "",
"name": "herta-villa-sdk",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "mihoyo miyoushe bot villa",
"author": "",
"author_email": "MingxuanGame <MingxuanGame@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/47/b2/ff3ef76fd20bff9821dcdf5383d35f38da748f2c8eefd168289ef3b0dc03/herta_villa_sdk-0.9.0.tar.gz",
"platform": null,
"description": "# Herta-villa-SDK\n\n[](https://github.com/Herta-villa/Herta-villa-SDK/blob/master/LICENSE)\n[](https://pypi.python.org/pypi/herta-villa-sdk)\n\n[](https://github.com/astral-sh/ruff)\n[](https://app.fossa.com/projects/git%2Bgithub.com%2FHerta-villa%2FHerta-villa-SDK?ref=badge_shield)\n\n\u5927\u522b\u91ce\u300c\u9ed1\u5854\u300dPython SDK\n\n## \u7279\u6027\n\n- \u591a\u79cd\u670d\u52a1\u5668\u540e\u7aef\uff08\u5185\u7f6e `aiohttp` \u548c `fastapi` \u540e\u7aef\uff09\uff0c\u5b8c\u6574\u5f02\u6b65\u652f\u6301\n- \u5b8c\u6574\u7c7b\u578b\u6ce8\u89e3\u652f\u6301\n- ...\n\n## \u5b89\u88c5\n\n```shell\npip install herta-villa-sdk\n```\n\nFastAPI \u540e\u7aef\u652f\u6301:\n\n```shell\npip install herta-villa-sdk[fastapi]\n```\n\nWebSocket \u652f\u6301:\n\n```shell\npip install herta-villa-sdk[ws]\n```\n\n## \u5feb\u901f\u5f00\u59cb\n\n\u4f60\u9700\u8981\u62e5\u6709\u4e00\u4e2a[\u5927\u522b\u91ce](https://dby.miyoushe.com/chat)\u673a\u5668\u4eba\u3002\u53ef\u524d\u5f80\u5927\u522b\u91ce[\u300c\u673a\u5668\u4eba\u5f00\u53d1\u8005\u793e\u533a\u300d](https://dby.miyoushe.com/chat/463/20020)\uff08`OpenVilla`\uff09\u7533\u8bf7\u3002\n\n```python\nfrom hertavilla import MessageChain, SendMessageEvent, VillaBot, run, StartswithResult\nfrom hertavilla.server import init_backend\n\n\nPUB_KEY = \"\"\"-----BEGIN PUBLIC KEY-----\naaa\nbbb\nccc\n-----END PUBLIC KEY-----\n\"\"\" # \u5f00\u653e\u5e73\u53f0 pub_key\n# \u9700\u8981\u6ce8\u610f `-----BEGIN PUBLIC KEY-----` \u524d\u6ca1\u6709\u6362\u884c\u7b26\n# `-----END PUBLIC KEY-----` \u540e\u6709\u4e00\u4e2a\u6362\u884c\u7b26\n# \u76ee\u524d\u4ece\u7f51\u9875\u7aef\u590d\u5236\u4e0b\u6765\u7684\u65f6\u5019\u4f1a\u4e3a\u4e00\u4e32 pub_key\uff0c\u9700\u8981\u5c06\u7a7a\u683c\u8f6c\u4e3a\u6362\u884c\n\nbot = VillaBot(\n \"bot_id\", # \u8fd9\u91cc\u586b\u5199 bot_id\n \"bot_secret\", # \u8fd9\u91cc\u586b\u5199 secret\n PUB_KEY, # \u5f00\u653e\u5e73\u53f0\u63d0\u4f9b\u7684 pub_key\n callback_endpoint=\"/\", # bot \u56de\u8c03 endpoint\n # use_websocket=True, # \u4f7f\u7528 WebSocket\n # test_villa_id=0, # \u6d4b\u8bd5\u522b\u91ce\uff0c\u4e0a\u7ebf\u540e\u53ef\u586b 0\n)\n\n\n@bot.startswith(\"/\") # \u6ce8\u518c\u4e00\u4e2a\u6d88\u606f\u5339\u914d\u5668\uff0c\u5339\u914d\u524d\u7f00\u4e3a / \u7684\u6d88\u606f\nasync def _(event: SendMessageEvent, bot: VillaBot, match_result: StartswithResult):\n if match_result.text == \"hello\":\n chain = MessageChain(\"world\")\n await bot.send(event.villa_id, event.room_id, chain)\n\n\ninit_backend() # \u521d\u59cb\u5316\u540e\u7aef\nrun(bot) # \u8fd0\u884c bot\n```\n\n\u53ef\u4ee5\u5411\u4f60\u7684 bot \u53d1\u9001 `@Bot /hello`\uff0cbot \u4f1a\u56de\u590d `world`\u3002\n\n## \u793a\u4f8b\n\n\u8be6\u89c1 [examples](./examples/) \u6587\u4ef6\u5939\u3002\n\n## WebSocket \u652f\u6301\n\n\u9700\u5728\u5f00\u653e\u5e73\u53f0\u7684\u300c\u56de\u8c03\u65b9\u5f0f\u300d\u4e2d\u9009\u62e9 \u300cwebsocket\u56de\u8c03\u300d\u3002\n\n\u5728\u5b9e\u4f8b\u5316 `VillaBot` \u65f6\u4f20\u5165\u53c2\u6570\uff1a\n\n- `use_websocket` (bool) \u542f\u7528 WebSocket\n- `test_villa_id` (int) \u6d4b\u8bd5\u522b\u91ce\uff0c\u4e0a\u7ebf\u540e\u53ef\u586b 0\n\n\u542f\u52a8\u65f6\u4f1a\u81ea\u52a8\u767b\u5f55\u5e76\u63a5\u6536\u4e8b\u4ef6\u3002\n\n### \u624b\u52a8\u4e0b\u7ebf\n\n\u8c03\u7528 `VillaBot.logout` \u65b9\u6cd5\u3002\n\n### Loop \u540e\u7aef\n\n\u5728\u4e0d\u9700\u8981 HTTP WebHook \u65f6\uff0cHerta SDK \u63d0\u4f9b\u4e86 `LoopBackend`\u3002\n\n\u6b64\u540e\u7aef\u4ec5\u4f9d\u9760\u5f02\u6b65 `loop` \u8fd0\u884c\u3002\n\n\u540c\u65f6\u589e\u52a0\u4e86\u76d1\u89c6 WS \u8fde\u63a5\uff08\u6240\u6709\u8fde\u63a5\u65ad\u5f00[^1]\u65f6\u4f1a\u81ea\u52a8\u5173\u95ed\u5e94\u7528\uff09\n\n[^1]:\u673a\u5668\u4eba\u4e3b\u52a8 Logout \u6216\u8005\u88ab\u670d\u52a1\u5668\u8e22\u4e0b\u7ebf\n\n- `auto_shutdown` (bool) \u542f\u7528\u81ea\u52a8\u5173\u95ed\n- `watch_interval` (int) \u76d1\u89c6\u95f4\u9694\n\n## \u652f\u6301\u7684 API\n\n- [x] \u9274\u6743\n - [x] \u6821\u9a8c\u7528\u6237\u673a\u5668\u4eba\u8bbf\u95ee\u51ed\u8bc1 `/checkMemberBotAccessToken`\n- [x] \u5927\u522b\u91ce\n - [x] \u83b7\u53d6\u5927\u522b\u91ce\u4fe1\u606f `/getVilla`\n- [x] \u7528\u6237\n - [x] \u83b7\u53d6\u7528\u6237\u4fe1\u606f `/getMember`\n - [x] \u83b7\u53d6\u5927\u522b\u91ce\u6210\u5458\u5217\u8868 `/getVillaMembers`\n - [x] \u8e22\u51fa\u5927\u522b\u91ce\u7528\u6237 `/deleteVillaMember`\n- [x] \u6d88\u606f\n - [x] \u7f6e\u9876\u6d88\u606f `/pinMessage`\n - [x] \u64a4\u56de\u6d88\u606f `/recallMessage`\n - [x] \u53d1\u9001\u6d88\u606f `/sendMessage`\n- [x] \u623f\u95f4\n - [x] \u521b\u5efa\u5206\u7ec4 `/createGroup`\n - [x] \u7f16\u8f91\u5206\u7ec4 `/editGroup`\n - [x] \u5220\u9664\u5206\u7ec4 `/deleteGroup`\n - [x] \u83b7\u53d6\u5206\u7ec4\u5217\u8868 `/getGroupList`\n - [x] \u7f16\u8f91\u623f\u95f4 `/editRoom`\n - [x] \u5220\u9664\u623f\u95f4 `/deleteRoom`\n - [x] \u83b7\u53d6\u623f\u95f4\u4fe1\u606f `/getRoom`\n - [x] \u83b7\u53d6\u623f\u95f4\u5217\u8868\u4fe1\u606f `/getVillaGroupRoomList`\n- [x] \u8eab\u4efd\u7ec4\n - [x] \u5411\u8eab\u4efd\u7ec4\u64cd\u4f5c\u7528\u6237 `/operateMemberToRole`\n - [x] \u521b\u5efa\u8eab\u4efd\u7ec4 `/createMemberRole`\n - [x] \u7f16\u8f91\u8eab\u4efd\u7ec4 `/editMemberRole`\n - [x] \u5220\u9664\u8eab\u4efd\u7ec4 `/deleteMemberRole`\n - [x] \u83b7\u53d6\u8eab\u4efd\u7ec4 `/getMemberRoleInfo`\n - [x] \u83b7\u53d6\u5927\u522b\u91ce\u4e0b\u6240\u6709\u8eab\u4efd\u7ec4 `/getVillaMemberRoles`\n- [x] \u8868\u6001\u8868\u60c5\n - [x] \u83b7\u53d6\u5168\u91cf\u8868\u60c5 `/getAllEmoticons`\n- [x] \u56fe\u7247\n - [x] \u56fe\u7247\u8f6c\u5b58 `/transferImage`\n - [x] \u83b7\u53d6\u56fe\u7247\u4e0a\u4f20\u53c2\u6570 `/getUploadImageParams`\n- [x] \u5ba1\u6838 `/audit`\n- [x] \u83b7\u53d6 WebSocket \u63a5\u5165\u4fe1\u606f `/getWebsocketInfo`\n\n## \u652f\u6301\u7684\u4e8b\u4ef6\n\n- [x] [JoinVilla](https://webstatic.mihoyo.com/vila/bot/doc/callback.html###JoinVilla) \u6709\u65b0\u7528\u6237\u52a0\u5165\u5927\u522b\u91ce\n- [x] [SendMessage](https://webstatic.mihoyo.com/vila/bot/doc/callback.html###SendMessage) \u7528\u6237@\u673a\u5668\u4eba\u53d1\u9001\u6d88\u606f\n- [x] [CreateRobot](https://webstatic.mihoyo.com/vila/bot/doc/callback.html###CreateRobot) \u5927\u522b\u91ce\u6dfb\u52a0\u673a\u5668\u4eba\u5b9e\u4f8b\n- [x] [DeleteRobot](https://webstatic.mihoyo.com/vila/bot/doc/callback.html###DeleteRobot) \u5927\u522b\u91ce\u5220\u9664\u673a\u5668\u4eba\u5b9e\u4f8b\n- [x] [AddQuickEmoticon](https://webstatic.mihoyo.com/vila/bot/doc/callback.html#AddQuickEmoticon) \u7528\u6237\u4f7f\u7528\u8868\u60c5\u56de\u590d\u6d88\u606f\u8868\u6001\n- [x] [AuditCallback](https://webstatic.mihoyo.com/vila/bot/doc/callback.html#AuditCallback) \u5ba1\u6838\u7ed3\u679c\u56de\u8c03\n\n## Bug \u53cd\u9988\u53ca\u5efa\u8bae\n\n\u5927\u522b\u91ce Bot \u548c Herta SDK \u5747\u5904\u4e8e\u5f00\u53d1\u72b6\u6001\u4e2d\uff0c\u5982\u9047\u5230\u95ee\u9898\u6216\u6709\u76f8\u5173\u5efa\u8bae\u53ef\u901a\u8fc7 [Issue](https://github.com/Herta-villa/Herta-villa-SDK/issues/new) \u63d0\u51fa\uff0c\u611f\u8c22\u652f\u6301\uff01\n\n\u6709\u5173\u63d0\u51fa Issue \u548c Pull Request \u7684\u8981\u70b9\uff0c\u8bf7\u67e5\u770b [\u8d21\u732e\u6307\u5357](./CONTRIBUTING.md)\u3002\n\n## \u76f8\u5173\u9879\u76ee\n\n- [CMHopeSunshine/villa-py](https://github.com/CMHopeSunshine/villa-py) \u7c73\u6e38\u793e\u5927\u522b\u91ce Bot Python SDK\uff08\u975e\u5b98\u65b9\uff09\n- [CMHopeSunshine/nonebot-adapter-villa](https://github.com/CMHopeSunshine/nonebot-adapter-villa) NoneBot2 \u7c73\u6e38\u793e\u5927\u522b\u91ce Bot \u9002\u914d\u5668\n\n## \u4ea4\u6d41\n\n- \u524d\u5f80\u5927\u522b\u91ce[\u300c\u65a9\u5c3d\u829c\u6742\u300d](https://dby.miyoushe.com/chat/1785/25317)\uff08`aaUeZqd`\uff09\n\n## \u8bb8\u53ef\u8bc1\n\n[MIT License](./LICENSE)\n\n[](https://app.fossa.com/projects/git%2Bgithub.com%2FHerta-villa%2FHerta-villa-SDK?ref=badge_large)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\u5927\u522b\u91ce\u300c\u9ed1\u5854\u300dPython SDK",
"version": "0.9.0",
"project_urls": {
"Bug tracker": "https://github.com/Herta-villa/Herta-villa-SDK/issues",
"Documentation": "https://github.com/Herta-villa/Herta-villa-SDK",
"Homepage": "https://github.com/Herta-villa/Herta-villa-SDK",
"Repository": "https://github.com/Herta-villa/Herta-villa-SDK"
},
"split_keywords": [
"mihoyo",
"miyoushe",
"bot",
"villa"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0fc8b98b9ea792a52b269a0e8eb2c9e230e6e45df51ba700140ab8204d7da290",
"md5": "9b167e5c49a233a15223850932852082",
"sha256": "e66773df68a6ea124a2bc14302caca0ab60517acd17398c9cc0b4c998c533f1a"
},
"downloads": -1,
"filename": "herta_villa_sdk-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b167e5c49a233a15223850932852082",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 57807,
"upload_time": "2023-12-16T15:53:50",
"upload_time_iso_8601": "2023-12-16T15:53:50.289752Z",
"url": "https://files.pythonhosted.org/packages/0f/c8/b98b9ea792a52b269a0e8eb2c9e230e6e45df51ba700140ab8204d7da290/herta_villa_sdk-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "47b2ff3ef76fd20bff9821dcdf5383d35f38da748f2c8eefd168289ef3b0dc03",
"md5": "2064d64f6456f45ef82129063e92757a",
"sha256": "7359cd07677cad7cc2b14a9df91029ab3aaebb98bf07273950286c91fc77faea"
},
"downloads": -1,
"filename": "herta_villa_sdk-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "2064d64f6456f45ef82129063e92757a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 43160,
"upload_time": "2023-12-16T15:53:52",
"upload_time_iso_8601": "2023-12-16T15:53:52.012876Z",
"url": "https://files.pythonhosted.org/packages/47/b2/ff3ef76fd20bff9821dcdf5383d35f38da748f2c8eefd168289ef3b0dc03/herta_villa_sdk-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-16 15:53:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Herta-villa",
"github_project": "Herta-villa-SDK",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "herta-villa-sdk"
}
