Skip to content

A High-performance, Generality, Humane Python CLI Arguments Parser Library. 一个直观的、高性能、泛用的Python命令行参数解析器集成库

License

Notifications You must be signed in to change notification settings

ArcletProject/Alconna

Folders and files

NameName
Last commit message
Last commit date

Latest commit

c46e2dd · Sep 21, 2024
Feb 10, 2024
Jul 8, 2024
Feb 26, 2024
Aug 11, 2024
Sep 21, 2024
Aug 31, 2024
Feb 24, 2024
Aug 31, 2024
Dec 17, 2021
May 10, 2022
Aug 31, 2024
Aug 31, 2024
Sep 27, 2023
Feb 26, 2024
Aug 16, 2024
Feb 26, 2024
Feb 26, 2024
Feb 28, 2024
Feb 26, 2024
Sep 20, 2024
Sep 20, 2024

Repository files navigation

Alconna

Alconna latest release Licence PyPI PyPI - Python Version FOSSA Status

简体中文|English

关于

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

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

安装

pip

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

文档

文档链接: 👉指路

相关文档: 📚文档

简单使用

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

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

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

其结果为

value=None args={'pak': '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), CommandMeta(fuzzy_match=True))

if __name__ == '__main__':
    alc()
$ python fuzzy.py /test_fuzzy foo bar
无法解析 /test_fuzzy。您想要输入的是不是 "!test_fuzzy" ?

示例

名称 文件
计算 calculate.py
执行代码 exec_code.py
请求路由 endpoint.py
图片搜索 img_search.py
PIP pip.py
数据库查询 exec_sql.py

许可

Alconna 采用 MIT 许可协议

FOSSA Status

鸣谢

JetBrains: 为本项目提供 PyCharm 等 IDE 的授权

About

A High-performance, Generality, Humane Python CLI Arguments Parser Library. 一个直观的、高性能、泛用的Python命令行参数解析器集成库

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages