入门

实例结构

前提

确保您已阅读关于命令结构的部分

一个Alconna实例的主要结构如下:

该结构仅为示例，实际结构会有所不同
-- Commands --
Alconna
├── command: Any
├── main_args: Args
├── prefixes: List[Any] | List[[Any, String]]
├── options: List[Option | Subcommand]
├── separator: String
├── meta: CommandMeta
└── ...

-- Args --
Arg
├── name: String
├── value: BasePattern
├── default: Any
├── separator: String
└── flags: List[String]

Args
├── arguments
│   ├── name1: Arg1
│   ├── name2: Arg2
│   └── ...
└── ...

-- Components --
Option
├── name: String
├── args: Args
├── aliases: List[String]
├── action: Action
├── default: Any
└── separator: String

Subcommand
├── name: String
├── args: Args
├── options: List[Option | Subcommand]
├── default: Any
└── separator: String

若将其线性化，则表示为:

ARG : [Text | Bool | Number | Object];
ARG_SEP : String;
ARGS : ARG *(ARG_SEP ARG);
OPTION : NAME/ALIAS [OPT_SEP ARGS];
SUBCOMMAND : NAME [SUB_SEP ARGS] *(SUB_SEP OPTION/SUBCOMMAND);
COMMAND : [PREFIXES] COMMAND [MAIN_SEP ARGS] *(MAIN_SEP OPTION/SUBCOMMAND);

当命令传入给 Alconna 解析时, 解析器将首先检查命令的头部(即 prefix + command), 再尝试将参数作为 Option 或 Subcommand 解析, 如果解析失败, 则将参数作为 main args 解析.

构造方法

Alconna 目前提供了5种构造方式, 其中后面四种方法需要安装 arclet-alconna-tools 包.

标准方式
字符串方式
格式化方式
装饰器方式
对象方式

可以传入全部参数的构造方式

from arclet.alconna import Alconna

alc = Alconna(...)

无法传入子命令

from arclet.alconna.tools import AlconnaString

alc = AlconnaString(...).build()

无法写入帮助信息、命令头、子命令、选项别名

from arclet.alconna.tools import AlconnaFormat

alc = AlconnaFormat(...)

无法传入子命令

from arclet.alconna.tools import AlconnaDecorate

alc = AlconnaDecorate(...)


@alc.command()
def test(...):
    pass

复杂的构造方式, 强制使用报错选项

from arclet.alconna.tools import AlconnaFire

def test(...):
    pass

alc = AlconnaFire(test)

示范

现在，我们假设需要构建的命令如下:

/pip
Usage:
  /pip <command> [options]

Commands:
  install                     Install packages.
  list                        List installed packages.
  show                        Show information about installed packages.
  help                        Show help for commands.

General Options:
  --help                      Show help.
  --retries <retries>         Maximum number of retries each connection should attempt (default 5 times).
  --timeout <sec>             Set the socket timeout (default 15 seconds).
  --exists-action <action>    Default action when a path already exists: (s)witch, (i)gnore, (w)ipe, (b)ackup, (a)bort.
  --trusted-host <hostname>   Mark this host or host:port pair as trusted, even though it does not have valid or any HTTPS.

根据上述的Alconna结构与前文的命令结构分析，我们可以得到这样的 Alconna:

/src/test_alconna.py
from arclet.alconna import Alconna, Option, Subcommand, Args, OptionResult
import sys

pip = Alconna(
    "/pip",
    Subcommand(
        "install", [
            Option("--upgrade"),
            Option("-i|--index-url", Args.url["url"])
        ],
        Args.pak[str]
    ),
    Subcommand("show", Args.pak[str]),
    Subcommand("help", Args.command[str]),
    Option("list"),
    Option("--retries", Args.retries[int], default=OptionResult(args={"retries": 5})),
    Option("-t|--timeout", Args.sec[int], default=OptionResult(args={"sec": 15})),
    Option("--exists-action", Args.action[str]),
    Option("--trusted-host", Args.host_name["url"])
)

if __name__ == "__main__":
    args = sys.argv[1:]
    print(pip.parse(" ".join(args)).all_matched_args)

现在你可以尝试如下输入:

实时编辑器

let cmd = new Command("/pip", null, new Args(), [
    new Subcommand(
        "install",
        Args.push("pak", String),
        [new Option("--upgrade"),  new Option("-i|--index-url", Args.push("iu", String))]
    ),
    new Subcommand("list", null, [new Option("--outdated")]),
    new Subcommand("show", Args.push("pak", String)),
    new Subcommand("help", Args.push("command", String)),
    new Option("--retries", Args.push("retries", Number)),
    new Option("-t|--timeout", Args.push("sec", Number)),
    new Option("--exists-action", Args.push("action", String)),
    new Option("--trusted-host", Args.push("host_name", String))
])

const Show = (props) => {
  let res = cmd.parse(props.input);
  let matches = [];
  res.allArgs.forEach((v, k) => {
    matches.push(`${k}=${v}`, <br/>)
  })
  return (
  <>
    <h2>匹配结果: {String(res.matched)}</h2>
    <p>{matches}</p>
  </>
  )
};

render(<Show input={
"/pip install numpy --upgrade -i http://pypi.douban.com/simple --trusted-host pypi.douban.com"
}/>);

let cmd = new Command("/pip", null, new Args(), [
    new Subcommand(
        "install",
        Args.push("pak", String),
        [new Option("--upgrade"),  new Option("-i|--index-url", Args.push("iu", String))]
    ),
    new Subcommand("list", null, [new Option("--outdated")]),
    new Subcommand("show", Args.push("pak", String)),
    new Subcommand("help", Args.push("command", String)),
    new Option("--retries", Args.push("retries", Number)),
    new Option("-t|--timeout", Args.push("sec", Number)),
    new Option("--exists-action", Args.push("action", String)),
    new Option("--trusted-host", Args.push("host_name", String))
])

const Show = (props) => {
  let res = cmd.parse(props.input);
  let matches = [];
  res.allArgs.forEach((v, k) => {
    matches.push(`${k}=${v}`, <br/>)
  })
  return (
  <>
    <h2>匹配结果: {String(res.matched)}</h2>
    <p>{matches}</p>
  </>
  )
};

render(<Show input={
"/pip install numpy --upgrade -i http://pypi.douban.com/simple --trusted-host pypi.douban.com"
}/>);

结果

fast →python test_alconna.py "/pip install numpy --upgrade -i http://pypi.douban.com/simple --trusted-host pypi.douban.com" {'host_name': 'pypi.douban.com', 'pak': 'numpy', 'url': 'http://pypi.douban.com/simple'} restart ↻

注意事项

想正确使用 Alconna，你首先需要明确自己需求的命令和对应的命令结构

拼接的字符串, 或是复杂的自然语句, 这些并不能算作严格意义上的命令, 你可以直接使用正则解析, 或是使用 NLP

信息

这并不意味着 Alconna 无法处理上述格式. 相反, 若提供了有效的命令结构, Alconna 一样可以解析这些命令

一般，你需要把命令分为四个部分:

命令名称：作为一个命令的标识符
命令分隔符：一般是空格, 作为参数之间的区分符号
命令参数：一个命令所需求的主要参数, 可以为空
命令选项：为命令添加额外的解释参数, 或以此选择命令的不同功能

在上述例子中, pip是命令名称, 而剩下的install, --retries都是命令选项.

若用一个类来比喻的话, 命令参数就是__init__方法的参数, 命令名称就是Class.__name__, 命令选项则是该类下的所有类方法.

入门

实例结构​

构造方法​

示范​

注意事项​

实例结构

构造方法

示范

注意事项