Metadata-Version: 2.1
Name: arclet-alconna
Version: 1.0.0
Summary: A High-performance, Generality, Humane Command Line Arguments Parser Library.
Home-page: https://github.com/ArcletProject/Alconna
Author: ArcletProject
Author-email: rf_tar_railt@qq.com
License: MIT
Project-URL: Documentation, https://arcletproject.github.io/docs/alconna/tutorial
Project-URL: Bug Reports, https://github.com/ArcletProject/Alconna/issues
Project-URL: Source, https://github.com/ArcletProject/Alconna
Keywords: command,argparse,fast,alconna,cli,parsing,optparse,command-line,parser
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/rst
License-File: LICENSE
Requires-Dist: typing-extensions
Provides-Extra: cli
Requires-Dist: arclet-alconna-cli ; extra == 'cli'
Provides-Extra: full
Requires-Dist: arclet-alconna-cli ; extra == 'full'
Requires-Dist: arclet-alconna-graia ; extra == 'full'
Provides-Extra: graia
Requires-Dist: arclet-alconna-graia ; extra == 'graia'

.. container::

   .. rubric:: Alconna
      :name: alconna

|Alconna| |latest release| |Licence| |PyPI| |PyPI - Python Version|

**English**: `README <README-EN.md>`__

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

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

安装
----

pip

::

   pip install --upgrade arclet-alconna

文档
----

文档链接:
`👉指路 <https://arcletproject.github.io/docs/alconna/tutorial>`__

相关文档: `📚文档 <https://graiax.cn/guide/alconna.html#alconna>`__

简单使用
--------

.. code:: python

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

   cmd = Alconna(
       "/pip",
       options=[
           Subcommand("install", [Option("-u|--upgrade")], Args.pak_name[str]),
           Option("list"),
       ]
   )

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

其结果为

::

   {'value': None, 'args': {'pak_name': 'cesloi'}, 'options': {'upgrade': Ellipsis}}

讨论
----

QQ 交流群: `链接 <https://jq.qq.com/?_wv=1027&k=PUPOnCSH>`__

特点
----

-  高效. 在 i5-10210U 处理器上, 性能大约为 ``41000~101000 msg/s``;
   测试脚本: `benchmark <dev_tools/benchmark.py>`__
-  精简、多样的构造方法
-  强大的类型解析与转换功能
-  可传入同步与异步的 action 函数
-  高度自定义的 HelpFormat、Analyser
-  自定义语言文件, 支持 i18n
-  命令输入缓存, 以保证重复命令的快速响应
-  Duplication、FuzzyMatch等一众特性

类型转换示范:

.. code:: python

   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'>
   '''

模糊匹配示范:

.. code:: python

   from arclet.alconna import Alconna
   alc = Alconna('!test_fuzzy', "foo:str", is_fuzzy_match=True)
   alc.parse("！test_fuzy foo bar")

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

typing 支持示范:

.. code:: python

    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 不正确
    '''

许可
----

Alconna 采用 `MIT <LICENSE>`__ 许可协议

鸣谢
----

`JetBrains <https://www.jetbrains.com/>`__: 为本项目提供
`PyCharm <https://www.jetbrains.com/pycharm/>`__ 等 IDE 的授权
` <https://www.jetbrains.com/>`__

.. |Alconna| image:: https://img.shields.io/badge/Arclet-Alconna-2564c2.svg
.. |latest release| image:: https://img.shields.io/github/release/ArcletProject/Alconna
.. |Licence| image:: https://img.shields.io/github/license/ArcletProject/Alconna
   :target: https://github.com/ArcletProject/Alconna/blob/master/LICENSE
.. |PyPI| image:: https://img.shields.io/pypi/v/arclet-alconna
   :target: https://pypi.org/project/arclet-alconna
.. |PyPI - Python Version| image:: https://img.shields.io/pypi/pyversions/arclet-alconna
   :target: https://www.python.org/


