Alconna

WARNING

该教程是对整个 Alconna 特性的大致归纳，以帮助读者熟悉 Alconna 的使用与开发。

有关更多详细内容，请参阅文档(/guide/alconna)

Alconna 是 Arclet Project 下负责命令参数解析的模块，是 Arclet 的核心模块之一。

我们通过一个例子来讲解 Alconna 的核心 —— Args, Subcommand, Option：

python

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

alc = Alconna(
    "pip",
    Subcommand(
        "install",
        Args["package", str],
        Option("-r|--requirement", Args["file", str]),
        Option("-i|--index-url", Args["url", str]),
    )
)

res = alc.parse("pip install arclet-entari -i URL")

print(res)
# matched=True, header_match=(origin='pip' result='pip' matched=True groups={}), subcommands={'install': (value=Ellipsis args={'package': 'arclet-entari'} options={'index-url': (value=None args={'url': 'URL'})} subcommands={})}, other_args={'package': 'nonebot2', 'url': 'URL'}

print(res.all_matched_args)
# {'package': 'arclet-entari', 'url': 'URL'}

解释

这段代码通过 Alconna 创建了一个接受主命令名为 pip, 子命令为 install 且子命令接受一个 Args 参数package和二个 Option 参数requirement和index-url的命令参数解析器, 通过parse方法返回解析结果 Arparma 的实例。

其特点有:

高效
直观的命令组件创建方式，例如选项别名，默认值，解析操作等
强大的类型解析与类型转换功能，具体在 Args 的使用上
自定义的帮助信息格式，帮助信息由内置选项 help 触发，用户可以选择自定义的 TextFormatter 获得不一样的输出格式
多语言支持，目前支持中文与英文
易用的快捷命令创建与使用，可由内置选项 shortcut 触发，或使用 Alconna.shortcut() 方法
可创建命令补全会话, 以实现多轮连续的补全提示
可通过 Namespace，CommandMeta 配置命令的行为与属性，例如通过 Namespace 自定义内置选项的触发字段，或通过 CommandMeta 启用模糊匹配
可嵌套的多级子命令
Duplication 能像 argparse.Namespace 一样获取指定的解析结果并获得类型支持
正则匹配支持
...

安装

pdmpoetrypip

bash

pdm add arclet-alconna

bash

poetry add arclet-alconna

bash

pip install --upgrade arclet-alconna

参数声明(Args)

Args 是用于声明命令参数的组件, 在 Alconna 中有非常重要的地位，甚至称得上是核心，比 Alconna 重要十倍甚至九倍。

Args 可以通过以下几种方式构造：

Args[key, var, default][key1, var1, default1][...]
Args[(key, var, default)]
Args.key[var, default]

其中，key 一定是字符串，而 var 一般为参数的类型，default 为具体的值或者 arclet.alconna.args.Field。

其与函数签名类似，但是允许含有默认值的参数在前；同时支持 keyword-only 参数不依照构造顺序传入（但是仍需要在非 keyword-only 参数之后）。

参数名(key)

key 的作用是用以标记解析出来的参数并存放于 Arparma 中，以方便用户调用。

其有三种为 Args 注解的标识符，为 ?、/ 与 !。标识符与 name 之间建议以 ; 分隔：

! 标识符表示该处传入的参数应不是规定的类型，或不在指定的值中。
? 标识符表示该参数为可选参数，会在无参数匹配时跳过。
/ 标识符表示该参数的类型注解需要隐藏。

另外，对于参数的注释也可以标记在 key 中，其与 key 或者标识符以 # 分割：foo#这是注释;? 或 foo?#这是注释

INFO

Args 中的 key 在实际命令中并不需要传入（keyword 参数除外）：

python

from arclet.alconna import Alconna, Args

alc = Alconna("test", Args["foo", str])
alc.parse("test --foo abc") # 错误
alc.parse("test abc") # 正确

若需要 test --foo abc，你应该使用 Option：

python

from arclet.alconna import Alconna, Args, Option

alc = Alconna("test", Option("--foo", Args["foo", str]))

参数值(var)

var 负责命令参数的类型检查与类型转化

Args 的var表面上看需要传入一个 type，但实际上它需要的是一个 nepattern.BasePattern 的实例：

python

from arclet.alconna import Args
from nepattern import BasePattern

# 表示 foo 参数需要匹配一个 @number 样式的字符串
args = Args["foo", BasePattern("@\d+")]

pip 示例中可以传入 str 是因为 str 已经注册在了 nepattern.global_patterns 中，因此会替换为 nepattern.global_patterns[str]

nepattern.global_patterns默认支持的类型有：

str: 匹配任意字符串
int: 匹配整数
float: 匹配浮点数
bool: 匹配 True 与 False 以及他们小写形式
hex: 匹配 0x 开头的十六进制字符串
url: 匹配网址
email: 匹配 xxxx@xxx 的字符串
ipv4: 匹配 xxx.xxx.xxx.xxx 的字符串
list: 匹配类似 ["foo","bar","baz"] 的字符串
dict: 匹配类似 {"foo":"bar","baz":"qux"} 的字符串
datetime: 传入一个 datetime 支持的格式字符串，或时间戳
Any: 匹配任意类型
AnyString: 匹配任意类型，转为 str
Number: 匹配 int 与 float，转为 int

同时可以使用 typing 中的类型：

Literal[X]: 匹配其中的任意一个值
Union[X, Y]: 匹配其中的任意一个类型
Optional[xxx]: 会自动将默认值设为 None，并在解析失败时使用默认值
List[X]: 匹配一个列表，其中的元素为 X 类型
Dict[X, Y]: 匹配一个字典，其中的 key 为 X 类型，value 为 Y 类型
...

TIP

几类特殊的传入标记：

"foo": 匹配字符串 "foo" (若没有某个 BasePattern 与之关联)
RawStr("foo"): 匹配字符串 "foo" (即使有 BasePattern 与之关联也不会被替换)
"foo|bar|baz": 匹配 "foo" 或 "bar" 或 "baz"
[foo, bar, Baz, ...]: 匹配其中的任意一个值或类型
Callable[[X], Y]: 匹配一个参数为 X 类型的值，并返回通过该函数调用得到的 Y 类型的值
"re:xxx": 匹配一个正则表达式 xxx，会返回 Match[0]
"rep:xxx": 匹配一个正则表达式 xxx，会返回 re.Match 对象
{foo: bar, baz: qux}: 匹配字典中的任意一个键, 并返回对应的值 (特殊的键 ... 会匹配任意的值)
...

特别的，你可以不传入 var，此时会使用 key 作为 var, 匹配 key 字符串。

MultiVar 与 KeyWordVar

MultiVar 是一个特殊的标注，用于告知解析器该参数可以接受多个值，类似于函数中的 *args，其构造方法形如 MultiVar(str)。

同样的还有 KeyWordVar，类似于函数中的 *, name: type，其构造方法形如 KeyWordVar(str)，用于告知解析器该参数为一个 keyword-only 参数。

INFO

MultiVar 与 KeyWordVar 组合时，代表该参数为一个可接受多个 key-value 的参数，类似于函数中的 **kwargs，其构造方法形如 MultiVar(KeyWordVar(str))

MultiVar 与 KeyWordVar 也可以传入 default 参数，用于指定默认值

MultiVar 不能在 KeyWordVar 之后传入

参数单元(Arg)

Arg 是 Args 的最小单位：

python

Args[Arg(k1, v1), Arg(k2, v2), ...]

Arg 初始化时可以传入：

name: 参数名
value: 参数类型
field: 参数域
seps: 参数分隔符
notice: 参数注释
flags: 参数标识符

Arg 可以通过传入 seps 指定该参数如何与后续数据区分，也可通过 Args 的 separators 参数统一设置

参数域(default/Field)

default 传入的是该参数的默认值或者 Field，以携带对于该参数的更多信息。

默认情况下 (即不声明) default 的值为特殊值 Empty。这也意味着你可以将默认值设置为 None 表示默认值为空值。

Field 构造需要的参数说明如下：

default: 参数单元的默认值
alias: 参数单元默认值的别名
completion: 参数单元的补全说明生成函数
unmatch_tips: 参数单元的错误提示生成函数，其接收一个表示匹配失败的元素的参数
missing_tips: 参数单元的缺失提示生成函数

选项与子命令(Option & Subcommand)

Option 与 Subcommand 是 Alconna 中的两个重要组件。

Option 和 Subcommand 可以传入一组 alias，

如 Option("--foo|-F|--FOO|-f")，Subcommand("foo", alias=["F"])

传入别名后，选项与子命令会选择其中长度最长的作为其名称。若传入为 "--foo|-f"，则命令名称为 "--foo"

特别提醒!!!

Option 的名字或别名没有要求必须在前面写上 -

Option 与 Subcommand 的唯一区别在于 Subcommand 可以传入自己的 Option 与 Subcommand

他们拥有如下共同参数：

help_text: 传入该组件的帮助信息
dest: 被指定为解析完成时标注匹配结果的标识符，不传入时默认为选项或子命令的名称 (name)
requires: 一段指定顺序的字符串列表，作为唯一的前置序列与命令嵌套替换
对于命令 test foo bar baz qux <a:int> 来讲，因为foo bar baz 仅需要判断是否相等, 所以可以这么编写：
python
```
Alconna("test", Option("qux", Args.a[int], requires=["foo", "bar", "baz"]))
```
1
default: 默认值，在该组件未被解析时使用使用该值替换。
特别的，使用 OptionResult 或 SubcomanndResult 可以设置包括参数字典在内的默认值：
python
```
from arclet.alconna import Option, OptionResult

opt1 = Option("--foo", default=False)
opt2 = Option("--foo", default=OptionResult(value=False, args={"bar": 1}))
```
1
2
3
4

选项操作(Action)

Option 可以特别设置传入一类 Action，作为解析操作

Action 分为三类：

store: 无 Args 时，仅存储一个值，默认为 Ellipsis；有 Args 时，后续的解析结果会覆盖之前的值
append: 无 Args 时，将多个值存为列表，默认为 Ellipsis；有 Args 时，每个解析结果会追加到列表中
当存在默认值并且不为列表时，会自动将默认值变成列表，以保证追加的正确性
count: 无 Args 时，计数器加一；有 Args 时，表现与 STORE 相同
当存在默认值并且不为数字时，会自动将默认值变成 1，以保证计数器的正确性。

Alconna 提供了预制的几类 action：

store，store_value，store_true，store_false
append，append_value
count

解析结果(Arparma)

Alconna.parse 会返回由 Arparma 承载的解析结果。

Arpamar 会有如下参数：

调试类
- matched: 是否匹配成功
- error_data: 解析失败时剩余的数据
- error_info: 解析失败时的异常内容
- origin: 原始命令，可以类型标注
分析类
- header_match: 命令头部的解析结果，包括原始头部、解析后头部、解析结果与可能的正则匹配组
- main_args: 命令的主参数的解析结果
- options: 命令所有选项的解析结果
- subcommands: 命令所有子命令的解析结果
- other_args: 除主参数外的其他解析结果
- all_matched_args: 所有 Args 的解析结果

Arparma 同时提供了便捷的查询方法 query[T]()，会根据传入的 path 查找参数并返回

path 支持如下：

main_args, options, ...: 返回对应的属性
args: 返回 all_matched_args
main_args.xxx, options.xxx, ...: 返回字典中 xxx键对应的值
args.xxx: 返回 all_matched_args 中 xxx键对应的值
options.foo, foo: 返回选项 foo 的解析结果 (OptionResult)
options.foo.value, foo.value: 返回选项 foo 的解析值
options.foo.args, foo.args: 返回选项 foo 的解析参数字典
options.foo.args.bar, foo.bar: 返回选项 foo 的参数字典中 bar 键对应的值 ...

同样, Arparma["foo.bar"] 的表现与 query() 一致

元数据(CommandMeta)

Alconna 的元数据相当于其配置，拥有以下条目：

description: 命令的描述
usage: 命令的用法
example: 命令的使用样例
author: 命令的作者
fuzzy_match: 命令是否开启模糊匹配
fuzzy_threshold: 模糊匹配阈值
raise_exception: 命令是否抛出异常
hide: 命令是否对 manager 隐藏
hide_shortcut: 命令的快捷指令是否在 help 信息中隐藏
keep_crlf: 命令解析时是否保留换行字符
compact: 命令是否允许第一个参数紧随头部
strict: 命令是否严格匹配，若为 False 则未知参数将作为名为 $extra 的参数
context_style: 命令上下文插值的风格，None 为关闭，bracket 为 {...}，parentheses 为 $(...)
extra: 命令的自定义额外信息

元数据一定使用 meta=... 形式传入：

python

from arclet.alconna import Alconna, CommandMeta

alc = Alconna(..., meta=CommandMeta("foo", example="bar"))

紧凑命令

Alconna, Option 可以设置 compact=True 使得解析命令时允许名称与后随参数之间没有分隔：

python

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

alc = Alconna("test", Args["foo", int], Option("BAR", Args["baz", str], compact=True), meta=CommandMeta(compact=True))

assert alc.parse("test123 BARabc").matched

这使得我们可以实现如下命令：

python

>>> from arclet.alconna import Alconna, Option, Args, append
>>> alc = Alconna("gcc", Option("--flag|-F", Args["content", str], action=append))
>>> alc.parse("gcc -Fabc -Fdef -Fxyz").query("flag.content")
['abc', 'def', 'xyz']

当 Option 的 action 为 count 时，其自动支持 compact 特性：

python

>>> from arclet.alconna import Alconna, Option, Args, count
>>> alc = Alconna("pp", Option("--verbose|-v", action=count, default=0))
>>> alc.parse("pp -vvv").query("verbose.value")
3

帮助信息

每个 Alconna 命令都可以通过 --help 或 -h 触发命令的帮助信息，并且可以通过继承 arclet.alconna.formatter.TextFormatter 来个性化信息样式，如：

python

from arclet.alconna import Alconna, Args, CommandMeta
from arclet.alconna.tools import MarkdownTextFormatter

alc = Alconna("test", Args["count#这是一个注释", int], formatter_type=MarkdownTextFormatter, meta=CommandMeta(description="Hello World"))
alc.parse("test --help")

输出:

txt

## Hello World

指令:

**test &lt;count:int&gt;**
### 注释:
&#96;&#96;&#96;
count: 这是一个注释
&#96;&#96;&#96;

除此之外，你可以通过 command_manager 获取当前程序下的所有命令：

python

from arclet.alconna import command_manager
...
print(command_manager.all_command_help())

输出:

txt

# 当前可用的命令有:
 - foo : Unknown
 - bar : Unknown
 - baz : Unknown
 - qux : Unknown
# 输入'命令名 --help' 查看特定命令的语法

TIP

Alconna 可以设置 meta.hide 参数以不被 command_manager 打印出来。

python

from arclet.alconna import Alconna, CommandMeta, command_manager
foo = Alconna("foo", meta=CommandMeta(hide=True))
...
print(command_manager.all_command_help())

输出:

txt

# 当前可用的命令有:
 - bar : Unknown
 - baz : Unknown
 - qux : Unknown
# 输入'命令名 --help' 查看特定命令的语法

命名空间配置

命名空间配置（以下简称命名空间）相当于 Alconna 的默认配置，其优先度低于 CommandMeta。

Alconna 默认使用 "Alconna" 命名空间。

命名空间有以下几个属性：

name: 命名空间名称
prefixes: 默认前缀配置
separators: 默认分隔符配置
formatter_type: 默认格式化器类型
fuzzy_match: 默认是否开启模糊匹配
raise_exception: 默认是否抛出异常
builtin_option_name: 默认的内置选项名称(--help, --shortcut, --comp)
disable_builtin_options: 默认禁用的内置选项(--help, --shortcut, --comp)
enable_message_cache: 默认是否启用消息缓存
compact: 默认是否开启紧凑模式
strict: 命令是否严格匹配
context_style: 命令上下文插值的风格
...

新建命名空间并替换

python

from arclet.alconna import Alconna, namespace, Namespace, Subcommand, Args, config


ns = Namespace("foo", prefixes=["/"])  # 创建 "foo"命名空间配置, 它要求创建的Alconna的主命令前缀必须是/

alc = Alconna("pip", Subcommand("install", Args["package", str]), namespace=ns) # 在创建Alconna时候传入命名空间以替换默认命名空间

# 可以通过with方式创建命名空间
with namespace("bar") as np1:
    np1.prefixes = ["!"]    # 以上下文管理器方式配置命名空间，此时配置会自动注入上下文内创建的命令
    np1.formatter_type = ShellTextFormatter  # 设置此命名空间下的命令的 formatter 默认为 ShellTextFormatter
    np1.builtin_option_name["help"] = {"帮助", "-h"}  # 设置此命名空间下的命令的帮助选项名称

# 你还可以使用config来管理所有命名空间并切换至任意命名空间
config.namespaces["foo"] = ns  # 将命名空间挂载到 config 上

alc = Alconna("pip", Subcommand("install", Args["package", str]), namespace=config.namespaces["foo"]) # 也是同样可以切换到"foo"命名空间

修改默认的命名空间

python

from arclet.alconna import config, namespace, Namespace


config.default_namespace.prefixes = [...]  # 直接修改默认配置

np = Namespace("xxx", prefixes=[...])
config.default_namespace = np  # 更换默认的命名空间

with namespace(config.default_namespace.name) as np:
    np.prefixes = [...]

快捷指令

快捷指令顾名思义，可以为基础指令创建便捷的触发方式, 并且传递参数给原命令

一般情况下你可以通过 Alconna.shortcut 进行快捷指令操作 (创建，删除).

shortcut 的第一个参数为快捷指令名称，第二个参数为 ShortcutArgs，作为快捷指令的配置

python

class ShortcutArgs(TypedDict):
    """快捷指令参数"""

    command: NotRequired[str]
    """快捷指令的命令"""
    args: NotRequired[list[Any]]
    """快捷指令的附带参数"""
    fuzzy: NotRequired[bool]
    """是否允许命令后随参数"""
    prefix: NotRequired[bool]
    """是否调用时保留指令前缀"""
    wrapper: NotRequired[ShortcutRegWrapper]
    """快捷指令的正则匹配结果的额外处理函数"""
    humanized: NotRequired[str]
    """快捷指令的人类可读描述"""

当 fuzzy 为 False 时，传入 "涩图1张 abc" 之类的快捷指令将视为解析失败

快捷指令允许三类特殊的 placeholder:

{%X}: 只用于 command, 如 setu {%0}，表示此处填入快截指令后随的第 X 个参数。
例如，若快捷指令为 涩图, 配置为 {"command": "setu {%0}"}, 则指令 涩图 1 相当于 setu 1
{*}: 只用于 command, 表示此处填入所有后随参数，并且可以通过 {*X} 的方式指定组合参数之间的分隔符。
{X}: 用于 command 与 args，表示此处填入可能的正则匹配的组：
- 若 command 中存在匹配组 (xxx)，则 {X} 表示第 X 个匹配组的内容
- 若 command 中存储匹配组 (?P<xxx>...), 则 {X} 表示名字为 X 的匹配结果

除此之外, 通过内置选项 --shortcut 可以动态操作快捷指令。

示例

args 的使用:

python

from arclet.alconna import Alconna, Args

alc = Alconna("setu", Args["count", int])
alc.shortcut("涩图(\d+)张", {"args": ["{0}"]})
# 'Alconna::setu 的快捷指令: "涩图(\\d+)张" 添加成功'
alc.parse("涩图3张").query("count")
# 3

command 的使用:

python

from arclet.alconna import Alconna, Args

alc = Alconna("eval", Args["content", str])
alc.shortcut("echo", {"command": "eval print(\\'{*}\\')"})
# 'Alconna::eval 的快捷指令: "echo" 添加成功'
alc.shortcut("echo", delete=True) # 删除快捷指令
# 'Alconna::eval 的快捷指令: "echo" 删除成功'

@alc.bind() # 绑定一个命令执行器, 若匹配成功则会传入参数, 自动执行命令执行器
def cb(content: str):
    eval(content, {}, {})

alc.parse('eval print(\\"hello world\\")')
# hello world
alc.parse("echo hello world!")
# hello world!

半自动补全

半自动补全为用户提供了推荐后续输入的功能。

补全默认通过 --comp 或 -cp 或 ? 触发：（命名空间配置可修改名称）

python

from arclet.alconna import Alconna, Args, Option

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

输出

txt

以下是建议的输入：
* <abc: int>
* --help
* -h
* -sct
* --shortcut
* foo
* bar

补全会话

补全会话基于半自动补全，提供了交互操作补全的接口

补全会话通过创建 CompSession 并进入上下文触发：

python

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

alc = Alconna("test", Args["abc", int]) + Option("foo") + Option("bar")

with CompSession(alc) as comp:
    alc.parse("test")
if comp.available:
    print("current completion:", comp.current())
    print("next completion:", comp.tab())
    with comp:
        res = comp.enter(["1"])

assert res.matched

Duplication

Duplication 用来提供更好的自动补全，类似于 ArgParse 的 Namespace，经测试表现良好（好耶）。

普通情况下使用，需要利用到 ArgsStub、OptionStub 和 SubcommandStub 三个部分，

以pip为例，其对应的 Duplication 应如下构造：

python

from arclet.alconna import OptionResult, Duplication, SubcommandStub

class MyDup(Duplication):
    verbose: OptionResult
    install: SubcommandStub  # 选项与子命令对应的stub的变量名必须与其名字相同

并在解析时传入 Duplication：

python

result = alc.parse("pip -v install ...", duplication=MyDup)
>>> type(result)
<class MyDup>

Duplication 也可以如 Namespace 一样直接标明参数名称和类型：

python

from typing import Optional
from arclet.alconna import Duplication


class MyDup(Duplication):
    package: str
    file: Optional[str] = None
    url: Optional[str] = None

使用模糊匹配

模糊匹配通过在 Alconna 中设置其 CommandMeta 开启。

模糊匹配会应用在任意需要进行名称判断的地方，如命令名称，选项名称和参数名称（如指定需要传入参数名称）。

python

from arclet.alconna import Alconna, CommandMeta

alc = Alconna("test_fuzzy", meta=CommandMeta(fuzzy_match=True))
alc.parse("test_fuzy")
# output: test_fuzy is not matched. Do you mean "test_fuzzy"?

上下文插值

当 context_style 条目被设置后，传入的命令中符合上下文插值的字段会被自动替换成当前上下文中的信息。

上下文可以在 parse 中传入：

python

from arclet.alconna import Alconna, Args, CommandMeta

alc = Alconna("test", Args["foo", int], meta=CommandMeta(context_style="parentheses"))

alc.parse("test $(bar)", {"bar": 123})
# {"foo": 123}

context_style 的值分两种：

"bracket": 插值格式为 {...}，例如 {foo}
"parentheses": 插值格式为 $(...)，例如 $(bar)

自定义语言文件

Alconna 的 i18n 支持使用了 Tarina.lang

其语言文件配置位于 arclet.alconna.i18n 下

您可以通过 tarina.lang.select 切换语言配置，也可以通过 tarina.lang.set 对单一文本进行修改。

参考链接

QQ 交流群: 🔗链接

要了解如何使用 Alconna-Graia, 参考消息链匹配/Alconna

要了解如何使用 nonebot-plugin-alconna, 参考 nonebot-plugin-alconna 文档

Alconna ​

安装 ​

参数声明(Args) ​

参数名(key) ​

参数值(var) ​

MultiVar 与 KeyWordVar ​

参数单元(Arg) ​

参数域(default/Field) ​

选项与子命令(Option & Subcommand) ​

选项操作(Action) ​

解析结果(Arparma) ​

元数据(CommandMeta) ​

紧凑命令 ​

帮助信息 ​

命名空间配置 ​

新建命名空间并替换 ​

修改默认的命名空间 ​

快捷指令 ​

示例 ​

半自动补全 ​

补全会话 ​

Duplication ​

使用模糊匹配 ​

上下文插值 ​

自定义语言文件 ​

参考链接 ​

Alconna

安装

参数声明(Args)

参数名(key)

参数值(var)

MultiVar 与 KeyWordVar

参数单元(Arg)

参数域(default/Field)

选项与子命令(Option & Subcommand)

选项操作(Action)

解析结果(Arparma)

元数据(CommandMeta)

紧凑命令

帮助信息

命名空间配置

新建命名空间并替换

修改默认的命名空间

快捷指令

示例

半自动补全

补全会话

Duplication

使用模糊匹配

上下文插值

自定义语言文件

参考链接