subparse 0.5.3

基本用法

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）

• 初始提交