subparse 0.6

基本用法

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。这实际上是< span class="docutils literal">subparse的秘诀，使得构建自己的共享CLI功能变得非常简单。

< span class="docutils literal">subparse.CLI的< span class="docutils literal">context_factory参数允许定义一个对象，该对象将被传递给所有命令。该工厂也可以是一个生成器，允许它在命令完成后清理上下文对象。例如

import transaction

def context_factory(cli, args):
    tm = transaction.TransactionManager(explicit=True)
    with tm:
        yield tm

在上面的示例中，事务管理器对所有子命令都是可用的，并且可以根据命令是否引发异常来提交/中止。

每个子命令都可以通过< span class="docutils literal">context_kwargs参数将自定义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.6 (2022-05-15)

• 删除Python 2.7，3.4，3.5，3.6，3.7。

• 添加Python 3.8，3.9，3.10。

• 删除对pkg_resources的依赖，并使用importlib.metadata。

• 100%测试覆盖率。

0.5.3 (2019-03-09)

• 解析失败时将帮助信息输出到< span class="docutils literal">sys.stderr。

• 支持将< span class="docutils literal">context_kwargs传递给< span class="docutils literal">command装饰器。这些参数将在命令执行时传递给< span class="docutils literal">context_factory。

0.5.2 (2019-03-09)

• 对帮助输出中的子命令进行排序。

0.5.1 (2019-03-08)

• 使用< span class="docutils literal">argparse.RawTextHelpFormatter格式化器类。

0.5 (2019-03-08)

• 添加Python 3.7支持。

• 修复来自setuptools的弃用警告。

• 更符合PEP-257对docstring解析的要求。

• 使用< span class="docutils literal">argparse.RawDescriptionHelpFormatter格式化器类修改帮助文本的显示方式。

0.4 (2018-05-03)

• 删除对Python 2.6，3.2和3.3的支持。

• 添加Python 3.4，3.5，3.6支持。

• 允许< span class="docutils literal">context_factory是一个生成器，它产生上下文。这使得上下文可以覆盖CLI的全生命周期。

0.3.3 (2013-08-12)

从0.3.2版本以来没有功能上的变化。

• 改进文档。

0.3.2 (2013-08-06)

• 添加< cite>CLI.run API，用于简单执行命令行。

0.3.1 (2013-08-06)

• 改进帮助输出。

0.3 (2013-08-06)

• 在API中将子命令重命名为命令。

0.2 (2013-08-06)

• 将函数名中的下划线转换为相应子命令名中的破折号。

• 添加< cite>CLI.add_generic_options API。

• 添加一个新的< cite>help子命令，允许使用< cite>myapp help foo。

• 允许在子命令规范中执行相对导入。

0.1 (2013-08-05)

• 初始提交