arclet-alconna 1.7.0rc1

A High-performance, Generality, Humane Command Line Arguments Parser Library.

Alconna

简体中文|English

About

Alconna is a powerful cli tool for parsing message chain or other raw message data. It is an overload version of CommandAnalysis, affiliated to ArcletProject.

Alconna has a large number of built-in components and complex parsing functions. But do not afraid, you can use it as a simple command parser.

Installation

pip

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

Documentation

Official Document : 👉Link

Relevant Document : 📚Docs

A Simple Example

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") # This method returns an 'Arparma' class instance.
print(result.query('install'))  # Or result.install

Output as follows:

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

Communication

QQ Group: Link

Features

• High Performance. On i5-10210U, performance is about 71000~289000 msg/s; test script: benchmark
• Simple and Flexible Constructor
• Powerful Automatic Type Parse and Conversion
• Support Synchronous and Asynchronous Actions
• Customizable Help Text Formatter, Command Analyser, etc.
• Customizable Language File, Support i18n
• Cache of input command for quick response of repeated command
• Easy-to-use Construct and Usage of Command Shortcut
• Various Features (FuzzyMatch, Command Completion, etc.)

Example of Type Conversion:

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

read = Alconna(
    "read", Args["data", bytes], 
    action=lambda data: 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'>
'''

Example of FuzzyMatch:

from arclet.alconna import Alconna, CommandMeta, Arg

alc = Alconna('!test_fuzzy', Arg("foo", str), meta=CommandMeta(fuzzy_match=True))
alc.parse("！test_fuzy foo bar")

'''
！test_fuzy not matched. Are you mean "!test_fuzzy"?
'''

Example of Command Shortcut:

from arclet.alconna import Alconna, Args

alc = Alconna("eval", Args["content", str], action=lambda x: eval(x, {}, {}))
alc.shortcut("echo", {"command": "eval print(\\'{*}\\')"})
alc.parse("echo Hello World!")

'''
Hello World!
'''

Example of typing Support:

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: param 3 is incorrect
'''

Example of Command Completion:

from arclet.alconna import Alconna, Args, Option

alc = Alconna("test", Args["bar", int]) + Option("foo") + Option("fool")
alc.parse("test --comp")

'''
next input maybe:
> foo
> int
> -h
> --help
> fool
'''

License

Alconna is licensed under the MIT License.

Acknowledgement

JetBrains: Support Authorize for PyCharm