命令 APP 框架

基于命令装饰类，你可以轻松开发支持跨平台、样式丰富的命令行工具。

快速开始

from QuickProject.Commander import Commander
from QuickProject import QproDefaultConsole as console

app = Commander('command-name')


@app.command()
def hello(name: str, color: str = 'cyan'):
    """
    echo Hello <name>

    :param name: str
    :param color: str
    """
    console.print(f"Hello [bold {color}]{name}[/]!")


def main():
    """
    注册为全局命令时, 默认采用main函数作为命令入口, 请勿将此函数用作它途.
    When registering as a global command, default to main function as the command entry, do not use it as another way.
    """
    app()


if __name__ == '__main__':
    main()

from QuickProject.Commander import Commander
from QuickProject import QproDefaultConsole as console

app = Commander('command-name')


@app.command()
def hello(name: str, color: str = 'cyan'):
    """
    echo Hello <name>

    :param name: str
    :param color: str
    """
    console.print(f"Hello [bold {color}]{name}[/]!")


def main():
    """
    注册为全局命令时, 默认采用main函数作为命令入口, 请勿将此函数用作它途.
    When registering as a global command, default to main function as the command entry, do not use it as another way.
    """
    app()


if __name__ == '__main__':
    main()

样例

qrun

qrun

qrun hello world

qrun hello world

qrun hello world --color red

qrun hello world --color red

创建自己的命令工具

通过Qpro create <项目名>命令，在内置模板中查询并选择commander以创建。

下面是 Commander 对 Python 基本类型的支持能力:

1. Commander 完整支持str, int, float, bool类型的参数。

TIP

Commander 对 bool 类型的参数支持方式

当 bool 类型的参数为必填参数时

• 这些值将被判定为 True：[True, 'True', 'true', 'yes', 1, 't', 'T', 'y', 'Y']
• 这些值将被判定为 False: [False, 'False', false, 'n', 0, 'f', 'F', 'n', 'N']

当 bool 类型的参数为可选参数时（假设参数名为flag）

• 推荐（强制要求）flag 默认设为 False。
• 在调用时加入--flag标志时，Commander 将把其解释为设置 flag 为 True。

2. Commander 对 list 类型的参数支持方式

注意⚠️

list 类型仅支持设置为必填参数，且在调用时必须在命令的末尾赋值。

现假设 list 的参数命名为ops，则赋值方式为: qrun <sub_cmd> [若干其他参数] -ops a b c d，此样例命令中的a b c d都将作为字符串传递给 ops 列表。

特别注意❕

Commander 暂不支持解析dict, set类型的参数（未来也不打算支持）。

将 Commander 应用注册为全局命令

想随处运行自己刚刚开发的命令吗？将它注册为全局命令叭！有两种主流的方式来安装你的命令：

1. 通过 git 安装

将你的 Commander APP 发布到 GitHub 或 Gitee 上，再以如下方式安装：

pip3 install git+<你的仓库地址>.git -U

pip3 install git+<你的仓库地址>.git -U

2. 自行打包安装

python3 setup.py sdist # 打包当前版本到dist/中
pip3 install dist/<代码包>

python3 setup.py sdist # 打包当前版本到dist/中
pip3 install dist/<代码包>

自动补全脚本生成与应用

Commander 可以帮助你为 APP 生成两种补全插件，分别是 Fig 和 ZSH；你只需要执行如下指令即可：

qrun complete # 在项目文件夹下执行
<APP 名称> complete # 全局命令可在任意位置执行

qrun complete # 在项目文件夹下执行
<APP 名称> complete # 全局命令可在任意位置执行

上述代码执行后会生成一个complete文件夹包含 FIG 和 ZSH 插件代码，其中 FIG 插件可以被自动应用，ZSH 插件需要手动应用。

ZSH 脚本路径为$FPATH，通常为/usr/local/share/zsh/site-functions。

自定义补全内容

Commander 会自动解析函数头部的注释部分，比如在上述的样例程序中，补全内容为:

更多高级文档

请查阅: 框架工具

有哪些基于 Commander 开发的 APP？