QuickProject

介绍

Qpro是一个神奇的库，安装后，它将为你注册两个命令Qpro和qrun；

就像它的名字(QuickProject)一样，你可以轻而易举的创建一个快速项目，并基于此，自定义操作以及远程映射（及当前文件夹到远程服务器某个文件夹的连接关系）。

内置模板

在Qpro中，提供了许多预先定义好的模板，有基础模板： C/C++，Python(2和3)，Java，Scala；以及高级模板：Commander，PypiCommander，RISC-V，DCU。多数模板都无需配置开箱即用，部分高级模板需要跟随README.md文件中的提示进行少量配置。你可以通过Qpro create <项目名>命令，选择内置模板，输入你想要的模板名称并查询选择即可创建模板项目！

可扩展

熟练使用Qpro后，你会发现它的扩展性非常高，你几乎可以把它应用在各种工作中（就像Makefile一样），你可以创建自己的模板、基于Qpro开发命令行APP等等。

安装

pip3 install Qpro [--upgrade]
注意：Qpro需要python3.7或以上版本，如果你的Python版本低于3.6: pip3 install Qpro==0.7.0, 这是Qpro对低版本Python的最后支持。
ZSH的Tab补全：将项目地址下的complete/zsh/<your-language>/*拷贝到你的$fpath内，并在~/.zshrc中最后一行加入:
1
2
3
autoload -Uz compinit
zstyle ':completion:*' menu select
compinit
Fig的自动补全：将项目地址下的complete/fig/<your-language>/*.ts拷贝至你的fig加载路径内（通常为~/.fig/autocomplete/src，并在相应位置npm run build即可。

使用:

Command	Result
`Qpro init`	将当前文件夹初始化为Qpro项目
`Qpro -h`	查看帮助
`Qpro create project`	创建一个Qpro项目
`Qpro update`	更新Qpro
`Qpro ssh`	进入服务器Qpro项目位置
`Qpro scp path`	将项目内文件夹或文件上传到默认服务器
`Qpro scp-init`	将整个项目上传到默认服务器
`Qpro get path`	从服务器上拉取项目内文件
`Qpro del path`	从Qpro项目中删除文件(夹)
`Qpro del-all`	删除整个项目
`Qpro ls path`	查看远程映射上的文件
`Qpro enable-complete`	启用Commander类的自动补全
`Qpro register`	注册全局命令
`Qpro unregister`	注销全局命令
`Qpro gen-complete`	生成Zsh和Fig自动补全脚本
`qrun *`	使用运行脚本运行你的项目

初始化后的项目，可以手动编辑配置表project_configure.json来调整配置。

配置表

请您务必了解配置表的含义，QuickProject几乎完全根据配置表工作
修改project_configure.json来调整脚本默认配置

键值	含义
`build`	编译指令
`entry_point`	待编译的文件（入口文件）
`executable`	编译出的可执行文件路径或执行命令
`input_file`	默认的输入文件
`template_root`	模板库根目录
`server_targets`	远程映射
`[enable_complete]`	使qrun支持Commander 的 tab补全

样例

{
    "build": "编译指令",
    "entry_point": "入口文件",
    "executable": "执行指令",
    "input_file": "输入文件",
    "template_root": "模板目录",
    "server_targets": [
        {
            "user": "用户名（可缺省）",
            "host": "主机地址或.ssh/config中的HostName",
            "port": "端口",
            "path": "在远程主机的目录地址"
        }
    ],
    "enable_complete": true
}

注意：旧版本的server_target 已变更为 server_targets，你可以通过formatOldJson来替换全部旧的project_configure.json。

运行脚本

一个可以让你在项目任意位置调用的运行器。

编译或运行

参数	含义
-b	编译
-r	运行
-br	编译且运行

如果上述三个命令都不存在，则默认运行当前编译好的程序

输入输出

可以编辑 默认的输入文件 来设置默认输入
运行 qrun [...] > output.txt 使程序输出到 ./output.txt。

参数	效果
-i	使用默认的输入文件作为输入
-if `*`	更改输入文件
-if -paste	使用粘贴板内容作为输入

查看帮助

qrun -h : 可以查看使用帮助(Windows系统不支持颜色显示)

命令	效果
`qrun -i`	使用默认输入文件并运行
`qrun`	运行
`qrun -br -i`	编译且使用输入文件运行

命令装饰类

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

快速开始

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

app = Commander()


@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 --help
qrun hello world
qrun hello world --color red

创建自己的命令工具

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

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

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。
Commander对list类型的参数支持方式
- list类型仅支持设置为必填参数，且在调用时必须在命令的末尾赋值。
- 现假设list的参数命名为ops，则赋值方式为: qrun <sub_cmd> [若干其他参数] -ops a b c d，此样例命令中的a b c d都将作为字符串传递给ops列表。
Commander暂不支持解析dict, set类型的参数（未来也不打算支持）。

将Commander应用注册为全局命令

想随处运行自己刚刚开发的命令吗？将它注册为全局命令叭！

第一次注册全局命令

你需要创建一个“Qpro全局文件夹”，比如~/.local/QuickProject/，并将其作为QproGlobalDir的环境变量。

mkdir ~/.local/QuickProject
# 打开你的 .*shrc 文件
vim .zshrc
# 填入如下内容
export QproGlobalDir="$HOME/.local/QuickProject"

设置$PATH, 用于执行Qpro注册的全局命令。

# 打开你的 .*shrc 文件
vim .zshrc
# 填入如下内容
export PATH="$PATH:$QproGlobalDir/bin"

注册方式：Qpro register

自动补全脚本生成与应用

进入Commander APP文件夹下执行Qpro gen-complete，将创建一个complete文件夹并生成ZSH和FIG的补全插件，你需要手动将它们拷贝至相应位置并应用。通常：

Fig脚本路径为~/.fig/user/autocomplete/src或~/.fig/autocomplete/src，执行npm run build 应用。

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

自定义补全内容

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

自定义可选项

将上述样例代码改为如下内容（添加了@app.custom_complete('color')修饰的hello函数），则在Fig的补全中会限制color的内容。(注意，custom_complete必须在子命令之前定义才会生效)

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

app = Commander()

@app.custom_complete('color')
def hello():
    """
    自定义补全函数, 请勿将此函数用作它途.
    Custom completion function, do not use it as another way.
    """
    return ['red', 'green', 'blue', 'cyan', 'magenta', 'yellow', 'black', 'white']


@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()

有哪些基于Commander开发的APP？

链接	描述
https://github.com/Rhythmicc/jav	Jav 工具箱
https://github.com/Rhythmicc/CUP_Network	一个selenium脚本，用于在命令行中登录CUP校园网。
https://github.com/Rhythmicc/pypi	A pypi Assistant for QproPypiTemplate
https://github.com/Rhythmicc/DrawMtxAsThumbnail	绘制mtx的缩略图
https://github.com/Rhythmicc/Amy	本地的Amy Surge订阅链接转换，并保存至腾讯云对象存储
https://github.com/Rhythmicc/orders	你的程序代写订单助手
https://github.com/Rhythmicc/ClassFlower	小红花榜
https://github.com/Rhythmicc/tgpd	在终端里下载和预览telegra.ph文章里的套图！