# Alconna Graia
该项目为 [`Alconna`](https://github.com/ArcletProject/Alconna) 为 [`GraiaProject`](https://github.com/GraiaProject) 下项目的内建支持
包括解析器、Dispatcher、SayaSchema 和 附加组件
## 安装
```shell
pip install arclet-alconna-graia, arclet-alconna-ariadne
pdm add arclet-alconna-graia, arclet-alconna-ariadne
```
或
```shell
pip install arclet-alconna-graia, arclet-alconna-avilla
pdm add arclet-alconna-graia, arclet-alconna-avilla
```
或
```shell
pip install arclet-alconna-graia, arclet-alconna-ichika
pdm add arclet-alconna-graia, arclet-alconna-ichika
```
## 前提
Alconna-Graia 现在依赖 `Launart` 的 `service` 功能
你需要在你使用 Alconna-Graia 组件时加入如下代码：
```python
from launart import Launart
from arclet.alconna.graia import AlconnaGraiaService
from arclet.alconna.xxx import AlconnaXXXAdapter
...
manager = Launart(...)
manager.add_service(AlconnaGraiaService(AlconnaXXXAdapter))
```
`adapater` 的使用可以直接导入：
```python
from launart import Launart
from arclet.alconna.graia import AlconnaGraiaService
import arclet.alconna.xxx
...
manager = Launart(...)
manager.add_service(AlconnaGraiaService())
```
或传入 endpoint, 其等价于直接导入:
```python
from launart import Launart
from arclet.alconna.graia import AlconnaGraiaService
...
manager = Launart(...)
manager.add_service(AlconnaGraiaService("xxx"))
```
不指定 adapter 时 Alconna-Graia 默认使用基础 adapter
## 快速使用
### 单文件
ariadne:
```python
from arclet.alconna import Args
from arclet.alconna.graia import Alconna, AlconnaDispatcher, Match, CommandResult
from arclet.alconna.graia.service import AlconnaGraiaService
import arclet.alconna.ariadne
...
manager = Launart(...)
manager.add_service(AlconnaGraiaService())
app = Ariadne(...)
alc = Alconna("!jrrp", Args["sth", str, 1123])
@app.broadcast.receiver(
GroupMessage,
dispatchers=[AlconnaDispatcher(alc, send_flag='stay')]
)
async def test2(
group: Group,
result: CommandResult[GroupMessage],
sth: Match[str]
):
print("sign:", result.result)
print("sender:", group)
print("match", sth.available, sth.result)
```
avilla:
```python
from arclet.alconna import Args
from arclet.alconna.graia import Alconna, AlconnaDispatcher, Match, CommandResult
from arclet.alconna.graia.service import AlconnaGraiaService
import arclet.alconna.avilla
...
broadcast = create(Broadcast)
manager = Launart(...)
manager.add_service(AlconnaGraiaService())
avilla = Avilla(...)
alc = Alconna("!jrrp", Args["sth", str, 1123])
@broadcast.receiver(
MessageReceived,
dispatchers=[AlconnaDispatcher(alc, send_flag='stay')]
)
async def test2(
context: Context,
result: CommandResult[MessageReceived],
sth: Match[str]
):
print("sign:", result.result)
print("sender:", context.scene)
print("match", sth.available, sth.result)
```
### 使用 Saya
in module.py:
```python
from arclet.alconna.graia import Alconna, AlconnaDispatcher, Match, CommandResult, AlconnaSchema
from arclet.alconna import Args
...
channel = Channel.current()
alc = Alconna("!jrrp", Args["sth", str, 1123])
@channel.use(AlconnaSchema(AlconnaDispatcher(alc)))
@channel.use(ListenerSchema([...]))
async def test2(result: CommandResult[...], sth: Match[str]):
print("sign:", result.result)
print("match", sth.available, sth.result)
```
in main.py:
```python
from arclet.alconna.graia import AlconnaBehaviour
from creart import create
...
saya = create(Saya)
create(AlconnaBehaviour)
with saya.module_context():
saya.require("module")
```
### 使用 Saya Util
in module.py:
```python
from graiax.shortcut.saya import listen
from arclet.alconna.graia import alcommand, Alconna, Match, from_command, startswith, endswith
from arclet.alconna import Args, Arpamar
...
@alcommand(Alconna("!jrrp", Args["sth", str, 1123]), private=False)
async def test1(result: Arpamar, sth: Match[str]):
print("sign:", result)
print("match", sth.available, sth.result)
@alcommand("[!|.]hello <name:str>", send_error=True)
async def test1(result: Arpamar, name: Match[str]):
print("sign:", result)
print("match", name.available, name.result)
@listen(...)
@from_command("foo bar {baz}")
async def test2(baz: int):
print("baz", baz)
@listen(...)
@startswith("foo bar")
async def test3(event: ...):
...
@listen(...)
@endswith(int)
async def test4(event: ...):
...
```
in main.py:
```python
from creart import create
...
saya = create(Saya)
with saya.module_context():
saya.require("module")
```
## AlconnaDispatcher 参数说明
```python
class AlconnaDispatcher(BaseDispatcher, Generic[TOHandler]):
def __init__(
self,
command: Alconna | AlconnaGroup,
*,
send_flag: Literal["reply", "post", "stay"] = "stay",
skip_for_unmatch: bool = True,
comp_session: Optional[CompConfig] = None,
message_converter: Callable[[OutType, str], MessageChain | Coroutine[Any, Any, MessageChain]] | None = None,
): ...
```
`command`: 使用的 Alconna 指令
`send_flag`: 解析期间输出信息的发送方式
- reply: 直接发送给指令发送者
- post: 以事件通过 Broadcast 广播
- stay: 存入 CommandResult 传递给事件处理器
`skip_for_unmatch`: 解析失败时是否跳过, 否则错误信息按 send_flag 处理
`comp_session`: 补全会话配置, 不传入则不启用补全会话
`message_converter`: send_flag 为 reply 时 输出信息的预处理器
## 附加组件
- `Match`: 查询某个参数是否匹配，如`foo: Match[int]`。使用时以 `Match.available` 判断是否匹配成功，以
`Match.result` 获取匹配结果
- `Query`: 查询某个参数路径是否存在，如`sth: Query[int] = Query("foo.bar")`；可以指定默认值如
`Query("foo.bar", 1234)`。使用时以 `Query.available` 判断是否匹配成功，以 `Query.result` 获取匹配结果
- `Header`: 表示命令头部为特殊形式时的头部匹配
- `assign`: 依托路径是否匹配成功为命令分发处理器。
```python
from arclet.alconna.graia import assign, alcommand
from arclet.alconna import Alconna, Arpamar
...
alc = Alconna(...)
@alcommand(alc, private=False)
@assign("foo")
async def foo(result: Arpamar):
...
@alcommand(alc, private=False)
@assign("bar.baz", 1)
async def bar_baz_1(result: Arpamar):
...
```
## 便捷方法
```python
from arclet.alconna.graia import Match, Alc
...
@app.broadcast.receiver(
..., dispatchers=[Alc.from_format("foo bar {baz:int}")]
)
async def test2(baz: Match[int]):
print("match", baz.available, baz.result)
```
or
```python
from arclet.alconna.graia import Match, AlconnaSchema
...
channel = Channel.current()
@channel.use(AlconnaSchema.from_("foo {sth:str} bar {baz:int}"))
@channel.use(ListenerSchema([...]))
async def test2(sth: Match[str]):
print("match", sth.available, sth.result)
```
## 文档
[链接](https://graiax.cn/guide/alconna.html#kirakira%E2%98%86dokidoki%E7%9A%84dispatcher)
Raw data
{
"_id": null,
"home_page": "https://github.com/ArcletProject/Alconna-Graia",
"name": "arclet-alconna-graia",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "alconna, graia, arclet, ariadne",
"author": null,
"author_email": "RF-Tar-Railt <rf_tar_railt@qq.com>",
"download_url": "https://files.pythonhosted.org/packages/d5/ff/7f21284e5e5afdcaae5d58194970bb9cc81edd729c0fc5c072914adba723/arclet_alconna_graia-0.18.3.tar.gz",
"platform": null,
"description": "# Alconna Graia\n\n\u8be5\u9879\u76ee\u4e3a [`Alconna`](https://github.com/ArcletProject/Alconna) \u4e3a [`GraiaProject`](https://github.com/GraiaProject) \u4e0b\u9879\u76ee\u7684\u5185\u5efa\u652f\u6301\n\n\u5305\u62ec\u89e3\u6790\u5668\u3001Dispatcher\u3001SayaSchema \u548c \u9644\u52a0\u7ec4\u4ef6\n\n## \u5b89\u88c5\n\n```shell\npip install arclet-alconna-graia, arclet-alconna-ariadne\npdm add arclet-alconna-graia, arclet-alconna-ariadne\n```\n\n\u6216\n\n```shell\npip install arclet-alconna-graia, arclet-alconna-avilla\npdm add arclet-alconna-graia, arclet-alconna-avilla\n```\n\n\u6216\n\n```shell\npip install arclet-alconna-graia, arclet-alconna-ichika\npdm add arclet-alconna-graia, arclet-alconna-ichika\n```\n\n## \u524d\u63d0\n\nAlconna-Graia \u73b0\u5728\u4f9d\u8d56 `Launart` \u7684 `service` \u529f\u80fd\n\n\u4f60\u9700\u8981\u5728\u4f60\u4f7f\u7528 Alconna-Graia \u7ec4\u4ef6\u65f6\u52a0\u5165\u5982\u4e0b\u4ee3\u7801\uff1a\n\n```python\nfrom launart import Launart\nfrom arclet.alconna.graia import AlconnaGraiaService\nfrom arclet.alconna.xxx import AlconnaXXXAdapter\n...\n\nmanager = Launart(...)\nmanager.add_service(AlconnaGraiaService(AlconnaXXXAdapter))\n```\n\n`adapater` \u7684\u4f7f\u7528\u53ef\u4ee5\u76f4\u63a5\u5bfc\u5165\uff1a\n\n```python\nfrom launart import Launart\nfrom arclet.alconna.graia import AlconnaGraiaService\nimport arclet.alconna.xxx\n...\n\nmanager = Launart(...)\nmanager.add_service(AlconnaGraiaService())\n```\n\n\u6216\u4f20\u5165 endpoint, \u5176\u7b49\u4ef7\u4e8e\u76f4\u63a5\u5bfc\u5165:\n\n```python\nfrom launart import Launart\nfrom arclet.alconna.graia import AlconnaGraiaService\n...\n\nmanager = Launart(...)\nmanager.add_service(AlconnaGraiaService(\"xxx\"))\n```\n\n\u4e0d\u6307\u5b9a adapter \u65f6 Alconna-Graia \u9ed8\u8ba4\u4f7f\u7528\u57fa\u7840 adapter\n\n\n## \u5feb\u901f\u4f7f\u7528\n\n### \u5355\u6587\u4ef6\n\nariadne:\n\n```python\nfrom arclet.alconna import Args\nfrom arclet.alconna.graia import Alconna, AlconnaDispatcher, Match, CommandResult\nfrom arclet.alconna.graia.service import AlconnaGraiaService\nimport arclet.alconna.ariadne\n...\nmanager = Launart(...)\nmanager.add_service(AlconnaGraiaService())\napp = Ariadne(...)\n\n\nalc = Alconna(\"!jrrp\", Args[\"sth\", str, 1123])\n\n@app.broadcast.receiver(\n GroupMessage,\n dispatchers=[AlconnaDispatcher(alc, send_flag='stay')]\n)\nasync def test2(\n group: Group,\n result: CommandResult[GroupMessage],\n sth: Match[str]\n):\n print(\"sign:\", result.result)\n print(\"sender:\", group)\n print(\"match\", sth.available, sth.result)\n```\n\navilla:\n\n```python\nfrom arclet.alconna import Args\nfrom arclet.alconna.graia import Alconna, AlconnaDispatcher, Match, CommandResult\nfrom arclet.alconna.graia.service import AlconnaGraiaService\nimport arclet.alconna.avilla\n...\nbroadcast = create(Broadcast)\nmanager = Launart(...)\nmanager.add_service(AlconnaGraiaService())\navilla = Avilla(...)\n\n\nalc = Alconna(\"!jrrp\", Args[\"sth\", str, 1123])\n\n@broadcast.receiver(\n MessageReceived,\n dispatchers=[AlconnaDispatcher(alc, send_flag='stay')]\n)\nasync def test2(\n context: Context,\n result: CommandResult[MessageReceived],\n sth: Match[str]\n):\n print(\"sign:\", result.result)\n print(\"sender:\", context.scene)\n print(\"match\", sth.available, sth.result)\n```\n\n### \u4f7f\u7528 Saya\n\nin module.py:\n```python\nfrom arclet.alconna.graia import Alconna, AlconnaDispatcher, Match, CommandResult, AlconnaSchema\nfrom arclet.alconna import Args\n...\nchannel = Channel.current()\n\nalc = Alconna(\"!jrrp\", Args[\"sth\", str, 1123])\n\n@channel.use(AlconnaSchema(AlconnaDispatcher(alc)))\n@channel.use(ListenerSchema([...]))\nasync def test2(result: CommandResult[...], sth: Match[str]):\n print(\"sign:\", result.result)\n print(\"match\", sth.available, sth.result)\n\n\n```\n\nin main.py:\n```python\nfrom arclet.alconna.graia import AlconnaBehaviour\nfrom creart import create\n...\n\nsaya = create(Saya)\ncreate(AlconnaBehaviour)\n\nwith saya.module_context():\n saya.require(\"module\")\n\n```\n### \u4f7f\u7528 Saya Util\n\nin module.py:\n\n```python\nfrom graiax.shortcut.saya import listen\nfrom arclet.alconna.graia import alcommand, Alconna, Match, from_command, startswith, endswith\nfrom arclet.alconna import Args, Arpamar\n\n...\n\n\n@alcommand(Alconna(\"!jrrp\", Args[\"sth\", str, 1123]), private=False)\nasync def test1(result: Arpamar, sth: Match[str]):\n print(\"sign:\", result)\n print(\"match\", sth.available, sth.result)\n\n\n@alcommand(\"[!|.]hello <name:str>\", send_error=True)\nasync def test1(result: Arpamar, name: Match[str]):\n print(\"sign:\", result)\n print(\"match\", name.available, name.result)\n\n \n@listen(...) \n@from_command(\"foo bar {baz}\")\nasync def test2(baz: int):\n print(\"baz\", baz)\n \n \n@listen(...)\n@startswith(\"foo bar\")\nasync def test3(event: ...):\n ...\n\n\n@listen(...)\n@endswith(int)\nasync def test4(event: ...):\n ...\n```\n\nin main.py:\n```python\nfrom creart import create\n...\n\nsaya = create(Saya)\n\nwith saya.module_context():\n saya.require(\"module\")\n\n```\n\n## AlconnaDispatcher \u53c2\u6570\u8bf4\u660e\n\n```python\nclass AlconnaDispatcher(BaseDispatcher, Generic[TOHandler]):\n def __init__(\n self,\n command: Alconna | AlconnaGroup,\n *,\n send_flag: Literal[\"reply\", \"post\", \"stay\"] = \"stay\",\n skip_for_unmatch: bool = True,\n comp_session: Optional[CompConfig] = None,\n message_converter: Callable[[OutType, str], MessageChain | Coroutine[Any, Any, MessageChain]] | None = None,\n ): ...\n```\n\n`command`: \u4f7f\u7528\u7684 Alconna \u6307\u4ee4\n\n`send_flag`: \u89e3\u6790\u671f\u95f4\u8f93\u51fa\u4fe1\u606f\u7684\u53d1\u9001\u65b9\u5f0f\n- reply: \u76f4\u63a5\u53d1\u9001\u7ed9\u6307\u4ee4\u53d1\u9001\u8005\n- post: \u4ee5\u4e8b\u4ef6\u901a\u8fc7 Broadcast \u5e7f\u64ad\n- stay: \u5b58\u5165 CommandResult \u4f20\u9012\u7ed9\u4e8b\u4ef6\u5904\u7406\u5668\n\n`skip_for_unmatch`: \u89e3\u6790\u5931\u8d25\u65f6\u662f\u5426\u8df3\u8fc7, \u5426\u5219\u9519\u8bef\u4fe1\u606f\u6309 send_flag \u5904\u7406\n\n`comp_session`: \u8865\u5168\u4f1a\u8bdd\u914d\u7f6e, \u4e0d\u4f20\u5165\u5219\u4e0d\u542f\u7528\u8865\u5168\u4f1a\u8bdd\n\n`message_converter`: send_flag \u4e3a reply \u65f6 \u8f93\u51fa\u4fe1\u606f\u7684\u9884\u5904\u7406\u5668\n\n## \u9644\u52a0\u7ec4\u4ef6\n\n- `Match`: \u67e5\u8be2\u67d0\u4e2a\u53c2\u6570\u662f\u5426\u5339\u914d\uff0c\u5982`foo: Match[int]`\u3002\u4f7f\u7528\u65f6\u4ee5 `Match.available` \u5224\u65ad\u662f\u5426\u5339\u914d\u6210\u529f\uff0c\u4ee5\n`Match.result` \u83b7\u53d6\u5339\u914d\u7ed3\u679c\n\n- `Query`: \u67e5\u8be2\u67d0\u4e2a\u53c2\u6570\u8def\u5f84\u662f\u5426\u5b58\u5728\uff0c\u5982`sth: Query[int] = Query(\"foo.bar\")`\uff1b\u53ef\u4ee5\u6307\u5b9a\u9ed8\u8ba4\u503c\u5982\n`Query(\"foo.bar\", 1234)`\u3002\u4f7f\u7528\u65f6\u4ee5 `Query.available` \u5224\u65ad\u662f\u5426\u5339\u914d\u6210\u529f\uff0c\u4ee5 `Query.result` \u83b7\u53d6\u5339\u914d\u7ed3\u679c\n\n- `Header`: \u8868\u793a\u547d\u4ee4\u5934\u90e8\u4e3a\u7279\u6b8a\u5f62\u5f0f\u65f6\u7684\u5934\u90e8\u5339\u914d\n\n- `assign`: \u4f9d\u6258\u8def\u5f84\u662f\u5426\u5339\u914d\u6210\u529f\u4e3a\u547d\u4ee4\u5206\u53d1\u5904\u7406\u5668\u3002\n\n```python\nfrom arclet.alconna.graia import assign, alcommand\nfrom arclet.alconna import Alconna, Arpamar\n...\n\nalc = Alconna(...)\n\n@alcommand(alc, private=False)\n@assign(\"foo\")\nasync def foo(result: Arpamar):\n ...\n\n@alcommand(alc, private=False)\n@assign(\"bar.baz\", 1)\nasync def bar_baz_1(result: Arpamar):\n ...\n```\n\n## \u4fbf\u6377\u65b9\u6cd5\n\n```python\nfrom arclet.alconna.graia import Match, Alc\n...\n\n@app.broadcast.receiver(\n ..., dispatchers=[Alc.from_format(\"foo bar {baz:int}\")]\n)\nasync def test2(baz: Match[int]):\n print(\"match\", baz.available, baz.result)\n```\n\nor\n\n```python\nfrom arclet.alconna.graia import Match, AlconnaSchema\n...\nchannel = Channel.current()\n\n@channel.use(AlconnaSchema.from_(\"foo {sth:str} bar {baz:int}\"))\n@channel.use(ListenerSchema([...]))\nasync def test2(sth: Match[str]):\n print(\"match\", sth.available, sth.result)\n```\n\n## \u6587\u6863\n\n[\u94fe\u63a5](https://graiax.cn/guide/alconna.html#kirakira%E2%98%86dokidoki%E7%9A%84dispatcher)",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Support Alconna to GraiaProject",
"version": "0.18.3",
"project_urls": {
"Bug reports": "https://github.com/ArcletProject/Alconna/issues",
"Documentation": "https://arcletproject.github.io/docs/alconna/tutorial",
"Homepage": "https://github.com/ArcletProject/Alconna-Graia",
"Repository": "https://github.com/ArcletProject/Alconna-Graia",
"Source": "https://github.com/ArcletProject/Alconna"
},
"split_keywords": [
"alconna",
" graia",
" arclet",
" ariadne"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9915e43d5c741f192eb72cbca84eae6558980df87ca78107ca018c8c2bdaf93a",
"md5": "e45810a7f1462d5961db09b4ab192a32",
"sha256": "c76cb114fcdfd910e6606435cbba69b91340eae2b706e7af7e56746917bab0e6"
},
"downloads": -1,
"filename": "arclet_alconna_graia-0.18.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e45810a7f1462d5961db09b4ab192a32",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 35691,
"upload_time": "2024-05-19T09:22:42",
"upload_time_iso_8601": "2024-05-19T09:22:42.778235Z",
"url": "https://files.pythonhosted.org/packages/99/15/e43d5c741f192eb72cbca84eae6558980df87ca78107ca018c8c2bdaf93a/arclet_alconna_graia-0.18.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d5ff7f21284e5e5afdcaae5d58194970bb9cc81edd729c0fc5c072914adba723",
"md5": "77786cd133dba301f545589c9c140c7f",
"sha256": "48abd524dd71e341725487585c1e430c09e241d094ed9bf38045ffca6f14b925"
},
"downloads": -1,
"filename": "arclet_alconna_graia-0.18.3.tar.gz",
"has_sig": false,
"md5_digest": "77786cd133dba301f545589c9c140c7f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 32002,
"upload_time": "2024-05-19T09:22:48",
"upload_time_iso_8601": "2024-05-19T09:22:48.724281Z",
"url": "https://files.pythonhosted.org/packages/d5/ff/7f21284e5e5afdcaae5d58194970bb9cc81edd729c0fc5c072914adba723/arclet_alconna_graia-0.18.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-19 09:22:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ArcletProject",
"github_project": "Alconna-Graia",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "arclet-alconna-graia"
}
JSON
