| Name | nonebot-plugin-pam JSON |
| Version |
0.2.3
JSON |
| download |
| home_page | None |
| Summary | Nonebot 2 的权限与访问管理。 |
| upload_time | 2024-11-19 07:18:31 |
| maintainer | None |
| docs_url | None |
| author | Yan |
| requires_python | <4.0,>=3.11 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Nonebot 2 的权限管理系统
## Rule 编写
规则文件一般放置于 "pam_config.config_path"/ 文件夹下面（仿造[文件夹例子](examples.data/pam)）
格式是 plugin_name.yaml，或者 plugin_name/xxx.yaml
plugin_name 是具体限制的插件名字，特别的，\_\_all\_\_.yaml 表示在全局启用（即，每一个指令都会检测）
## Yaml 规范
```yaml
pam:
- rule: user.id != '1919810'
reason: 你是？
```
这个是判断发送消息的 id 是不是 1919810，如果不是，就发送“你是？”并终止指令 pam 的匹配。特别的，这里指约束指令的首个元素，即，cmd = ('pam', 'reload', ) 也会被这个匹配到。
```yaml
pam:
- rule: len(plugin.command) > 1 and plugin.command[1] == 'help'
ratelimit: limit.bucket(f'{plugin.command}', 60, 3)
reason: "{user.name}，你怎么一直要查看帮助呢？"
```
要匹配 cmd = ('pam', 'help', )，或者类似的，则可以对 plugin.command 约束。具体的规则请查看[规范](#规则支持)。
并且，reason 是 f-string，也就是说，你可以在里面使用 {} 包裹一些变量，函数等，进行更加丰富的提示返回。这三个字段所运行的上下文都是一致的。不过可能缺失部分内建函数/类。
ratelimit 则是令牌桶管理，具体可以查看[限速配置](#限速配置)。
### \_\_all\_\_
位置 `"pam_config.config_path"/nonebot_plugin_mysticism.yaml`
```yaml
__all__:
- ratelimit: limit.bucket(f"{user.id}_{plugin.name}", max_burst=60)
reason: 你话好像有点多了？
```
表示对于插件 nonebot_plugin_mysticism 下面的所有指令进行限速（同一个限速桶）。
---
位置 `"pam_config.config_path"/__all__.yaml`
```yaml
__all__:
- ratelimit: limit.bucket(user.id, 10, 1)
reason: 发太快了喵。
```
表示在全局，某一个人的发言频率过快，至多 10s 一次，无论是什么插件，什么指令都统一计算。
## 规则支持
### Top Level
变量：
- bot
- event
- state
- message
- limit
- group
- plugin
- user
- bucket
模块/类：
- int
- datetime，这个是 datetime.datetime
- str
- re
部分字段算是语法糖，例如，group.name 在 Python 中需要 await 的。
### bot
对 Bot 的包装，和 Nonebot2 的没啥区别。
### event
对 Evnet 的包装，和 Nonebot2 的没啥区别，但是多了字段 `type`
- type: event 的类型，str
### state
对 T_State 的包装，大概的区别就是可以 state._prefix 这么用。
### message
event.get_plaintext()，没啥差别。
### bucket
快捷访问 key 为 `{user.id}_{plugin.name}_{plugin.command}` 的 limit 桶.
### group
群组信息，Onebot V11 适配器专属（其他适配器 pr wellcome）
- id: 群号，int
- name: 群名字，str
### user
- id: 用户标识码，str
- superuser: 是否为 SuperUser，bool
Onebot V11 专属：
- name: 名字，群昵称优先，str
### plugin
- name: 插件名字，str
- command: 当前执行的命令，tuple[str] | None
- bucket: 属于当前插件的桶（对应用户），limit
### limit
限流，具体请查看[限速配置](#限速配置)。
## 限速配置
具体的实现是令牌桶。
```yaml
py:
- ratelimit: limit.bucket(f"{user.id}_{plugin.name}_{plugin.command}")
reason: 还有 {limit.status(f"{user.id}_{plugin.name}_{plugin.command}"):.2f} 秒哦。
```
等价于
```yaml
py:
- ratelimit: bucket.bucket()
reason: 还有 {bucket.status():.2f} 秒哦。
```
### limit.bucket(key: Hashable, period: int, max_burst: int, count_pre_period: int) -> bool
- key: 限定是什么桶，注意，key = 1 和 key = '1' 是两个桶。
- period: 令牌添加间隔，也就是经过多少秒添加 count_pre_period 个令牌，默认 60.
- max_burst: 令牌桶最大容量，默认 3.
- count_pre_period: 每个周期添加的令牌数量
返回值为 True 意味着当前处于速率限制。
### limit.status(key: Hashable) -> float
- key: 桶的key
返回值为还有多久的时间（单位 s）添加下一批令牌，如果为0则是当前还有令牌。
## TODO LIST
### Main
1. 自动提取指令
2. 添加给其他插件使用的接口
### Checker
1. 完善 alias 的识别
### Server
1. 新增 Change API
2. fetch 返回全部可用指令，而不单单是COMMAND RULE中的。
### WebUI
1. 完善 Detail 展示
Raw data
{
"_id": null,
"home_page": null,
"name": "nonebot-plugin-pam",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Yan",
"author_email": "1964649083@qq.com",
"download_url": "https://files.pythonhosted.org/packages/66/96/e97e7fa4840b278ace87ea636f50fd0710a2aa79887f3c226f9e2442141e/nonebot_plugin_pam-0.2.3.tar.gz",
"platform": null,
"description": "# Nonebot 2 \u7684\u6743\u9650\u7ba1\u7406\u7cfb\u7edf\n\n## Rule \u7f16\u5199\n\n\u89c4\u5219\u6587\u4ef6\u4e00\u822c\u653e\u7f6e\u4e8e \"pam_config.config_path\"/ \u6587\u4ef6\u5939\u4e0b\u9762\uff08\u4eff\u9020[\u6587\u4ef6\u5939\u4f8b\u5b50](examples.data/pam)\uff09\n\n\u683c\u5f0f\u662f plugin_name.yaml\uff0c\u6216\u8005 plugin_name/xxx.yaml\n\nplugin_name \u662f\u5177\u4f53\u9650\u5236\u7684\u63d2\u4ef6\u540d\u5b57\uff0c\u7279\u522b\u7684\uff0c\\_\\_all\\_\\_.yaml \u8868\u793a\u5728\u5168\u5c40\u542f\u7528\uff08\u5373\uff0c\u6bcf\u4e00\u4e2a\u6307\u4ee4\u90fd\u4f1a\u68c0\u6d4b\uff09\n\n## Yaml \u89c4\u8303\n\n```yaml\npam:\n - rule: user.id != '1919810'\n reason: \u4f60\u662f\uff1f\n```\n\n\u8fd9\u4e2a\u662f\u5224\u65ad\u53d1\u9001\u6d88\u606f\u7684 id \u662f\u4e0d\u662f 1919810\uff0c\u5982\u679c\u4e0d\u662f\uff0c\u5c31\u53d1\u9001\u201c\u4f60\u662f\uff1f\u201d\u5e76\u7ec8\u6b62\u6307\u4ee4 pam \u7684\u5339\u914d\u3002\u7279\u522b\u7684\uff0c\u8fd9\u91cc\u6307\u7ea6\u675f\u6307\u4ee4\u7684\u9996\u4e2a\u5143\u7d20\uff0c\u5373\uff0ccmd = ('pam', 'reload', ) \u4e5f\u4f1a\u88ab\u8fd9\u4e2a\u5339\u914d\u5230\u3002\n\n```yaml\npam:\n - rule: len(plugin.command) > 1 and plugin.command[1] == 'help'\n ratelimit: limit.bucket(f'{plugin.command}', 60, 3)\n reason: \"{user.name}\uff0c\u4f60\u600e\u4e48\u4e00\u76f4\u8981\u67e5\u770b\u5e2e\u52a9\u5462\uff1f\"\n```\n\n\u8981\u5339\u914d cmd = ('pam', 'help', )\uff0c\u6216\u8005\u7c7b\u4f3c\u7684\uff0c\u5219\u53ef\u4ee5\u5bf9 plugin.command \u7ea6\u675f\u3002\u5177\u4f53\u7684\u89c4\u5219\u8bf7\u67e5\u770b[\u89c4\u8303](#\u89c4\u5219\u652f\u6301)\u3002\n\n\u5e76\u4e14\uff0creason \u662f f-string\uff0c\u4e5f\u5c31\u662f\u8bf4\uff0c\u4f60\u53ef\u4ee5\u5728\u91cc\u9762\u4f7f\u7528 {} \u5305\u88f9\u4e00\u4e9b\u53d8\u91cf\uff0c\u51fd\u6570\u7b49\uff0c\u8fdb\u884c\u66f4\u52a0\u4e30\u5bcc\u7684\u63d0\u793a\u8fd4\u56de\u3002\u8fd9\u4e09\u4e2a\u5b57\u6bb5\u6240\u8fd0\u884c\u7684\u4e0a\u4e0b\u6587\u90fd\u662f\u4e00\u81f4\u7684\u3002\u4e0d\u8fc7\u53ef\u80fd\u7f3a\u5931\u90e8\u5206\u5185\u5efa\u51fd\u6570/\u7c7b\u3002\n\nratelimit \u5219\u662f\u4ee4\u724c\u6876\u7ba1\u7406\uff0c\u5177\u4f53\u53ef\u4ee5\u67e5\u770b[\u9650\u901f\u914d\u7f6e](#\u9650\u901f\u914d\u7f6e)\u3002\n\n### \\_\\_all\\_\\_\n\n\u4f4d\u7f6e `\"pam_config.config_path\"/nonebot_plugin_mysticism.yaml`\n\n```yaml\n__all__:\n - ratelimit: limit.bucket(f\"{user.id}_{plugin.name}\", max_burst=60)\n reason: \u4f60\u8bdd\u597d\u50cf\u6709\u70b9\u591a\u4e86\uff1f\n```\n\n\u8868\u793a\u5bf9\u4e8e\u63d2\u4ef6 nonebot_plugin_mysticism \u4e0b\u9762\u7684\u6240\u6709\u6307\u4ee4\u8fdb\u884c\u9650\u901f\uff08\u540c\u4e00\u4e2a\u9650\u901f\u6876\uff09\u3002\n\n---\n\n\u4f4d\u7f6e `\"pam_config.config_path\"/__all__.yaml`\n\n```yaml\n__all__:\n - ratelimit: limit.bucket(user.id, 10, 1)\n reason: \u53d1\u592a\u5feb\u4e86\u55b5\u3002\n```\n\n\u8868\u793a\u5728\u5168\u5c40\uff0c\u67d0\u4e00\u4e2a\u4eba\u7684\u53d1\u8a00\u9891\u7387\u8fc7\u5feb\uff0c\u81f3\u591a 10s \u4e00\u6b21\uff0c\u65e0\u8bba\u662f\u4ec0\u4e48\u63d2\u4ef6\uff0c\u4ec0\u4e48\u6307\u4ee4\u90fd\u7edf\u4e00\u8ba1\u7b97\u3002\n\n## \u89c4\u5219\u652f\u6301\n\n### Top Level\n\n\u53d8\u91cf\uff1a\n\n- bot\n- event\n- state\n- message\n- limit\n- group\n- plugin\n- user\n- bucket\n\n\u6a21\u5757/\u7c7b\uff1a\n\n- int\n- datetime\uff0c\u8fd9\u4e2a\u662f datetime.datetime\n- str\n- re\n\n\u90e8\u5206\u5b57\u6bb5\u7b97\u662f\u8bed\u6cd5\u7cd6\uff0c\u4f8b\u5982\uff0cgroup.name \u5728 Python \u4e2d\u9700\u8981 await \u7684\u3002\n\n### bot\n\n\u5bf9 Bot \u7684\u5305\u88c5\uff0c\u548c Nonebot2 \u7684\u6ca1\u5565\u533a\u522b\u3002\n\n### event\n\n\u5bf9 Evnet \u7684\u5305\u88c5\uff0c\u548c Nonebot2 \u7684\u6ca1\u5565\u533a\u522b\uff0c\u4f46\u662f\u591a\u4e86\u5b57\u6bb5 `type`\n\n- type: event \u7684\u7c7b\u578b\uff0cstr\n\n### state\n\n\u5bf9 T_State \u7684\u5305\u88c5\uff0c\u5927\u6982\u7684\u533a\u522b\u5c31\u662f\u53ef\u4ee5 state._prefix \u8fd9\u4e48\u7528\u3002\n\n### message\n\nevent.get_plaintext()\uff0c\u6ca1\u5565\u5dee\u522b\u3002\n\n### bucket\n\n\u5feb\u6377\u8bbf\u95ee key \u4e3a `{user.id}_{plugin.name}_{plugin.command}` \u7684 limit \u6876.\n\n### group\n\n\u7fa4\u7ec4\u4fe1\u606f\uff0cOnebot V11 \u9002\u914d\u5668\u4e13\u5c5e\uff08\u5176\u4ed6\u9002\u914d\u5668 pr wellcome\uff09\n\n- id: \u7fa4\u53f7\uff0cint\n- name: \u7fa4\u540d\u5b57\uff0cstr\n\n### user\n\n- id: \u7528\u6237\u6807\u8bc6\u7801\uff0cstr\n- superuser: \u662f\u5426\u4e3a SuperUser\uff0cbool\n\nOnebot V11 \u4e13\u5c5e\uff1a\n\n- name: \u540d\u5b57\uff0c\u7fa4\u6635\u79f0\u4f18\u5148\uff0cstr\n\n### plugin\n\n- name: \u63d2\u4ef6\u540d\u5b57\uff0cstr\n- command: \u5f53\u524d\u6267\u884c\u7684\u547d\u4ee4\uff0ctuple[str] | None\n- bucket: \u5c5e\u4e8e\u5f53\u524d\u63d2\u4ef6\u7684\u6876\uff08\u5bf9\u5e94\u7528\u6237\uff09\uff0climit\n\n### limit\n\n\u9650\u6d41\uff0c\u5177\u4f53\u8bf7\u67e5\u770b[\u9650\u901f\u914d\u7f6e](#\u9650\u901f\u914d\u7f6e)\u3002\n\n## \u9650\u901f\u914d\u7f6e\n\n\u5177\u4f53\u7684\u5b9e\u73b0\u662f\u4ee4\u724c\u6876\u3002\n\n```yaml\npy:\n - ratelimit: limit.bucket(f\"{user.id}_{plugin.name}_{plugin.command}\")\n reason: \u8fd8\u6709 {limit.status(f\"{user.id}_{plugin.name}_{plugin.command}\"):.2f} \u79d2\u54e6\u3002\n```\n\n\u7b49\u4ef7\u4e8e\n\n```yaml\npy:\n - ratelimit: bucket.bucket()\n reason: \u8fd8\u6709 {bucket.status():.2f} \u79d2\u54e6\u3002\n```\n\n### limit.bucket(key: Hashable, period: int, max_burst: int, count_pre_period: int) -> bool\n\n- key: \u9650\u5b9a\u662f\u4ec0\u4e48\u6876\uff0c\u6ce8\u610f\uff0ckey = 1 \u548c key = '1' \u662f\u4e24\u4e2a\u6876\u3002\n- period: \u4ee4\u724c\u6dfb\u52a0\u95f4\u9694\uff0c\u4e5f\u5c31\u662f\u7ecf\u8fc7\u591a\u5c11\u79d2\u6dfb\u52a0 count_pre_period \u4e2a\u4ee4\u724c\uff0c\u9ed8\u8ba4 60.\n- max_burst: \u4ee4\u724c\u6876\u6700\u5927\u5bb9\u91cf\uff0c\u9ed8\u8ba4 3.\n- count_pre_period: \u6bcf\u4e2a\u5468\u671f\u6dfb\u52a0\u7684\u4ee4\u724c\u6570\u91cf\n\n\u8fd4\u56de\u503c\u4e3a True \u610f\u5473\u7740\u5f53\u524d\u5904\u4e8e\u901f\u7387\u9650\u5236\u3002\n\n### limit.status(key: Hashable) -> float\n\n- key: \u6876\u7684key\n\n\u8fd4\u56de\u503c\u4e3a\u8fd8\u6709\u591a\u4e45\u7684\u65f6\u95f4\uff08\u5355\u4f4d s\uff09\u6dfb\u52a0\u4e0b\u4e00\u6279\u4ee4\u724c\uff0c\u5982\u679c\u4e3a0\u5219\u662f\u5f53\u524d\u8fd8\u6709\u4ee4\u724c\u3002\n\n## TODO LIST\n\n### Main\n\n1. \u81ea\u52a8\u63d0\u53d6\u6307\u4ee4\n2. \u6dfb\u52a0\u7ed9\u5176\u4ed6\u63d2\u4ef6\u4f7f\u7528\u7684\u63a5\u53e3\n\n### Checker\n\n1. \u5b8c\u5584 alias \u7684\u8bc6\u522b\n\n### Server\n\n1. \u65b0\u589e Change API\n2. fetch \u8fd4\u56de\u5168\u90e8\u53ef\u7528\u6307\u4ee4\uff0c\u800c\u4e0d\u5355\u5355\u662fCOMMAND RULE\u4e2d\u7684\u3002\n\n### WebUI\n\n1. \u5b8c\u5584 Detail \u5c55\u793a\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Nonebot 2 \u7684\u6743\u9650\u4e0e\u8bbf\u95ee\u7ba1\u7406\u3002",
"version": "0.2.3",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d0d481748b2907794052096b2a66ac35bdd510fa0dbeb2fe9fa2d58d9fe57fd2",
"md5": "7f3f33938809ecf835b68aebbb743a8f",
"sha256": "8774533ad5b6bddf44d4d2f5f3cd216ef79c839878cf9a6c9d1d0a5b4527ec6f"
},
"downloads": -1,
"filename": "nonebot_plugin_pam-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f3f33938809ecf835b68aebbb743a8f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 19034,
"upload_time": "2024-11-19T07:18:30",
"upload_time_iso_8601": "2024-11-19T07:18:30.912715Z",
"url": "https://files.pythonhosted.org/packages/d0/d4/81748b2907794052096b2a66ac35bdd510fa0dbeb2fe9fa2d58d9fe57fd2/nonebot_plugin_pam-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6696e97e7fa4840b278ace87ea636f50fd0710a2aa79887f3c226f9e2442141e",
"md5": "7bd1c55b30ee593c7d955fcafdae7b40",
"sha256": "b441d7df955b3e84bece7e2ffaa237da1804a1fe9dad7e7b15ddb0ce6412bc2e"
},
"downloads": -1,
"filename": "nonebot_plugin_pam-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "7bd1c55b30ee593c7d955fcafdae7b40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 17859,
"upload_time": "2024-11-19T07:18:31",
"upload_time_iso_8601": "2024-11-19T07:18:31.868032Z",
"url": "https://files.pythonhosted.org/packages/66/96/e97e7fa4840b278ace87ea636f50fd0710a2aa79887f3c226f9e2442141e/nonebot_plugin_pam-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 07:18:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "nonebot-plugin-pam"
}
