<div align="center">
<a href="https://v2.nonebot.dev/">
<img src="https://v2.nonebot.dev/logo.png" width="200" height="200" alt="nonebot">
</a>
# nonebot-plugin-session
_✨ [Nonebot2](https://github.com/nonebot/nonebot2) 会话信息提取与会话 id 定义插件 ✨_
<p align="center">
<img src="https://img.shields.io/github/license/noneplugin/nonebot-plugin-session" alt="license">
<img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="Python">
<img src="https://img.shields.io/badge/nonebot-2.0.0+-red.svg" alt="NoneBot">
<a href="https://pypi.org/project/nonebot-plugin-session">
<img src="https://badgen.net/pypi/v/nonebot-plugin-session" alt="pypi">
</a>
</p>
</div>
- 这个插件可以做什么？
本插件提供了一个统一的会话模型 `Session`，
可以从不同适配器的 `Bot` 和 `Event` 中提取与会话相关的
“平台”、“会话等级”（单用户、单级群组、两级群组）、“目标 id” 等属性；
同时提供了获取会话 id 的函数，可以按照不同的类型获取会话id，方便不同场景下的使用
- 这个插件解决了什么问题？
Nonebot 适配器基类中提供了 `get_session_id` 函数用于获取会话 id，
但这一结果通常是 用户 id、群组 id 的组合，属于 “用户级别” 的 id，
但在很多插件中，需要用到 “群组级别” 的会话 id，如词云、词库等等
本插件可以为不同适配器提供一个统一的、可选级别的会话 id 定义方式
### 安装
- 使用 nb-cli
```
nb plugin install nonebot_plugin_session
```
- 使用 pip
```
pip install nonebot_plugin_session
```
### 使用
获取 `Session`：
```python
from nonebot_plugin_session import extract_session
@matcher.handle()
async def handle(bot: Bot, event: Event):
session = extract_session(bot, event)
```
获取 `session id`：
```python
from nonebot_plugin_session import SessionId, SessionIdType
@matcher.handle()
async def handle(session_id: str = SessionId(SessionIdType.GROUP)):
# 获取 “群组级别” 的 session id
...
```
将 `Session` 存至数据库中（需要安装 [nonebot-plugin-datastore](https://github.com/he0119/nonebot-plugin-datastore) 插件）
```python
from nonebot_plugin_datastore import create_session
from nonebot_plugin_session import extract_session
from nonebot_plugin_session.model import get_or_add_session_model
@matcher.handle()
async def handle(bot: Bot, event: Event):
session = extract_session(bot, event)
async with create_session() as db_session:
session_model = await get_or_add_session_model(session, db_session) # 可关联其他表用于筛选等
```
从 `Session` 中获取 `saa` 的 `PlatformTarget` 对象用于发送（需要安装 [nonebot-plugin-send-anything-anywhere](https://github.com/felinae98/nonebot-plugin-send-anything-anywhere) 插件）
```python
from nonebot_plugin_session import extract_session
@matcher.handle()
async def handle(bot: Bot, event: Event):
session = extract_session(bot, event)
target = session.get_saa_target() # 用于发送
```
不同的 “会话级别” 与 “会话id类型” 下返回的 id 如下表所示：（不包含 `bot_id` 等属性的情况）
| | LEVEL0<br>（无用户） | LEVEL1<br>（单用户） | LEVEL2<br>（单级群组） | LEVEL3<br>（两级群组） |
| --- | --- | --- | --- | --- |
| TYPE0 (GLOBAL) | `""` | `""` | `""` | `""` |
| TYPE1 (USER) | `""` | `"id1"` | `"id1"` | `"id1"` |
| TYPE2 | `""` | `"id1"` | `"id2"` | `"id2"` |
| TYPE3 | `""` | `"id1"` | `"id2_id1"` | `"id2_id1"` |
| TYPE4 | `""` | `"id1"` | `"id2"` | `"id3"` |
| TYPE5 | `""` | `"id1"` | `"id2_id1"` | `"id3_id1"` |
| TYPE6 (GROUP) | `""` | `"id1"` | `"id2"` | `"id3_id2"` |
| TYPE7 (GROUP_USER) | `""` | `"id1"` | `"id2_id1"` | `"id3_id2_id1"` |
### 支持的 adapter
| OneBot v11 | OneBot v12 | Console | Kaiheila | QQ Guild | Telegram |
| :--------: | :--------: | :------: | :------: | :------: | :------: |
| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
### 鸣谢
- [nonebot-plugin-send-anything-anywhere](https://github.com/felinae98/nonebot-plugin-send-anything-anywhere) 项目的灵感来源以及部分实现的参考
- [uy/sun](https://github.com/he0119) 感谢歪日佬的技术支持
Raw data
{
"_id": null,
"home_page": "https://github.com/noneplugin/nonebot-plugin-session",
"name": "nonebot-plugin-session",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "meetwq",
"author_email": "meetwq@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1e/c5/f36eda2b8211b29294f0047712e1148f226d15e23101ced79c3f43e22ac0/nonebot_plugin_session-0.0.8.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n <a href=\"https://v2.nonebot.dev/\">\n <img src=\"https://v2.nonebot.dev/logo.png\" width=\"200\" height=\"200\" alt=\"nonebot\">\n </a>\n\n# nonebot-plugin-session\n\n_\u2728 [Nonebot2](https://github.com/nonebot/nonebot2) \u4f1a\u8bdd\u4fe1\u606f\u63d0\u53d6\u4e0e\u4f1a\u8bdd id \u5b9a\u4e49\u63d2\u4ef6 \u2728_\n\n<p align=\"center\">\n <img src=\"https://img.shields.io/github/license/noneplugin/nonebot-plugin-session\" alt=\"license\">\n <img src=\"https://img.shields.io/badge/python-3.8+-blue.svg\" alt=\"Python\">\n <img src=\"https://img.shields.io/badge/nonebot-2.0.0+-red.svg\" alt=\"NoneBot\">\n <a href=\"https://pypi.org/project/nonebot-plugin-session\">\n <img src=\"https://badgen.net/pypi/v/nonebot-plugin-session\" alt=\"pypi\">\n </a>\n</p>\n\n</div>\n\n\n- \u8fd9\u4e2a\u63d2\u4ef6\u53ef\u4ee5\u505a\u4ec0\u4e48\uff1f\n\n\u672c\u63d2\u4ef6\u63d0\u4f9b\u4e86\u4e00\u4e2a\u7edf\u4e00\u7684\u4f1a\u8bdd\u6a21\u578b `Session`\uff0c\n\u53ef\u4ee5\u4ece\u4e0d\u540c\u9002\u914d\u5668\u7684 `Bot` \u548c `Event` \u4e2d\u63d0\u53d6\u4e0e\u4f1a\u8bdd\u76f8\u5173\u7684\n\u201c\u5e73\u53f0\u201d\u3001\u201c\u4f1a\u8bdd\u7b49\u7ea7\u201d\uff08\u5355\u7528\u6237\u3001\u5355\u7ea7\u7fa4\u7ec4\u3001\u4e24\u7ea7\u7fa4\u7ec4\uff09\u3001\u201c\u76ee\u6807 id\u201d \u7b49\u5c5e\u6027\uff1b\n\n\u540c\u65f6\u63d0\u4f9b\u4e86\u83b7\u53d6\u4f1a\u8bdd id \u7684\u51fd\u6570\uff0c\u53ef\u4ee5\u6309\u7167\u4e0d\u540c\u7684\u7c7b\u578b\u83b7\u53d6\u4f1a\u8bddid\uff0c\u65b9\u4fbf\u4e0d\u540c\u573a\u666f\u4e0b\u7684\u4f7f\u7528\n\n- \u8fd9\u4e2a\u63d2\u4ef6\u89e3\u51b3\u4e86\u4ec0\u4e48\u95ee\u9898\uff1f\n\nNonebot \u9002\u914d\u5668\u57fa\u7c7b\u4e2d\u63d0\u4f9b\u4e86 `get_session_id` \u51fd\u6570\u7528\u4e8e\u83b7\u53d6\u4f1a\u8bdd id\uff0c\n\u4f46\u8fd9\u4e00\u7ed3\u679c\u901a\u5e38\u662f \u7528\u6237 id\u3001\u7fa4\u7ec4 id \u7684\u7ec4\u5408\uff0c\u5c5e\u4e8e \u201c\u7528\u6237\u7ea7\u522b\u201d \u7684 id\uff0c\n\u4f46\u5728\u5f88\u591a\u63d2\u4ef6\u4e2d\uff0c\u9700\u8981\u7528\u5230 \u201c\u7fa4\u7ec4\u7ea7\u522b\u201d \u7684\u4f1a\u8bdd id\uff0c\u5982\u8bcd\u4e91\u3001\u8bcd\u5e93\u7b49\u7b49\n\n\u672c\u63d2\u4ef6\u53ef\u4ee5\u4e3a\u4e0d\u540c\u9002\u914d\u5668\u63d0\u4f9b\u4e00\u4e2a\u7edf\u4e00\u7684\u3001\u53ef\u9009\u7ea7\u522b\u7684\u4f1a\u8bdd id \u5b9a\u4e49\u65b9\u5f0f\n\n\n### \u5b89\u88c5\n\n- \u4f7f\u7528 nb-cli\n\n```\nnb plugin install nonebot_plugin_session\n```\n\n- \u4f7f\u7528 pip\n\n```\npip install nonebot_plugin_session\n```\n\n### \u4f7f\u7528\n\n\n\u83b7\u53d6 `Session`\uff1a\n\n```python\nfrom nonebot_plugin_session import extract_session\n\n@matcher.handle()\nasync def handle(bot: Bot, event: Event):\n session = extract_session(bot, event)\n```\n\n\n\u83b7\u53d6 `session id`\uff1a\n\n```python\nfrom nonebot_plugin_session import SessionId, SessionIdType\n\n@matcher.handle()\nasync def handle(session_id: str = SessionId(SessionIdType.GROUP)):\n # \u83b7\u53d6 \u201c\u7fa4\u7ec4\u7ea7\u522b\u201d \u7684 session id\n ...\n```\n\n\n\u5c06 `Session` \u5b58\u81f3\u6570\u636e\u5e93\u4e2d\uff08\u9700\u8981\u5b89\u88c5 [nonebot-plugin-datastore](https://github.com/he0119/nonebot-plugin-datastore) \u63d2\u4ef6\uff09\n\n```python\nfrom nonebot_plugin_datastore import create_session\nfrom nonebot_plugin_session import extract_session\nfrom nonebot_plugin_session.model import get_or_add_session_model\n\n@matcher.handle()\nasync def handle(bot: Bot, event: Event):\n session = extract_session(bot, event)\n async with create_session() as db_session:\n session_model = await get_or_add_session_model(session, db_session) # \u53ef\u5173\u8054\u5176\u4ed6\u8868\u7528\u4e8e\u7b5b\u9009\u7b49\n```\n\n\n\u4ece `Session` \u4e2d\u83b7\u53d6 `saa` \u7684 `PlatformTarget` \u5bf9\u8c61\u7528\u4e8e\u53d1\u9001\uff08\u9700\u8981\u5b89\u88c5 [nonebot-plugin-send-anything-anywhere](https://github.com/felinae98/nonebot-plugin-send-anything-anywhere) \u63d2\u4ef6\uff09\n\n```python\nfrom nonebot_plugin_session import extract_session\n\n@matcher.handle()\nasync def handle(bot: Bot, event: Event):\n session = extract_session(bot, event)\n target = session.get_saa_target() # \u7528\u4e8e\u53d1\u9001\n```\n\n\n\u4e0d\u540c\u7684 \u201c\u4f1a\u8bdd\u7ea7\u522b\u201d \u4e0e \u201c\u4f1a\u8bddid\u7c7b\u578b\u201d \u4e0b\u8fd4\u56de\u7684 id \u5982\u4e0b\u8868\u6240\u793a\uff1a\uff08\u4e0d\u5305\u542b `bot_id` \u7b49\u5c5e\u6027\u7684\u60c5\u51b5\uff09\n\n| | LEVEL0<br>\uff08\u65e0\u7528\u6237\uff09 | LEVEL1<br>\uff08\u5355\u7528\u6237\uff09 | LEVEL2<br>\uff08\u5355\u7ea7\u7fa4\u7ec4\uff09 | LEVEL3<br>\uff08\u4e24\u7ea7\u7fa4\u7ec4\uff09 | \n| --- | --- | --- | --- | --- |\n| TYPE0 (GLOBAL) | `\"\"` | `\"\"` | `\"\"` | `\"\"` |\n| TYPE1 (USER) | `\"\"` | `\"id1\"` | `\"id1\"` | `\"id1\"` |\n| TYPE2 | `\"\"` | `\"id1\"` | `\"id2\"` | `\"id2\"` |\n| TYPE3 | `\"\"` | `\"id1\"` | `\"id2_id1\"` | `\"id2_id1\"` |\n| TYPE4 | `\"\"` | `\"id1\"` | `\"id2\"` | `\"id3\"` |\n| TYPE5 | `\"\"` | `\"id1\"` | `\"id2_id1\"` | `\"id3_id1\"` |\n| TYPE6 (GROUP) | `\"\"` | `\"id1\"` | `\"id2\"` | `\"id3_id2\"` |\n| TYPE7 (GROUP_USER) | `\"\"` | `\"id1\"` | `\"id2_id1\"` | `\"id3_id2_id1\"` |\n\n\n### \u652f\u6301\u7684 adapter\n\n| OneBot v11 | OneBot v12 | Console | Kaiheila | QQ Guild | Telegram |\n| :--------: | :--------: | :------: | :------: | :------: | :------: |\n| \u2705 | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 |\n\n\n### \u9e23\u8c22\n\n- [nonebot-plugin-send-anything-anywhere](https://github.com/felinae98/nonebot-plugin-send-anything-anywhere) \u9879\u76ee\u7684\u7075\u611f\u6765\u6e90\u4ee5\u53ca\u90e8\u5206\u5b9e\u73b0\u7684\u53c2\u8003\n- [uy/sun](https://github.com/he0119) \u611f\u8c22\u6b6a\u65e5\u4f6c\u7684\u6280\u672f\u652f\u6301\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Nonebot2 \u4f1a\u8bdd\u4fe1\u606f\u63d0\u53d6\u4e0e\u4f1a\u8bddid\u5b9a\u4e49",
"version": "0.0.8",
"project_urls": {
"Homepage": "https://github.com/noneplugin/nonebot-plugin-session",
"Repository": "https://github.com/noneplugin/nonebot-plugin-session"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f203c75e9bb6add74a9bb63ac578d01ce1a3892eb541157d751bc25818328f98",
"md5": "90c3e7330e8254682d59f45417568d1a",
"sha256": "d6dda53e0ea0729b07542d7e6cf5526e422b6e7ed1f051a6a378fe00052f9de1"
},
"downloads": -1,
"filename": "nonebot_plugin_session-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "90c3e7330e8254682d59f45417568d1a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 14024,
"upload_time": "2023-07-26T14:37:19",
"upload_time_iso_8601": "2023-07-26T14:37:19.266033Z",
"url": "https://files.pythonhosted.org/packages/f2/03/c75e9bb6add74a9bb63ac578d01ce1a3892eb541157d751bc25818328f98/nonebot_plugin_session-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1ec5f36eda2b8211b29294f0047712e1148f226d15e23101ced79c3f43e22ac0",
"md5": "13eb8e40c9f2120de41b895924cbbaa7",
"sha256": "fedd92b12742e2f95a6c9f842236f11b91e43b598b2791fcbe16b4dbb1d3462a"
},
"downloads": -1,
"filename": "nonebot_plugin_session-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "13eb8e40c9f2120de41b895924cbbaa7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 10133,
"upload_time": "2023-07-26T14:37:21",
"upload_time_iso_8601": "2023-07-26T14:37:21.655222Z",
"url": "https://files.pythonhosted.org/packages/1e/c5/f36eda2b8211b29294f0047712e1148f226d15e23101ced79c3f43e22ac0/nonebot_plugin_session-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-26 14:37:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "noneplugin",
"github_project": "nonebot-plugin-session",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nonebot-plugin-session"
}
JSON
