Awesome

Alconna

</div>

latest release

简体中文|English

关于

Alconna 隶属于 ArcletProject, 是一个简单、灵活、高效的命令参数解析器, 并且不局限于解析命令式字符串。

Alconna 拥有复杂的解析功能与命令组件，但一般情况下请当作奇妙简易的消息链解析器/命令解析器(雾)

安装

pip

pip install --upgrade arclet-alconna
pip install --upgrade arclet-alconna[full]

完整安装

pip install --upgrade arclet-alconna[all]

文档

文档链接: 👉指路

简单使用

from arclet.alconna import Alconna, Option, Subcommand, Args

cmd = Alconna(
    "/pip",
    Subcommand("install", Option("-u|--upgrade"), Args.pak_name[str]),
    Option("list")
)

result = cmd.parse("/pip install numpy --upgrade") # 该方法返回一个Arpamar类的实例
print(result.query('install'))  # 或者 result.install

其结果为

value=None args={'pak_name': 'numpy'} options={'upgrade': value=Ellipsis args={}} subcommands={}

讨论

QQ 交流群: 链接

特点

高效. 在 i5-10210U 处理器上, 性能大约为 71000~289000 msg/s; 测试脚本: benchmark
直观的命令组件创建方式
强大的类型解析与类型转换功能
自定义的帮助信息格式与命令解析控制
i18n
命令输入缓存, 以保证重复命令的快速响应
易用的快捷命令创建与使用
可以绑定回调函数, 以便于在命令解析完成后执行
可创建命令补全会话, 以实现多轮连续的补全提示
模糊匹配、输出捕获等一众特性

执行回调示范:

# callback.py
from arclet.alconna import Alconna, Args

alc = Alconna("callback", Args["foo", int]["bar", str])

@alc.bind()
def cb(foo: int, bar: str):
    print(f"foo: {foo}")
    print(f"bar: {bar}")
    print(bar * foo)

if __name__ == '__main__':
    alc()

$ python callback.py 2 hello
foo: 2
bar: hello
hellohello

类型转换示范:

from arclet.alconna import Alconna, Args
from pathlib import Path

read = Alconna("read", Args["data", bytes])

@read.bind()
def cb(data: bytes):
    print(type(data))

read.parse(["read", b'hello'])
read.parse("read test_fire.py")
read.parse(["read", Path("test_fire.py")])

'''
<class 'bytes'>
<class 'bytes'>
<class 'bytes'>
'''

组件创建示范:

# component.py
from arclet.alconna import Alconna, Args, Option, Subcommand, store_true, count, append

alc = Alconna(
    "component",
    Args["path", str],
    Option("--verbose|-v", action=count),
    Option("-f", Args["flag", str], compact=True, action=append),
    Subcommand("sub", Option("bar", action=store_true, default=False))
)

if __name__ == '__main__':
    res = alc()
    print(res.query("path"))
    print(res.query("verbose.value"))
    print(res.query("f.flag"))
    print(res.query("sub"))

$ python component.py /home/arclet -vvvv -f1 -f2 -f3 sub bar
/home/arclet
4
['1', '2', '3']
(value=Ellipsis args={} options={'bar': (value=True args={})} subcommands={})

快捷命令示范:

# shortcut.py
from arclet.alconna import Alconna, Args

alc = Alconna("eval", Args["content", str])
alc.shortcut("echo", {"command": "eval print(\\'{*}\\')"})

@alc.bind()
def cb(content: str):
    eval(content, {}, {})

if __name__ == '__main__':
    alc()

$ python shortcut.py eval print(\"hello world\")
hello world
$ python shortcut.py echo hello world!
hello world!

命令补全示范:

# complete.py
from arclet.alconna import Alconna, Args, Option

alc = Alconna("complete", Args["bar", int]) + Option("foo") + Option("fool")

if __name__ == '__main__':
    alc()

$ python completion.py ?
以下是建议的输入：
* bar: int
* --help
* -h
* foo
* fool

typing 支持示范:

from typing import Annotated  # or typing_extensions.Annotated
from arclet.alconna import Alconna, Args

alc = Alconna("test", Args.foo[Annotated[int, lambda x: x % 2 == 0]])
alc.parse("test 2")
alc.parse("test 3")

'''
'foo': 2
ParamsUnmatched: 参数 3 不正确
'''

模糊匹配示范:

# fuzzy.py
from arclet.alconna import Alconna, CommandMeta, Arg

alc = Alconna('!test_fuzzy', Arg("foo", str), meta=CommandMeta(fuzzy_match=True))

if __name__ == '__main__':
    alc()

$ python fuzzy.py /test_fuzzy foo bar
无法解析 /test_fuzzy。您想要输入的是不是 "!test_fuzzy" ?

许可

Alconna 采用 MIT 许可协议

鸣谢

JetBrains: 为本项目提供 PyCharm 等 IDE 的授权<br> <img src="https://cdn.jsdelivr.net/gh/Kyomotoi/CDN@master/noting/jetbrains-variant-3.png" width="200"/>