Python 函数转命令行界面库 -- Argsense CLI

argsense 是一个 python 命令行界面库, 是 click, fire, typer 之外的又一个选项.

argsense 最大的特点是极低的侵入性设计和近乎零成本的上手难度, 如果你熟悉 python 函数是如何传参的 (这是大部分 python 初学者已经掌握的知识), 那么你就可以很快上手 argsense.

特性一览

• 非常低的学习成本.
• 低侵入性设计: 任何被 argsense 装饰的函数, 仍然可以像原来一样在模块内调用.
• 现代化的界面.
• 基于类型标注实现的自动类型转换.
• 支持 *args 和 **kwargs 传参.
• docstring 解析.
• 友好的错误提示.

安装

项目地址: https://github.com/likianta/argsense-cli

通过 pip 安装:

pip install argsense
1

python 版本要求 3.8 及以上. 当前 argsense 最新版本为 0.5.0+.

使用

假设我们有一个脚本:

# hello_world.py

def hello(name: str):
    print(f"Hello, {name}!")

if __name__ == "__main__":
    hello("Alice")
1
2
3
4
5
6
7

导入 argsense, 使用 @cli.cmd() 装饰器, 将它转换为命令行程序:

# hello_world.py
from argsense import cli

@cli.cmd()
def hello(name: str):
    print(f"Hello, {name}!")

if __name__ == "__main__":
    cli.run()
1
2
3
4
5
6
7
8
9

现在, 我们在命令行中可以这样调用:

# 显示帮助
py hello_world.py hello -h

# 调用
py hello_world.py hello Alice
1
2
3
4
5

更多用法

使用 *args 和 **kwargs 传递参数

from argsense import cli

@cli.cmd()
def main(*args, **kwargs):
    print(args, kwargs)

if __name__ == "__main__":
    cli.run(main)
1
2
3
4
5
6
7
8

py main.py alpha beta :true :false :none --xxx hello --yyy world --zzz :true
1

类型自动转换

• 仅支持基本类型的转换.
• 如果没有标注类型, 则按照 str 类型处理.
• 如果标注为 typing.Any, 则根据值的特征进行自动推断, 例如 “123” 会被推断为 int.

from argsense import cli
from typing import Any

@cli.cmd()
def main(a: str, b: int, c: float, d: bool, e, f: 'any', g: Any):
    print([(x, type(x)) for x in (a, b, c, d, e, f, g)])

if __name__ == "__main__":
    cli.run(main)
1
2
3
4
5
6
7
8
9

py main.py -h
py main.py 1 2 3.12 :true foo :none :false
1
2

位置参数和关键字参数

from argsense import cli

@cli.cmd()
def main(a: int, b: int, c: int, d: int = None, e: int = None, f: int = None):
    print(a, b, c, d, e, f)

if __name__ == "__main__":
    cli.run(main)
1
2
3
4
5
6
7
8

py main.py -h
py main.py 1 2 3
py main.py 1 2 3 4 5 6
py main.py 1 2 3 --d 4 --e 5 --f 6
1
2
3
4

纠错演示

TODO

谁在使用它

下面是目前收集到的一部分使用 argsense 的开源项目, 你可以从下面的截图中获得灵感, 以及从这些项目源代码中 (通常是 __main__.py 脚本) 学习 argsense 的实际应用.

• depsland

  

• lk-qtquick-scaffold

  

• lk-utils

  

• markdown-image-lofter

  

原理

TODO

原理

TODO