可扩展子命令的命令行助手库
subparse的Python项目详细描述
argparse的包装器,提供基于decorator的子命令支持。
命令可以与实际的主要功能分开定义, 实现更快的导入时间。
基本用法
from subparse import CLI class MyApp(object): def __init__(self, quiet=False): self.quiet = quiet def info(self, *msg): if not self.quiet: print('[info]', *msg) def context_factory(cli, args): return MyApp(args.quiet) def generic_options(parser): parser.add_argument('--quiet', action='store_true', help='turn of debugging') cli = CLI(version='0.0', context_factory=context_factory) cli.add_generic_options(generic_options) @cli.command(__name__ + ':foo_main') def foo(parser): """ a short description ending in a period. a longer description """ parser.add_argument('--bar', action='store_true', help='turn on bar') def foo_main(app, args): app.info('Hello World!') result = cli.run() sys.exit(result)
懒惰的装饰者
命令可以懒散地定义,稍后再获取。这将删除排序 命令和cli对象之间的限制。
可以定义包含命令的模块,而不必考虑实际的 CLI实例:
# myapp/info.py from subparse import command @command('myapp.info:foo_main') def foo(parser): """perform foo"""
稍后,当创建CLI的实例时,可以加载命令 并注册:
cli = CLI() cli.load_commands('myapp.info')
入口点
命令也可以在外部模块中定义并通过入口加载 要点。
from subparse import cli cli = CLI() cli.load_commands_from_entry_point('myapp.commands')
然后,扩展应用程序将定义应该 搜索命令。同样,这允许命令本身 独立定义主要功能,提高导入速度。
扩展包应该定义一个模块,其中包含 命令:
# barpkg/commands.py from subparse import command @command('barpkg.bar') def bar(parser): """perform bar"""
包还应该定义要为每个命令调用的函数。 (可选)在单独的模块中,以避免导入运行时依赖项 解析期间:
# barpkg/bar.py def main(app, args): pass
然后,包可以广播模块barpkg.commands 包含支持的命令:
[myapp.commands] barpkg = barpkg.commands
现在,当安装扩展包时,命令将自动 变得可用。
上下文工厂
执行每个子命令时,都会传递一个上下文对象,该对象定义 子命令之间可重用的api。这真是 subparse,这使得构建自己的共享cli功能变得非常容易。
subparse.CLI的context_factory参数允许定义 传递给所有命令的对象。这个工厂也可以是 生成器,允许它yield上下文对象,然后清除 命令完成后。例如:
import transaction def context_factory(cli, args): tm = transaction.TransactionManager(explicit=True) with tm: yield tm
在上面的示例中,事务管理器可用于所有子命令 它可以根据命令是否引发异常来提交/中止。
每个子命令都可以通过 context_kwargs参数。例如,如果单个子命令希望 退出事务管理器:
def context_factory(cli, args, without_tm=False): if without_tm: yield tm = transaction.TransactionManager(explicit=True) with tm: yield tm @command(..., context_kwargs=dict(without_tm=True)) def foo(parser): """" Run a command without the tm enabled."""
0.5.3(2019-03-09)
- 解析失败时将帮助输出到sys.stderr。
- 支持将context_kwargs传递给commanddecorator。这些 当命令是 执行。
0.5.2(2019-03-09)
- 对帮助输出中的子命令排序。
0.5.1(2019-03-08)
- 使用argparse.RawTextHelpFormatterformatter类。
0.5(2019-03-08)
- 添加Python3.7支持。
- 修复来自setuptools的弃用警告。
- 更接近于pep-257的docstring解析。
- 使用 argparse.RawDescriptionHelpFormatter格式化程序类。
0.4(2018-05-03)
- 放弃对Python2.6、3.2和3.3的支持。
- 添加Python3.4、3.5、3.6支持。
- 允许context_factory作为生成上下文的生成器。 这允许上下文包装cli的整个生命周期。
0.3.3(2013-08-12)
0.3.2没有功能变化。
- 改进文档。
0.3.2(2013-08-06)
- 添加cli.runapi以便简单地执行命令行。
0.3.1(2013-08-06)
- 提高帮助输出。
0.3(2013-08-06)
- 将子命令重命名为api中的命令。
0.2(2013-08-06)
- 函数名中的下划线在其respe中转换为破折号活跃的 子命令名称。
- 添加cli.add_generic_选项。
- 添加一个新的help子命令,允许myapp help foo。
- 允许子命令规范中的相对导入。
0.1(2013-08-05)
- 初始提交