A High-performance, Generality, Humane Command Line Arguments Parser Library.
Project description
Alconna
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]
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 - Intuitive way to create command components
- Powerful Automatic Type Parse and Conversion
- Customizable Help Text Formatter and Control of Command Analyser
- i18n Support
- Cache of input command for quick response of repeated command
- Easy-to-use Construct and Usage of Command Shortcut
- Can bind callback function to execute after command parsing
- Can create command completion session to implement multi-round continuous completion prompt
- Various Features (FuzzyMatch, Output Capture, etc.)
Example of Callback Executor:
# callback.py
from arclet.alconna import Alconna, Args
alc = Alconna("callback", Args["foo", int]["bar", str])
@alc.bind()
def callback(foo: int, bar: str):
print(f"foo: {foo}")
print(f"bar: {bar}")
print(bar * foo)
if __name__ == "__main__":
alc()
$ python callback.py 3 hello
foo: 3
bar: hello
hellohellohello
Example of Type Conversion:
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'>
'''
Example of Component creation:
# 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={})
Example of Command Shortcut:
# 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!
Example of Command Completion:
# completion.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 ?
suggest input follows:
* bar: int
* --help
* -h
* foo
* fool
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 FuzzyMatch:
# 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_fuzy not matched. Are you mean "!test_fuzzy"?
Examples
Name | File |
---|---|
Calculate | calculate.py |
Execute | exec_code.py |
Request Route | endpoint.py |
Image Search | img_search.py |
PIP | pip.py |
Database Query | exec_sql.py |
License
Alconna is licensed under the MIT License.
Acknowledgement
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for arclet_alconna-1.8.25-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5f269c547ed2071035c3c53c567f449fa4cbaeb956748c024d2887d73d4da332 |
|
MD5 | dceb10f021dc96ceb069b5c64941e688 |
|
BLAKE2b-256 | 8a7c9f65d6d05fd4c9b1c8028670a2c49b34956b5553aa4cdc1ed5c39ccbbcfc |