Python（可选）#

如果 cmd2.Cmd 类在实例化时传入 include_py=True，则可选的 py 命令将可用，并启动一个交互式 Python shell：

1
from cmd2 import Cmd
2
class App(Cmd):
3
    def __init__(self):
4
        Cmd.__init__(self, include_py=True)

Python shell 可以使用 self.pyscript_name 中命名的对象（默认为 app）来运行你应用中的 CLI 命令。这个封装提供了在你的 cmd2 应用中执行命令的能力，同时与完整的 Cmd 实例保持隔离。例如，可以使用 app("command ...") 来运行任何应用命令。

你可以选择通过将 self.self_in_py 设为 True 来启用对应用的完全访问。启用此标志会将 self 添加到 Python 会话中，它是对你的 cmd2 应用的引用。这对调试应用非常有用。

在 Python 会话中创建的任何局部或全局变量不会在 CLI 环境中持久存在。

self.py_locals 中的所有内容在 Python 环境中始终可用。

所有这些参数也可通过 run_pyscript 命令运行的 Python 脚本使用：

• 支持文件系统路径的 Tab 补全
• 能够向调用的脚本传递命令行参数

此命令提供了比简单文本文件脚本更复杂和强大的脚本能力。Python 脚本可以包含条件控制流逻辑。参阅 python_scripting.py 和 conditional.py 脚本了解如何在自己的应用中实现这一点。参阅脚本了解 cmd2 应用中两种脚本方法的说明。

以下是使用 run_pyscript 的简单示例以及 arg_printer 脚本：

1
(Cmd) run_pyscript examples/scripts/arg_printer.py foo bar baz
2
Running Python script 'arg_printer.py' which was called with 3 arguments
3
arg 1: 'foo'
4
arg 2: 'bar'
5
arg 3: 'baz'

IPython（可选）#

如果系统中安装了 IPython，并且 cmd2.Cmd 类在实例化时传入 include_ipy=True，则可选的 ipy 命令将启动一个交互式 IPython shell：

1
from cmd2 import Cmd
2
class App(Cmd):
3
    def __init__(self):
4
        Cmd.__init__(self, include_ipy=True)

ipy 命令进入一个交互式 IPython 会话。与交互式 Python 会话类似，如果 self.self_in_py 为 True，此 shell 可以通过 self 访问你的应用实例，并且通过 self 对应用所做的任何更改都将持久存在。但是，在 ipy shell 中创建的任何局部或全局变量不会在 CLI 环境中持久存在。

同样，与交互式 Python 会话一样，ipy shell 可以访问 self.py_locals 的内容，并可以使用 app 对象（或你的自定义名称）回调应用。

IPython 提供了许多优势，包括：

• 全面的对象自省
• 使用 ? 获取对象帮助
• 可扩展的 Tab 补全，默认支持 Python 变量和关键字的补全
• 优秀的内置 ipdb 调试器

对象自省和 Tab 补全使 IPython 在调试以及交互式实验和数据分析方面特别高效。

普通输出#

poutput 方法类似于 Python 内置的 print 函数。poutput 添加了一些便利功能：

1. 由于用户可以将输出管道传递给 shell 命令，它会捕获 BrokenPipeError 并将 self.broken_pipe_warning 的内容输出到 stderr。self.broken_pipe_warning 默认为空字符串，所以此方法只会吞掉异常。如果你想显示错误消息，请在初始化 cmd2.Cmd 时将其放入 self.broken_pipe_warning 中。
2. 它会检查并遵守 allow_style 设置。详见下方彩色输出。
3. 它允许打印任意 rich 可渲染对象，可以实现视觉上非常复杂的效果。

以下是一个展示此方法用法的简单命令：

1
def do_echo(self, args):
2
    """A simple command showing how poutput() works"""
3
    self.poutput(args)

错误消息#

当程序中发生错误时，你可以通过调用 perror 方法在 sys.stderr 上显示它。默认情况下，此方法会将 Cmd2Style.ERROR 应用于输出。

警告消息#

pwarning 与 cmd2.Cmd.perror 类似，但会将 Cmd2Style.WARNING 应用于输出。

反馈信息#

你可能需要向用户显示不属于生成输出的信息。这可能是调试信息或长时间运行命令的进度信息。它不是输出，不是错误消息，而是状态信息。如果你使用 Timing 设置，命令运行耗时的输出将以无样式的文本输出到 stderr。你可以通过将 style=None 传递给 perror 方法来产生此类输出。

如果 quiet 设置为 True，则调用 cmd2.Cmd.pfeedback 不会产生任何输出。如果 quiet 为 False，pfeedback 方法将输出发送到 stdout。因此，pfeedback 适用于你希望在 quiet 为 True 时能够静音的非必要输出。

异常#

如果你的应用捕获了异常并希望向用户显示异常信息，pexcept 方法可以提供帮助。默认行为是只显示异常中包含的消息。但是，如果 debug 设置为 True，则会显示整个堆栈跟踪。

分页输出#

如果你知道将要生成大量输出，你可能希望以用户可以前后滚动的方式显示它。如果你将所有要显示的输出传递给 ppaged 的单次调用，它将被管道传递给操作系统适当的 shell 命令来分页输出。在 Windows 上，输出被管道传递给 more；在 macOS 和 Linux 等类 Unix 操作系统上，输出被管道传递给 less。

彩色输出#

你可以在输出中添加自己的 ANSI 转义序列来指示终端更改前景色和背景色。

cmd2 提供了许多便捷函数和类来为文本添加颜色和其他样式。这些都基于 rich，文档在以下章节中：

• cmd2.colors
• cmd2.rich_utils
• cmd2.string_utils

color.py 示例演示了 cmd2 应用中所有可用的颜色。

文本对齐#

如果你想生成在指定宽度或终端宽度内左对齐、居中或右对齐的输出，以下函数可以提供帮助：

• cmd2.string_utils.align_left
• cmd2.string_utils.align_center
• cmd2.string_utils.align_right

这些函数与 Python 的字符串对齐函数不同，它们支持显示宽度大于 1 的字符。此外，ANSI 样式序列会被安全忽略，不计入显示宽度。这意味着支持彩色文本。如果文本包含换行符，则每行独立对齐。

多列输出#

在生成多列输出时，你通常需要计算每个项目的宽度以便用空格适当填充。然而，有些 Unicode 字符占用 2 个单元格，而另一些占用 0 个。更复杂的是，你可能在输出中包含了 ANSI 转义序列来在终端上生成颜色。

cmd2.string_utils.str_width 函数解决了这两个问题。给它传递一个字符串，无论它包含哪些 Unicode 字符和 ANSI 文本样式转义序列，它都会告诉你该字符串在屏幕上打印时会占用多少个字符。

获取帮助#

cmd2 使终端用户可以通过内置的 help 命令轻松获取帮助。单独的 help 命令显示可用命令的列表：

1
(Cmd) help
2

3
Documented Commands
4
 alias  help     ipy    py    run_pyscript  set    shortcuts
5
 edit   history  macro  quit  run_script    shell

help 命令也可用于提供特定命令的详细帮助：

1
(Cmd) help quit
2
Usage: quit [-h]
3

4
Exit this application.
5

6
Optional Arguments:
7
  -h, --help  show this help message and exit

提供帮助#

cmd2 使 cmd2 应用的开发者可以轻松提供帮助。默认情况下，命令的帮助是定义命令的 do_* 方法的文档字符串——例如，对于命令 foo，该命令通过定义 do_foo 方法实现，该方法的文档字符串就是帮助内容。

对于使用 @with_argparser 装饰器解析参数的命令，帮助由 argparse 提供。详见帮助消息。

偶尔可能会出现不寻常的情况，提供静态帮助文本不够好，你希望在命令的帮助文本中提供动态信息。为满足此需求，如果定义了与 do_foo 方法匹配的 help_foo 方法，则该方法将用于提供命令 foo 的帮助。此动态帮助仅适用于不使用 argparse 装饰器的命令，因为我们不希望 help cmd 和 cmd -h 的输出不同。

命令分类#

在 cmd2 中，help 命令将其输出组织为分类。每个命令属于一个分类，显示由 DEFAULT_CATEGORY 类变量驱动。

有 3 种指定命令分类的方法：

1. 使用 DEFAULT_CATEGORY 类变量（自动）
2. 使用 @with_category 装饰器（手动）
3. 使用 categorize() 函数（手动）

1
class MyApp(cmd2.Cmd):
2
    # All commands defined in this class will be grouped here
3
    DEFAULT_CATEGORY = 'Application Commands'
4

5
    def do_echo(self, arg):
6
        """Echo command"""
7
        self.poutput(arg)

1
class Plugin(cmd2.CommandSet):
2
    DEFAULT_CATEGORY = 'Plugin Commands'
3

4
    def do_plugin_cmd(self, _):
5
        """Plugin command"""
6
        self._cmd.poutput('Plugin')

1
class MyApp(cmd2.Cmd):
2
    # Rename the framework's built-in category
3
    cmd2.Cmd.DEFAULT_CATEGORY = 'Shell Commands'
4

5
    # Set the category for your own commands
6
    DEFAULT_CATEGORY = 'Application Commands'

1
@with_category('Connecting')
2
def do_which(self, _):
3
    """Which command"""
4
    self.poutput('Which')

1
def do_connect(self, _):
2
    """Connect command"""
3
    self.poutput('Connect')
4

5
# Tag the above command functions under the category Connecting
6
categorize(do_connect, CMD_CAT_CONNECTING)

1
def do_undeploy(self, _):
2
    """Undeploy command"""
3
    self.poutput('Undeploy')
4

5
def do_stop(self, _):
6
    """Stop command"""
7
    self.poutput('Stop')
8

9
def do_findleakers(self, _):
10
    """Find Leakers command"""
11
    self.poutput('Find Leakers')
12

13
# Tag the above command functions under the category Application Management
14
categorize((do_undeploy,
15
            do_stop,
16
            do_findleakers), CMD_CAT_APP_MGMT)

1
Application Management
2
─────────────────────────────────────
3
Name          Description
4
─────────────────────────────────────
5
deploy        Deploy command.
6
expire        Expire command.
7
findleakers   Find Leakers command.
8
list          List command.
9
redeploy      Redeploy command.
10
restart       Restart command.
11
sessions      Sessions command.
12
start         Start command.
13
stop          Stop command.
14
undeploy      Undeploy command.
15

16

17
Command Management
18
─────────────────────────────────────────────────────────────────
19
Name               Description
20
─────────────────────────────────────────────────────────────────
21
disable_commands   Disable the Application Management commands.
22
enable_commands    Enable the Application Management commands.
23

24

25
Connecting
26
────────────────────────────
27
Name      Description
28
────────────────────────────
29
connect   Connect command.
30
which     Which command.
31

32

33
Server Information
34
─────────────────────────────────────────────────────────────────────────────────────────────────
35
Name                  Description
36
─────────────────────────────────────────────────────────────────────────────────────────────────
37
resources             Resources command.
38
serverinfo            Server Info command.
39
sslconnectorciphers   SSL Connector Ciphers command is an example of a command that contains
40
                    multiple lines of help information for the user. Each line of help in a
41
                    contiguous set of lines will be printed and aligned in the verbose output
42
                    provided with 'help --verbose'.
43
status                Status command.
44
thread_dump           Thread Dump command.
45
vminfo                VM Info command.
46

47

48
Other
49
─────────────────────────────────────────────────────────────────────────────────────────
50
Name           Description
51
─────────────────────────────────────────────────────────────────────────────────────────
52
alias          Manage aliases.
53
config         Config command.
54
edit           Run a text editor and optionally open a file with it.
55
help           List available commands or provide detailed help for a specific command.
56
history        View, run, edit, save, or clear previously entered commands.
57
macro          Manage macros.
58
quit           Exit this application.
59
run_pyscript   Run Python script within this application's environment.
60
run_script     Run text script.
61
set            Set a settable parameter or show current settings of parameters.
62
shell          Execute a command as if at the OS prompt.
63
shortcuts      List available shortcuts.
64
version        Version command.