Skip to main content

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

Project description

Alconna

Alconna latest release Licence PyPI PyPI - Python Version FOSSA Status

简体中文|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.

FOSSA Status

Acknowledgement

JetBrains: Support Authorize for PyCharm

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

arclet-alconna-1.7.0rc2.tar.gz (45.9 kB view hashes)

Uploaded Source

Built Distribution

arclet_alconna-1.7.0rc2-py3-none-any.whl (54.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page