<div align="center">
<a href="https://nonebot.dev/">
<img src="https://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` 中提取与会话相关的属性
具体定义如下：
| 属性 | 类型 | 含义 | 备注 |
| ---------- | --------- | ------------------------ | ---------------------------------------------------------------------------------------- |
| `bot_id` | `str` | 机器人 id | |
| `bot_type` | `str` | 机器人类型（适配器名称） | |
| `platform` | `str` | 平台 | 未知平台用 `unknown` 表示 |
| `level` | `IntEnum` | 会话等级 | 目前分为 LEVEL0（无用户）、LEVEL1（单用户）、LEVEL2（单级群组）、LEVEL3（两级群组） 四类 |
| `id1` | `str` | 1 级 id | 通常为 `user_id` |
| `id2` | `str` | 2 级 id | 通常为 单级群组中的 `group_id`，两级群组中的 `channel_id` |
| `id3` | `str` | 3 级 id | 通常为 两级群组中的 `guild_id` |
同时，本插件提供了获取会话 id 的函数，可以按照不同的类型获取会话id，方便不同场景下的使用
Nonebot 适配器基类中也提供了 `get_session_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)
```
或使用依赖注入的形式：
```python
from nonebot_plugin_session import EventSession
@matcher.handle()
async def handle(session: EventSession):
...
```
#### 获取 `session id`：
```python
from nonebot_plugin_session import extract_session, SessionIdType
@matcher.handle()
async def handle(bot: Bot, event: Event):
session = extract_session(bot, event)
session_id = session.get_id(SessionIdType.GROUP) # 获取 “群组级别” 的 session id
```
或使用依赖注入的形式：
```python
from nonebot_plugin_session import SessionId, SessionIdType
@matcher.handle()
async def handle(session_id: str = SessionId(SessionIdType.GROUP)):
...
```
不同的 “会话级别” 与 “会话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
- [x] OneBot v11
- [x] OneBot v12
- [x] Console
- [x] Kaiheila
- [x] Telegram
- [x] Feishu
- [x] RedProtocol
- [x] Discord
- [x] QQ
- [x] Satori
- [x] DoDo
### 相关插件
- [nonebot-plugin-session-orm](https://github.com/noneplugin/nonebot-plugin-session-orm) 为 session 提供数据库模型及存取方法
- [nonebot-plugin-session-saa](https://github.com/noneplugin/nonebot-plugin-session-saa) 提供从 session 获取 [saa](https://github.com/MountainDash/nonebot-plugin-send-anything-anywhere) 发送对象 [PlatformTarget](https://github.com/MountainDash/nonebot-plugin-send-anything-anywhere/blob/main/nonebot_plugin_saa/utils/platform_send_target.py) 的方法
### 鸣谢
- [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/8a/4b/37484bcc7aab9b79e88cc9b2f55cef6f6fe26f66c98c81f5ca29e9592d89/nonebot_plugin_session-0.3.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n <a href=\"https://nonebot.dev/\">\n <img src=\"https://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\u672c\u63d2\u4ef6\u63d0\u4f9b\u4e86\u4e00\u4e2a\u7edf\u4e00\u7684\u4f1a\u8bdd\u6a21\u578b `Session`\uff0c\u53ef\u4ee5\u4ece\u4e0d\u540c\u9002\u914d\u5668\u7684 `Bot` \u548c `Event` \u4e2d\u63d0\u53d6\u4e0e\u4f1a\u8bdd\u76f8\u5173\u7684\u5c5e\u6027\n\n\u5177\u4f53\u5b9a\u4e49\u5982\u4e0b\uff1a\n\n| \u5c5e\u6027 | \u7c7b\u578b | \u542b\u4e49 | \u5907\u6ce8 |\n| ---------- | --------- | ------------------------ | ---------------------------------------------------------------------------------------- |\n| `bot_id` | `str` | \u673a\u5668\u4eba id | |\n| `bot_type` | `str` | \u673a\u5668\u4eba\u7c7b\u578b\uff08\u9002\u914d\u5668\u540d\u79f0\uff09 | |\n| `platform` | `str` | \u5e73\u53f0 | \u672a\u77e5\u5e73\u53f0\u7528 `unknown` \u8868\u793a |\n| `level` | `IntEnum` | \u4f1a\u8bdd\u7b49\u7ea7 | \u76ee\u524d\u5206\u4e3a LEVEL0\uff08\u65e0\u7528\u6237\uff09\u3001LEVEL1\uff08\u5355\u7528\u6237\uff09\u3001LEVEL2\uff08\u5355\u7ea7\u7fa4\u7ec4\uff09\u3001LEVEL3\uff08\u4e24\u7ea7\u7fa4\u7ec4\uff09 \u56db\u7c7b |\n| `id1` | `str` | 1 \u7ea7 id | \u901a\u5e38\u4e3a `user_id` |\n| `id2` | `str` | 2 \u7ea7 id | \u901a\u5e38\u4e3a \u5355\u7ea7\u7fa4\u7ec4\u4e2d\u7684 `group_id`\uff0c\u4e24\u7ea7\u7fa4\u7ec4\u4e2d\u7684 `channel_id` |\n| `id3` | `str` | 3 \u7ea7 id | \u901a\u5e38\u4e3a \u4e24\u7ea7\u7fa4\u7ec4\u4e2d\u7684 `guild_id` |\n\n\u540c\u65f6\uff0c\u672c\u63d2\u4ef6\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\nNonebot \u9002\u914d\u5668\u57fa\u7c7b\u4e2d\u4e5f\u63d0\u4f9b\u4e86 `get_session_id` \u51fd\u6570\uff0c\u4f46\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\u5f88\u591a\u63d2\u4ef6\u4e2d\u9700\u8981\u7528\u5230\u4e0d\u540c\u7ea7\u522b\u7684\u4f1a\u8bdd id\uff0c\u5982\u8bcd\u4e91\u3001\u8bcd\u5e93\u7b49\u7b49\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#### \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\u6216\u4f7f\u7528\u4f9d\u8d56\u6ce8\u5165\u7684\u5f62\u5f0f\uff1a\n\n```python\nfrom nonebot_plugin_session import EventSession\n\n@matcher.handle()\nasync def handle(session: EventSession):\n ...\n```\n\n#### \u83b7\u53d6 `session id`\uff1a\n\n```python\nfrom nonebot_plugin_session import extract_session, SessionIdType\n\n@matcher.handle()\nasync def handle(bot: Bot, event: Event):\n session = extract_session(bot, event)\n session_id = session.get_id(SessionIdType.GROUP) # \u83b7\u53d6 \u201c\u7fa4\u7ec4\u7ea7\u522b\u201d \u7684 session id\n```\n\n\u6216\u4f7f\u7528\u4f9d\u8d56\u6ce8\u5165\u7684\u5f62\u5f0f\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 ...\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### \u652f\u6301\u7684 adapter\n\n- [x] OneBot v11\n- [x] OneBot v12\n- [x] Console\n- [x] Kaiheila\n- [x] Telegram\n- [x] Feishu\n- [x] RedProtocol\n- [x] Discord\n- [x] QQ\n- [x] Satori\n- [x] DoDo\n\n### \u76f8\u5173\u63d2\u4ef6\n\n- [nonebot-plugin-session-orm](https://github.com/noneplugin/nonebot-plugin-session-orm) \u4e3a session \u63d0\u4f9b\u6570\u636e\u5e93\u6a21\u578b\u53ca\u5b58\u53d6\u65b9\u6cd5\n- [nonebot-plugin-session-saa](https://github.com/noneplugin/nonebot-plugin-session-saa) \u63d0\u4f9b\u4ece session \u83b7\u53d6 [saa](https://github.com/MountainDash/nonebot-plugin-send-anything-anywhere) \u53d1\u9001\u5bf9\u8c61 [PlatformTarget](https://github.com/MountainDash/nonebot-plugin-send-anything-anywhere/blob/main/nonebot_plugin_saa/utils/platform_send_target.py) \u7684\u65b9\u6cd5\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.3.1",
"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": "2c0754eba2aa35c970a98ccc46f0bd8bfe08005cdcfd209b219baec055e019e5",
"md5": "b205779ebac1323125a7b83633df66f8",
"sha256": "7d21ed11a7d2a3bc9466be11f9653270ff0951585bd8e6fdd8034274e883ffb0"
},
"downloads": -1,
"filename": "nonebot_plugin_session-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b205779ebac1323125a7b83633df66f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 14645,
"upload_time": "2024-02-25T07:05:33",
"upload_time_iso_8601": "2024-02-25T07:05:33.845496Z",
"url": "https://files.pythonhosted.org/packages/2c/07/54eba2aa35c970a98ccc46f0bd8bfe08005cdcfd209b219baec055e019e5/nonebot_plugin_session-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8a4b37484bcc7aab9b79e88cc9b2f55cef6f6fe26f66c98c81f5ca29e9592d89",
"md5": "e1634f475db9b1c0e4433afe9fddbb64",
"sha256": "ba93b4b8e86394aa06ae099cd17c191e131f0d123a97e0c040578c08614fe306"
},
"downloads": -1,
"filename": "nonebot_plugin_session-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "e1634f475db9b1c0e4433afe9fddbb64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 10331,
"upload_time": "2024-02-25T07:05:35",
"upload_time_iso_8601": "2024-02-25T07:05:35.659284Z",
"url": "https://files.pythonhosted.org/packages/8a/4b/37484bcc7aab9b79e88cc9b2f55cef6f6fe26f66c98c81f5ca29e9592d89/nonebot_plugin_session-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-25 07:05:35",
"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
