模块化命令#

概述#

Cmd2 还允许开发者将其命令定义模块化为 CommandSet 对象。CommandSet 代表 cmd2 应用中命令的逻辑分组。默认情况下，CommandSet 对象需要手动注册。然而，通过在实例化 cmd2.Cmd 类时设置 auto_load_commands=True，可以自动发现和加载所有 CommandSet 对象。这还允许开发者动态地从 cmd2 应用中添加/移除命令。这对于添加额外功能的可加载插件非常有用。此外，它允许面向对象的封装和特定于 CommandSet 的状态的垃圾回收。

功能特性#

模块化命令集 - 命令可以被拆分为单独的模块，而不是在一个包含所有命令的”上帝类”中
自动命令发现 - 在应用中，只需定义和导入 CommandSet 就足以让 cmd2 发现和加载你的命令（如果设置了 auto_load_commands=True）。无需手动注册
动态可加载/可卸载命令 - 命令函数和 CommandSet 都可以在应用执行期间动态加载和卸载。这可以实现动态加载模块以添加额外命令等功能
事件处理器 - CommandSet 类中提供了四个事件处理器用于自定义初始化和清理步骤。详见事件处理器
子命令注入 - 子命令可以独立于基础命令定义。这允许以操作为中心（而非以对象为中心）的命令系统，同时仍然围绕被管理的对象组织代码和处理器

参阅 [cmd2.CommandSet][] 的 API 文档。

参阅示例了解更多细节。

定义命令#

命令集#

CommandSet 将多个命令组合在一起。插件将使用与在 cmd2.Cmd 中定义时相同的规则来检查 CommandSet 中的函数。命令必须以 do_ 为前缀，帮助函数以 help_ 为前缀，补全函数以 complete_ 为前缀。

CommandSet 命令方法期望的参数与在 cmd2.Cmd 子类中定义时相同，只是 self 现在将引用 CommandSet 而不是 cmd2 实例。cmd2 实例可以通过在 CommandSet 注册时填充的 self._cmd 来访问。

只有在初始化器不接受参数时，CommandSet 才会被自动加载。如果需要提供初始化器参数，请参阅手动 CommandSet 构造。

1
import cmd2
2
from cmd2 import CommandSet
3

4

5
class ExampleApp(cmd2.Cmd):
6
    """
7
    CommandSets are automatically loaded. Nothing needs to be done.
8
    """
9

10
    def __init__(self, *args, **kwargs):
11
        super().__init__(*args, auto_load_commands=True, **kwargs)
12

13
    def do_something(self, arg):
14
        """Something Command."""
15
        self.poutput("this is the something command")
16

17

18
class AutoLoadCommandSet(CommandSet[ExampleApp]):
19
    DEFAULT_CATEGORY = "My Category"
20

21
    def __init__(self):
22
        super().__init__()
23

24
    def do_hello(self, _: cmd2.Statement):
25
        """Hello Command."""
26
        self._cmd.poutput("Hello")
27

28
    def do_world(self, _: cmd2.Statement):
29
        """World Command."""
30
        self._cmd.poutput("World")

手动 CommandSet 构造#

如果 CommandSet 类需要向初始化器提供参数，你可以手动构造 CommandSet 并将其传递给 Cmd2。

1
import cmd2
2
from cmd2 import CommandSet
3

4

5
class ExampleApp(cmd2.Cmd):
6
    """
7
    CommandSets with initializer parameters are provided in the initializer
8
    """
9

10
    def __init__(self, *args, **kwargs):
11
        super().__init__(*args, auto_load_commands=True, **kwargs)
12

13
    def do_something(self, arg):
14
        """Something Command."""
15
        self.last_result = 5
16
        self.poutput("this is the something command")
17

18

19
class CustomInitCommandSet(CommandSet[ExampleApp]):
20
    DEFAULT_CATEGORY = "My Category"
21

22
    def __init__(self, arg1, arg2):
23
        super().__init__()
24
        self._arg1 = arg1
25
        self._arg2 = arg2
26

27
    def do_show_arg1(self, _: cmd2.Statement):
28
        """Show Arg 1."""
29
        self._cmd.poutput(f"Arg1: {self._arg1}")
30

31
    def do_show_arg2(self, _: cmd2.Statement):
32
        """Show Arg 2."""
33
        self._cmd.poutput(f"Arg2: {self._arg2}")
34

35

36
def main():
37
    my_commands = CustomInitCommandSet(1, 2)
38
    app = ExampleApp(command_sets=[my_commands])
39
    app.cmdloop()

类型提示与 self._cmd#

当 CommandSet 被注册时，其 _cmd 属性会被填充为对 cmd2.Cmd 实例的引用。CommandSet 是一个泛型类，允许你指定它期望被加载到的特定 cmd2.Cmd 子类。

通过使用你的应用类参数化继承，你的 IDE 和静态分析工具（如 Mypy）将知道 self._cmd 的确切类型。这在访问主应用实例的自定义属性或方法时提供了完整的自动补全和类型验证。

1
import cmd2
2
from cmd2 import CommandSet
3

4

5
class MyApp(cmd2.Cmd):
6
    def __init__(self):
7
        super().__init__()
8
        self.custom_state = "Some important data"
9

10

11
class MyCommands(CommandSet[MyApp]):
12
    def do_check_state(self, _: cmd2.Statement):
13
        # Type checkers know self._cmd is an instance of MyApp
14
        self._cmd.poutput(f"State: {self._cmd.custom_state}")

动态命令#

你还可以通过在运行时安装和移除 CommandSet 来动态加载和卸载命令。例如，你可以支持运行时可加载的插件或根据状态添加/移除命令。

如果需要在运行时动态加载命令，你可能需要禁用命令自动加载。

1
import argparse
2
import cmd2
3
from cmd2 import CommandSet, with_argparser, with_category
4

5

6
class LoadableFruits(CommandSet["ExampleApp"]):
7
    DEFAULT_CATEGORY = "Fruits"
8

9
    def __init__(self):
10
        super().__init__()
11

12
    def do_apple(self, _: cmd2.Statement):
13
        """Apple Command."""
14
        self._cmd.poutput("Apple")
15

16
    def do_banana(self, _: cmd2.Statement):
17
        """Banana Command."""
18
        self._cmd.poutput("Banana")
19

20

21
class LoadableVegetables(CommandSet["ExampleApp"]):
22
    DEFAULT_CATEGORY = "Vegetables"
23

24
    def __init__(self):
25
        super().__init__()
26

27
    def do_arugula(self, _: cmd2.Statement):
28
        """Arugula Command."""
29
        self._cmd.poutput("Arugula")
30

31
    def do_bokchoy(self, _: cmd2.Statement):
32
        """Bok Choy Command."""
33
        self._cmd.poutput("Bok Choy")
34

35

36
class ExampleApp(cmd2.Cmd):
37
    """
38
    CommandSets are loaded via the `load` and `unload` commands
39
    """
40

41
    def __init__(self, *args, **kwargs):
42
        super().__init__(*args, auto_load_commands=False, **kwargs)
43
        self._fruits = LoadableFruits()
44
        self._vegetables = LoadableVegetables()
45

46
    load_parser = cmd2.Cmd2ArgumentParser()
47
    load_parser.add_argument("cmds", choices=["fruits", "vegetables"])
48

49
    @with_argparser(load_parser)
50
    @with_category("Command Loading")
51
    def do_load(self, ns: argparse.Namespace):
52
        """Load Command."""
53
        if ns.cmds == "fruits":
54
            try:
55
                self.register_command_set(self._fruits)
56
                self.poutput("Fruits loaded")
57
            except ValueError:
58
                self.poutput("Fruits already loaded")
59

60
        if ns.cmds == "vegetables":
61
            try:
62
                self.register_command_set(self._vegetables)
63
                self.poutput("Vegetables loaded")
64
            except ValueError:
65
                self.poutput("Vegetables already loaded")
66

67
    @with_argparser(load_parser)
68
    def do_unload(self, ns: argparse.Namespace):
69
        """Unload Command."""
70
        if ns.cmds == "fruits":
71
            self.unregister_command_set(self._fruits)
72
            self.poutput("Fruits unloaded")
73

74
        if ns.cmds == "vegetables":
75
            self.unregister_command_set(self._vegetables)
76
            self.poutput("Vegetables unloaded")
77

78

79
if __name__ == "__main__":
80
    app = ExampleApp()
81
    app.cmdloop()

事件处理器#

以下函数在 CommandSet 生命周期的不同阶段被调用：

on_register - 由 cmd2.Cmd 在注册 CommandSet 的第一步调用。此时此类中定义的命令尚未添加到 CLI 对象。子类可以重写此方法以执行任何需要访问 Cmd 对象的初始化（例如，基于 CLI 状态数据配置命令及其解析器）
on_registered - 由 cmd2.Cmd 在 CommandSet 注册完成且所有命令已添加到 CLI 后调用。子类可以重写此方法以执行与新添加命令相关的自定义步骤（例如，将它们设为禁用状态）
on_unregister - 由 cmd2.Cmd 在注销 CommandSet 的第一步调用。子类可以重写此方法以执行任何需要其命令在 CLI 中注册的清理步骤
on_unregistered - 由 cmd2.Cmd 在 CommandSet 注销完成且所有命令已从 CLI 中移除后调用。子类可以重写此方法以执行剩余的清理步骤

注入子命令#

说明#

使用 @with_argparser 和 @as_subcommand_to 装饰器，可以轻松地为命令定义子命令。这往往会将你的接口推向以对象为中心的接口。例如，假设你有一个管理媒体收藏的工具，你想管理电影或节目。以对象为中心的方式会要求你有 movies 和 shows 等基础命令，每个都有 add、edit、list、delete 子命令。如果你想呈现以操作为中心的命令集，使 add、edit、list 和 delete 成为基础命令，你就必须围绕这些类似的操作组织代码，而不是围绕被管理的类似对象组织代码。

子命令注入允许你将子命令注入到基础命令中，以呈现对用户合理的接口，同时仍然以对开发者更有逻辑意义的结构组织代码。

示例#

此示例是上面动态命令示例的变体。引入了一个 cut 命令作为基础命令，每个 CommandSet 向其添加一个子命令。

1
import argparse
2
import cmd2
3
from cmd2 import CommandSet, with_argparser, with_category
4

5

6
class LoadableFruits(CommandSet["ExampleApp"]):
7
    DEFAULT_CATEGORY = "Fruits"
8

9
    def __init__(self):
10
        super().__init__()
11

12
    def do_apple(self, _: cmd2.Statement):
13
        """Apple Command."""
14
        self._cmd.poutput("Apple")
15

16
    banana_parser = cmd2.Cmd2ArgumentParser()
17
    banana_parser.add_argument("direction", choices=["discs", "lengthwise"])
18

19
    @cmd2.as_subcommand_to("cut", "banana", banana_parser)
20
    def cut_banana(self, ns: argparse.Namespace):
21
        """Cut banana"""
22
        self._cmd.poutput("cutting banana: " + ns.direction)
23

24

25
class LoadableVegetables(CommandSet["ExampleApp"]):
26
    DEFAULT_CATEGORY = "Vegetables"
27

28
    def __init__(self):
29
        super().__init__()
30

31
    def do_arugula(self, _: cmd2.Statement):
32
        """Arugula Command."""
33
        self._cmd.poutput("Arugula")
34

35
    bokchoy_parser = cmd2.Cmd2ArgumentParser()
36
    bokchoy_parser.add_argument("style", choices=["quartered", "diced"])
37

38
    @cmd2.as_subcommand_to("cut", "bokchoy", bokchoy_parser)
39
    def cut_bokchoy(self, _: argparse.Namespace):
40
        """Cut bok choy."""
41
        self._cmd.poutput("Bok Choy")
42

43

44
class ExampleApp(cmd2.Cmd):
45
    """
46
    CommandSets are loaded dynamically at runtime via other commands.
47
    """
48

49
    def __init__(self, *args, **kwargs):
50
        super().__init__(*args, auto_load_commands=False, **kwargs)
51
        self._fruits = LoadableFruits()
52
        self._vegetables = LoadableVegetables()
53

54
    load_parser = cmd2.Cmd2ArgumentParser()
55
    load_parser.add_argument("cmds", choices=["fruits", "vegetables"])
56

57
    @with_argparser(load_parser)
58
    @with_category("Command Loading")
59
    def do_load(self, ns: argparse.Namespace):
60
        """Load Command."""
61
        if ns.cmds == "fruits":
62
            try:
63
                self.register_command_set(self._fruits)
64
                self.poutput("Fruits loaded")
65
            except ValueError:
66
                self.poutput("Fruits already loaded")
67

68
        if ns.cmds == "vegetables":
69
            try:
70
                self.register_command_set(self._vegetables)
71
                self.poutput("Vegetables loaded")
72
            except ValueError:
73
                self.poutput("Vegetables already loaded")
74

75
    @with_argparser(load_parser)
76
    def do_unload(self, ns: argparse.Namespace):
77
        """Unload Command."""
78
        if ns.cmds == "fruits":
79
            self.unregister_command_set(self._fruits)
80
            self.poutput("Fruits unloaded")
81

82
        if ns.cmds == "vegetables":
83
            self.unregister_command_set(self._vegetables)
84
            self.poutput("Vegetables unloaded")
85

86
    cut_parser = cmd2.Cmd2ArgumentParser()
87
    cut_parser.add_subparsers(title="item", help="item to cut", metavar="ITEM", required=True)
88

89
    @with_argparser(cut_parser)
90
    def do_cut(self, ns: argparse.Namespace):
91
        """Cut Command."""
92
        # 调用所选择的子命令处理函数
93
        ns.cmd2_subcommand_func(ns)
94

95

96
if __name__ == "__main__":
97
    app = ExampleApp()
98
    app.cmdloop()

模块化命令#

概述#

功能特性#

定义命令#

命令集#

手动 CommandSet 构造#

类型提示与 self._cmd#

动态命令#

事件处理器#

注入子命令#

说明#

示例#

支持与分享

评论区

Python cmd2：模块化命令详解

模块化命令#

概述#

功能特性#

定义命令#

命令集#

手动 CommandSet 构造#

类型提示与 self._cmd#

动态命令#

事件处理器#

注入子命令#

说明#

示例#

支持与分享

评论区