{"id":25858785,"url":"https://github.com/arcletproject/alconna","last_synced_at":"2025-04-04T15:05:25.395Z","repository":{"id":37932069,"uuid":"438128739","full_name":"ArcletProject/Alconna","owner":"ArcletProject","description":"A High-performance, Generality, Humane Python CLI Arguments Parser Library. 一个直观的、高性能、泛用的Python命令行参数解析器集成库","archived":false,"fork":false,"pushed_at":"2025-02-24T12:53:09.000Z","size":2298,"stargazers_count":81,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-03-28T14:06:26.370Z","etag":null,"topics":["argparse","cli","command","parser","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ArcletProject.png","metadata":{"files":{"readme":"README-EN.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-14T05:27:43.000Z","updated_at":"2025-03-17T15:54:45.000Z","dependencies_parsed_at":"2024-02-10T10:25:40.036Z","dependency_job_id":"b0505284-ef28-4d59-84ae-b103c1509bea","html_url":"https://github.com/ArcletProject/Alconna","commit_stats":{"total_commits":319,"total_committers":8,"mean_commits":39.875,"dds":"0.31974921630094044","last_synced_commit":"1115ee99e59b435be8ce7db8171dfb1f51275da2"},"previous_names":[],"tags_count":103,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArcletProject%2FAlconna","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArcletProject%2FAlconna/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArcletProject%2FAlconna/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArcletProject%2FAlconna/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ArcletProject","download_url":"https://codeload.github.com/ArcletProject/Alconna/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198447,"owners_count":20900079,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argparse","cli","command","parser","python"],"created_at":"2025-03-01T20:34:01.025Z","updated_at":"2025-04-04T15:05:25.372Z","avatar_url":"https://github.com/ArcletProject.png","language":"Python","readme":"![](https://socialify.git.ci/ArcletProject/Alconna/image?description=1\u0026descriptionEditable=A%20High-performance%2C%20Generality%2C%20Humane%20Command%20Line%20Arguments%20Parser%20Library.\u0026font=Inter\u0026forks=1\u0026issues=1\u0026language=1\u0026logo=https%3A%2F%2Farclet.top%2Fimg%2Farclet.png\u0026name=1\u0026owner=1\u0026pattern=Brick%20Wall\u0026stargazers=1\u0026theme=Auto)\n\u003cdiv align=\"center\"\u003e \n\n# Alconna\n\n\u003c/div\u003e\n\n![Alconna](https://img.shields.io/badge/Arclet-Alconna-2564c2.svg)\n![latest release](https://img.shields.io/github/release/ArcletProject/Alconna)\n[![Licence](https://img.shields.io/github/license/ArcletProject/Alconna)](https://github.com/ArcletProject/Alconna/blob/master/LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/arclet-alconna)](https://pypi.org/project/arclet-alconna)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/arclet-alconna)](https://www.python.org/)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FArcletProject%2FAlconna.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2FArcletProject%2FAlconna?ref=badge_shield)\n\n[**简体中文**](README.md)|[**English**](README-EN.md)\n\n## About\n\n`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`.\n\n`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.\n\n## Installation\n\npip\n```shell\n$ pip install --upgrade arclet-alconna\n$ pip install --upgrade arclet-alconna[full]\n```\n\n## Documentation\n\nOfficial Document : [👉Link](https://arclet.top/docs/tutorial/alconna)\n\nRelevant Document : [📚Docs](https://graiax.cn/guide/message_parser/alconna.html)\n\n## A Simple Example\n\n```python\nfrom arclet.alconna import Alconna, Option, Subcommand, Args\n\ncmd = Alconna(\n    \"/pip\",\n    Subcommand(\"install\", Option(\"-U|--upgrade\"), Args.pak(str)),\n    Option(\"list\")\n)\n\nresult = cmd.parse(\"/pip install numpy --upgrade\") # This method returns an 'Arparma' class instance.\nprint(result.query('install'))  # Or result.install\n```\n\nOutput as follows:\n```\nvalue=None args={'pak': 'numpy'} options={'upgrade': value=Ellipsis args={}} subcommands={}\n```\n\n## Communication\n\nQQ Group: [Link](https://jq.qq.com/?_wv=1027\u0026k=PUPOnCSH)\n\n## Features\n\n* High Performance. On i5-10210U, performance is about `71000~289000 msg/s`; test script: [benchmark](benchmark.py)\n* Intuitive way to create command components\n* Powerful Automatic Type Parse and Conversion\n* Customizable Help Text Formatter and Control of Command Analyser\n* i18n Support\n* Cache of input command for quick response of repeated command\n* Easy-to-use Construct and Usage of Command Shortcut\n* Can bind callback function to execute after command parsing\n* Can create command completion session to implement multi-round continuous completion prompt\n* Various Features (FuzzyMatch, Output Capture, etc.)\n\nExample of Callback Executor:\n\n```python\n# callback.py\nfrom arclet.alconna import Alconna, ArgsBase\n\nclass CallbackArgs(ArgsBase):\n    foo: int\n    bar: str\n\nalc = Alconna(\"callback\", CallbackArgs)\n\n@alc.bind()\ndef cb(args: CallbackArgs):\n    print(f\"foo: {args.foo}\")\n    print(f\"bar: {args.bar}\")\n    print(args.bar * args.foo)\n    \nif __name__ == \"__main__\":\n    alc()\n```\n\n```shell\n$ python callback.py 3 hello\nfoo: 3\nbar: hello\nhellohellohello\n```\n\n\nExample of Type Conversion:\n\n```python\nfrom arclet.alconna import Alconna, Args\nfrom pathlib import Path\n\nread = Alconna(\"read\", Args.data(bytes))\n\n@read.bind()\ndef cb(data: bytes):\n    print(type(data))\n\nread.parse([\"read\", b'hello'])\nread.parse(\"read test_fire.py\")\nread.parse([\"read\", Path(\"test_fire.py\")])\n\n'''\n\u003cclass 'bytes'\u003e\n\u003cclass 'bytes'\u003e\n\u003cclass 'bytes'\u003e\n'''\n```\n\nExample of Component creation:\n```python\n# component.py\nfrom arclet.alconna import Alconna, Args, Option, Subcommand, store_true, count, append\n\nalc = Alconna(\n    \"component\",\n    Args.path(str),\n    Option(\"--verbose|-v\", action=count),\n    Option(\"-f\", Args.flag(str), compact=True, action=append),\n    Subcommand(\"sub\", Option(\"bar\", action=store_true, default=False))\n)\n\nif __name__ == '__main__':\n    res = alc()\n    print(res.query(\"path\"))\n    print(res.query(\"verbose.value\"))\n    print(res.query(\"f.flag\"))\n    print(res.query(\"sub\"))\n```\n\n```shell\n$ python component.py /home/arclet -vvvv -f1 -f2 -f3 sub bar\n/home/arclet\n4\n['1', '2', '3']\n(value=Ellipsis args={} options={'bar': (value=True args={})} subcommands={})\n```\n\nExample of Command Shortcut:\n```python\n# shortcut.py\nfrom arclet.alconna import Alconna, Args\n\nalc = Alconna(\"eval\", Args.content(str))\nalc.shortcut(\"echo\", {\"command\": \"eval print(\\\\'{*}\\\\')\"})\n\n@alc.bind()\ndef cb(content: str):\n    eval(content, {}, {})\n\nif __name__ == '__main__':\n    alc()\n```\n\n```shell\n$ python shortcut.py eval print(\\\"hello world\\\")\nhello world\n$ python shortcut.py echo hello world!\nhello world!\n```\n\nExample of Command Completion:\n```python\n# completion.py\nfrom arclet.alconna import Alconna, Args, Option\n\nalc = Alconna(\"complete\", Args.bar(int)) + Option(\"foo\") + Option(\"fool\")\n\nif __name__ == \"__main__\":\n    alc()\n```\n\n```shell\n$ python completion.py ?\nsuggest input follows:\n* bar: int\n* --help\n* -h\n* foo\n* fool\n```\n\nExample of `typing` Support:\n```python\nfrom typing import Annotated  # or typing_extensions.Annotated\nfrom arclet.alconna import Alconna, Args\n\nalc = Alconna(\"test\", Args.foo(Annotated[int, lambda x: x % 2 == 0]))\nalc.parse(\"test 2\")\nalc.parse(\"test 3\")\n\n'''\n'foo': 2\nParamsUnmatched: param 3 is incorrect\n'''\n```\n\nExample of FuzzyMatch:\n\n```python\n# fuzzy.py\nfrom arclet.alconna import Alconna, Config, Arg\n\nalc = Alconna('!test_fuzzy', Arg(\"foo\", str), Config(fuzzy_match=True))\n\nif __name__ == \"__main__\":\n    alc()\n\n```\n\n```shell\n$ python fuzzy.py /test_fuzzy foo bar\n/test_fuzy not matched. Are you mean \"!test_fuzzy\"?\n```\n\n## Examples\n\n| Name           | File                                     |\n|----------------|------------------------------------------|\n| Calculate      | [calculate.py](./example/calculate.py)   |\n| Execute        | [exec_code.py](./example/exec_code.py)   |\n| Request Route  | [endpoint.py](./example/endpoint.py)     |\n| Image Search   | [img_search.py](./example/img_search.py) |\n| PIP            | [pip.py](./example/pip.py)               |\n| Database Query | [exec_sql.py](./example/exec_sql.py)     |\n\n## License\n\nAlconna is licensed under the [MIT License](LICENSE).\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FArcletProject%2FAlconna.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2FArcletProject%2FAlconna?ref=badge_large)\n\n## Acknowledgement\n\n[JetBrains](https://www.jetbrains.com/): Support Authorize for [PyCharm](https://www.jetbrains.com/pycharm/)\u003cbr\u003e\n[\u003cimg src=\"https://cdn.jsdelivr.net/gh/Kyomotoi/CDN@master/noting/jetbrains-variant-3.png\" width=\"200\"/\u003e](https://www.jetbrains.com/)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farcletproject%2Falconna","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farcletproject%2Falconna","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farcletproject%2Falconna/lists"}