基本用法#

没有默认值的参数成为位置参数。有默认值的参数成为 --option 标志。仅限关键字的参数（在 * 之后）始终成为选项，若没有默认值则成为必填选项。

参数名中的下划线会在生成的标志中转换为短横线，因此 dry_run 会变成 --dry-run。你在函数体中读取的 Python 标识符仍保留下划线形式（args.dry_run）。若要关闭这一转换，可通过 Option("--my_flag", ...) 传入显式名称。

1
from cmd2.annotated import with_annotated
2

3

4
class MyApp(cmd2.Cmd):
5
    @with_annotated
6
    def do_greet(self, name: str, count: int = 1, loud: bool = False):
7
        """Greet someone."""
8
        for _ in range(count):
9
            msg = f"Hello {name}"
10
            self.poutput(msg.upper() if loud else msg)

命令 greet Alice --count 3 --loud 会解析出 name="Alice"、count=3、loud=True，并把它们作为关键字参数传入。

注解如何映射到 argparse#

该装饰器把 Python 类型注解转换为 add_argument() 调用：

当集合类型与 @with_annotated 一起使用时，解析出的值按以下类型传给命令函数：

• list[T] 传为 list
• set[T] 传为 set
• frozenset[T] 传为 frozenset
• tuple[T, ...] 传为 tuple

不支持的模式会抛出 TypeError，包括：

• 含有多个非 None 成员的联合类型，如 str | int（除非每个成员都是 Enum 子类，例如 EnumA | EnumB，此时按顺序尝试每个成员的转换器）
• 混合类型的元组，如 tuple[int, str]
• Annotated[T, meta] | None；应改写为 Annotated[T | None, meta]
• Annotated[T, Argument(nargs=N)]，其中 N 为 '*'、'+' 或 >= 1 的整数，而 T 不是集合类型。会产生值列表的 nargs 需要集合注解，如 list[T] 或 tuple[T, ...]
• 可选的固定元数位置参数，如 Annotated[tuple[int, int], Argument()] = (1, 2)、Annotated[tuple[int, int] | None, Argument()]，或任何带默认值或 | None 的位置参数 Argument(nargs=N)。argparse 无法让固定元数的位置参数变为可选（没有表示”缺席或恰好 N 个词法单元”的 nargs），因此请改用可变元数类型如 tuple[T, ...]、去掉默认值，或把它改成选项（给出默认值但不带 Argument()）
• Annotated[tuple[T, T], Argument(nargs=N)]，其中 N 与元组声明的元素数量不一致。元组类型已经固定了 nargs，用户元数据无法更改它

参数名 dest 和 subcommand 是保留字，不能用作注解参数名。cmd2_statement 接收解析后的 [cmd2.Statement][] 对象，cmd2_subcommand_func（仅在用 @with_annotated(base_command=True) 装饰的命令上有效）接收子命令处理函数。

注解元数据#

若需更精细的控制，可使用 typing.Annotated 搭配 [Argument][cmd2.annotated.Argument] 或 [Option][cmd2.annotated.Option] 元数据：

1
from typing import Annotated
2
from cmd2.annotated import Argument, Option, with_annotated
3

4

5
class MyApp(cmd2.Cmd):
6
    def sport_choices(self) -> cmd2.Choices:
7
        return cmd2.Choices.from_values(["football", "basketball"])
8

9
    @with_annotated
10
    def do_play(
11
        self,
12
        sport: Annotated[
13
            str,
14
            Argument(
15
                choices_provider=sport_choices,
16
                help_text="Sport to play",
17
            ),
18
        ],
19
        venue: Annotated[
20
            str,
21
            Option(
22
                "--venue",
23
                "-v",
24
                help_text="Where to play",
25
                completer=cmd2.Cmd.path_complete,
26
            ),
27
        ] = "home",
28
    ):
29
        self.poutput(f"Playing {sport} at {venue}")

Argument 和 Option 都接受与 add_argument() 相同的 cmd2 专属字段：choices、choices_provider、completer、table_columns、suppress_tab_hint、metavar、nargs 和 help_text。它们还接受用于自定义转换的 converter / preprocess，以及用于枚举别名的 allow_unknown_entry。

Option 额外接受 action、required，以及用于自定义标志字符串的位置 *names（例如 Option("--color", "-c")）。

1
import enum
2
from typing import Annotated
3
from cmd2.annotated import Argument, with_annotated
4

5

6
class Color(enum.Enum):
7
    red = "red"
8
    green = "green"
9
    blue = "blue"
10

11
    @classmethod
12
    def _missing_(cls, value):
13
        # 把特殊关键字映射到真实成员；返回 None 则拒绝
14
        return cls.red if str(value).lower() == "auto" else None
15

16

17
class MyApp(cmd2.Cmd):
18
    @with_annotated
19
    def do_theme(self, choice: Annotated[Color, Argument(allow_unknown_entry=True)]) -> None:
20
        self.poutput(f"theme set to {choice.value}")

1
@with_annotated
2
def do_pick(self, choice: Suit | Rank) -> None:
3
    if isinstance(choice, Suit):
4
        self.poutput(f"suit {choice.name}")
5
    else:
6
        self.poutput(f"rank {choice.name}")

1
class UpperAction(argparse.Action):
2
    def __call__(self, parser, namespace, values, option_string=None):
3
        setattr(namespace, self.dest, values.upper())
4

5

6
@with_annotated
7
def do_shout(self, name: Annotated[str, Option("--name", action=UpperAction)] = ""):
8
    self.poutput(name)

1
# 签名默认值
2
def do_x(self, name: Annotated[str, Option("--name")] = "HI"): ...
3

4

5
# 元数据默认值（行为相同）
6
def do_x(self, name: Annotated[str, Option("--name", default="HI")]): ...

1
import datetime
2
from typing import Annotated
3
from cmd2.annotated import Argument, Option, with_annotated
4

5

6
def parse_size(value: str) -> int:
7
    """解析带可选 K/M/G 后缀的整数。"""
8
    multiplier = {"K": 1_000, "M": 1_000_000, "G": 1_000_000_000}.get(value[-1:].upper(), 1)
9
    return int(value[:-1] if multiplier != 1 else value) * multiplier
10

11

12
class MyApp(cmd2.Cmd):
13
    @with_annotated
14
    def do_alloc(self, size: Annotated[int, Argument(converter=parse_size)]) -> None:
15
        self.poutput(f"Allocating {size} bytes")  # `alloc 64K` -> 64000
16

17
    @with_annotated
18
    def do_at(self, when: Annotated[datetime.datetime, Option("--when", converter=datetime.datetime.fromisoformat)]):
19
        self.poutput(when.isoformat())  # `datetime` 没有推断出的转换器，converter= 使其合法

1
from typing import Annotated, Any
2

3

4
def parse_intset(value: str) -> set[int]:
5
    return {int(piece) for piece in value.split(",")}
6

7

8
@with_annotated
9
def do_select(self, idx: Annotated[Any, Option("--idx", converter=parse_intset)]) -> None:
10
    self.poutput(sorted(idx))  # `select --idx 1,3,5` -> [1, 3, 5]

1
import os
2
from typing import Annotated
3
from cmd2.annotated import Argument, with_annotated
4

5

6
class MyApp(cmd2.Cmd):
7
    @with_annotated
8
    def do_tag(self, color: Annotated[Color, Argument(preprocess=str.lower)]) -> None:
9
        self.poutput(color.value)  # `tag RED` 可用，`tag <TAB>` 仍会列出颜色
10

11
    @with_annotated
12
    def do_open(self, path: Annotated[Path, Argument(preprocess=os.path.expanduser)]) -> None:
13
        self.poutput(path)  # `open ~/file` 会展开，路径补全仍可用

装饰器选项#

@with_annotated 目前支持：

• ns_provider —— 在解析前预填充命名空间，与 @with_argparser 对应
• preserve_quotes —— 为 True 时保留参数中的引号
• with_unknown_args —— 为 True 时，无法识别的参数通过 _unknown 传入
• subcommand_to —— 把该函数注册为某个父命令下的注解式子命令
• base_command —— 创建基础命令，其解析器同时添加子解析器并暴露 cmd2_subcommand_func。cmd2_subcommand_func 参数只在用 base_command=True 装饰的命令上有效；在别处声明会抛出 TypeError
• subcommand_required —— 是否必须提供子命令（仅在 base_command=True 时有效，默认 True）
• subcommand_metavar —— 子命令组显示的 metavar（仅在 base_command=True 时有效，默认 "SUBCOMMAND"）
• subcommand_title —— 子命令 --help 小节的标题（仅在 base_command=True 时有效）。设置它或 subcommand_description 会把子命令从位置参数小节移到独立小节，与 argparse 中的行为一致
• subcommand_description —— 子命令 --help 小节的描述（仅在 base_command=True 时有效）。只提供它而不提供 subcommand_title 时，该小节使用 argparse 的默认标题 subcommands
• help —— 注解式子命令的帮助文本（仅在配合 subcommand_to 时有效）
• aliases —— 注解式子命令的别名（仅在配合 subcommand_to 时有效）
• deprecated —— 在 --help 中把该子命令标记为已弃用（仅在配合 subcommand_to 时有效）
• groups —— 把参数名分配给参数组的 Group 实例
• mutually_exclusive_groups —— 互斥参数的 Group 实例
• parser_class —— 自定义解析器类（默认为配置的默认值）
• **parser_kwargs —— 其他所有 Cmd2ArgumentParser 构造关键字参数，通过 PEP 692 [Unpack[Cmd2ParserKwargs]][cmd2.annotated.Cmd2ParserKwargs] 转发。完整列表及 description / prog 的特例见下文解析器定制

1
@with_annotated(with_unknown_args=True)
2
def do_rawish(self, name: str, _unknown: list[str] | None = None):
3
    self.poutput((name, _unknown))

解析器定制#

每个 Cmd2ArgumentParser 构造关键字参数都通过 PEP 692 [Unpack[Cmd2ParserKwargs]][cmd2.annotated.Cmd2ParserKwargs] 直接流经 @with_annotated 和 build_parser_from_function。[Cmd2ParserKwargs][cmd2.annotated.Cmd2ParserKwargs] 这个 TypedDict 是被转发关键字参数的唯一权威来源，并为类型检查器/IDE 在装饰器调用点提供自动补全：给 Cmd2ArgumentParser 新增构造关键字参数只需在 Cmd2ParserKwargs 上添加对应字段，注解式装饰器就会自动识别。

被转发的关键字参数包括 description、epilog、prog、usage、parents、argument_default、prefix_chars、fromfile_prefix_chars、conflict_handler、add_help、allow_abbrev、exit_on_error、formatter_class、completer_class，以及 Python ≥ 3.14 上的 suggest_on_error / color。其中两个在裸透传之上叠加了额外行为：

• description —— 省略时会用函数的 docstring 填充（详见下文）；传入显式值可覆盖
• prog —— 设置了 subcommand_to 时会被拒绝；cmd2 的子命令机制会根据父命令层级重写 prog，这里的任何值都会被静默覆盖

parser_class 保持为独立的显式关键字参数，因为它选择的是类本身，而不是传给它的值。参数组通过 [Group][cmd2.annotated.Group] 声明；传入 title 和 description 可得到带标题的帮助小节（省略则为无标题分组）：

1
from cmd2.annotated import Group, with_annotated
2

3

4
class App(cmd2.Cmd):
5
    @with_annotated(
6
        description="Open a network connection.",
7
        epilog="Example: connect example.com --port 2222",
8
        groups=(Group("host", "port", title="connection", description="where to connect"),),
9
    )
10
    def do_connect(self, host: str, port: int = 22, verbose: bool = False):
11
        self.poutput(f"connecting to {host}:{port}")

若省略 description，函数 docstring 的第一段（到第一个空行为止的所有内容）会被用作解析器描述；后续段落会被丢弃，以免 rst 字段指令（如 :param name:）泄漏进 --help。传 description="" 可关闭自动填充，传 description="..." 可覆盖它。

1
@with_annotated
2
def do_greet(self, name: str):
3
    """Greet someone by name.
4

5
    :param name: who to greet
6
    """
7
    self.poutput(f"hello {name}")
8

9

10
# parser.description == "Greet someone by name."

mutually_exclusive_groups 同样接受 Group 实例。传 Group(..., required=True) 可让互斥组本身成为必填——argparse 会强制要求其成员中恰好有一个被提供。普通（非互斥）Group 上的 required=True 会被拒绝，因为 add_argument_group 没有 required 标志。

1
@with_annotated(
2
    mutually_exclusive_groups=(Group("verbose", "quiet", required=True),),
3
)
4
def do_run(self, verbose: bool = False, quiet: bool = False): ...

给 mutually_exclusive_groups 的 Group 加上 title/description，可以把它渲染为带标题的帮助小节——这是 argparse 唯一支持的嵌套形式：互斥组位于参数组内部。你只需声明一次，无需配对的 groups= 条目。对每个 bool 成员使用 Option(action="store_true")，可让选项显示为 [--json | --csv]，而不是展开成 --json/--no-json 和 --csv/--no-csv：

1
@with_annotated(
2
    mutually_exclusive_groups=(Group("json", "csv", title="output", description="how to write results"),),
3
)
4
def do_render(
5
    self,
6
    json: Annotated[bool, Option(action="store_true")] = False,
7
    csv: Annotated[bool, Option(action="store_true")] = False,
8
): ...

若要把非互斥参数放进同一小节，请用包含它们全部的 groups= 条目声明，并且不要给互斥组加标题；argparse 会把互斥组嵌套在该组内。在两处都声明该小节、互斥组只有部分成员出现在 groups= 条目中、或它横跨两个条目，都会抛出 ValueError。另外三种嵌套形式（参数组嵌套在另一个组或互斥组内、互斥组嵌套在互斥组内）在 Python 3.14 的 argparse 中已移除，此处也无法表达。

Group 的成员命名的是命令行参数。对于普通参数，参数即参数本身，因此名称两边相同。ArgumentBlock 参数则不同：它会展开为每个字段一个参数（字段名 == 参数名），因此你要命名的是它的字段而非整个块：

1
@dataclass
2
class Conn(ArgumentBlock):
3
    host: Annotated[str, Option("--host")] = "localhost"
4
    port: Annotated[int, Option("--port")] = 8080
5

6

7
@with_annotated(groups=(Group("host", "port", title="connection"),))
8
def do_connect(self, conn: Conn) -> None: ...

给块参数本身命名（Group("conn")）会抛出 ValueError：该参数已被展开，没有属于自己的参数。逐个命名块的字段还有一个好处：你可以指明哪些字段是互斥选项——把 Group("json", "csv") 放进 mutually_exclusive_groups，就只有这两个互相排斥，而不是它们所在块的每个字段都互相排斥。

分组规格的形状规则——成员重复出现、一个成员被分到两个组、普通组上的 required=True，以及上文的互斥嵌套规则——都在装饰器运行时校验，因此形状不合法的分组会在类定义时抛出 ValueError，而不是等到第一次使用命令时。这些检查只读取 Group 规格，不读取签名或类型注解，因此前向引用的注解仍能正常装饰。

依赖成员身份的规则（例如每个成员都指向真实参数、互斥组成员必须可省略——即有默认值或是 T | None）在构建解析器时才触发，因为不解析类型注解就无法知道块的字段名。

parents= 与 argparse 标准的 parents 机制一致，用于在多个解析器间共享参数定义。argument_default=argparse.SUPPRESS 不受支持并抛出 TypeError。它会把缺席的参数从解析出的命名空间中移除，但 @with_annotated 是按函数签名构建调用的，因此每个声明的参数在调用时都必须存在；参数从命名空间中消失在这里永远不可能合法（与逐参数的 default=argparse.SUPPRESS 被拒绝相对应）。其他任何 argument_default 值都会原样转发给解析器。

其余 argparse 关键字参数覆盖较少见的需求，但都原样接入：

• prefix_chars="+-" 接受以 + 开头的选项（如 +verbose）；配合显式的 Option("+verbose") 来声明此类标志
• fromfile_prefix_chars="@" 让用户写 mycmd @args.txt，把文件内容作为参数拼接进来
• conflict_handler="resolve" 让父解析器的选项可以在本地重新定义而不报错——配合 parents= 覆盖继承的标志时很有用
• add_help=False 移除自动添加的 -h/--help 动作（cmd2 的标准解析器默认保留它）
• allow_abbrev=False 要求用户输入完整的长选项名（--verbose 不能写成 --verb）
• exit_on_error=False 让解析失败抛出 argparse.ArgumentError 而不是调用 sys.exit——在把解析器嵌入其他流程时很有用

注解式子命令#

@with_annotated 还能无需手动构造子解析器就构建类型化的子命令树。

1
@with_annotated(base_command=True)
2
def do_manage(self, *, cmd2_subcommand_func):
3
    if cmd2_subcommand_func:
4
        cmd2_subcommand_func()
5

6

7
@with_annotated(subcommand_to="manage", help="list projects")
8
def manage_list(self):
9
    self.poutput("listing")

对于嵌套子命令，subcommand_to 可以是空格分隔的，例如 subcommand_to="manage project"。中间层级也必须声明为创建自己的子解析器的子命令：

1
@with_annotated(subcommand_to="manage", base_command=True, help="manage projects")
2
def manage_project(self, *, cmd2_subcommand_func):
3
    if cmd2_subcommand_func:
4
        cmd2_subcommand_func()
5

6

7
@with_annotated(subcommand_to="manage project", help="add a project")
8
def manage_project_add(self, name: str):
9
    self.poutput(f"added {name}")

参数块#

当多个命令共享同一组参数时，可复用的参数块（argument block）能消除重复。在 @dataclass 上继承 cmd2.ArgumentBlock 特性类，并用它注解某个参数。每个字段成为一个扁平的命令行参数（字段名 == 参数名），解析出的值会被重建成 dataclass 实例传给命令：

1
from dataclasses import dataclass
2
from typing import Annotated
3
from pathlib import Path
4

5
import cmd2
6
from cmd2 import with_annotated
7
from cmd2.annotated import Option
8

9

10
@dataclass
11
class CommonArgs(cmd2.ArgumentBlock):
12
    verbose: Annotated[bool, Option("-v", "--verbose")] = False
13
    output: Annotated[Path | None, Option("--output")] = None
14

15

16
class App(cmd2.Cmd):
17
    @with_annotated
18
    def do_build(self, target: str, common: CommonArgs):
19
        self.poutput(f"{target} verbose={common.verbose} output={common.output}")

build app --verbose --output /tmp/x 会重建出 CommonArgs(verbose=True, output=Path("/tmp/x")) 并作为 common 传入。块参数本身永远不是参数，只有它的字段才是。

字段携带常规的 Annotated[T, Option(...)] / Annotated[T, Argument(...)] 元数据，其行为与同形状的顶层参数完全一致。dataclass 是默认值的唯一权威来源：带默认值（default 或 default_factory）的字段在调用时由 dataclass 构造器填充，因此 default_factory 每次调用都会产生新值，__post_init__ 也会运行。没有默认值的字段成为必填参数。

继承是复用机制：块的子类本身也是块，因此可以在共享基块的基础上按命令扩展，而无需重复其字段。

1
@dataclass
2
class TracedArgs(CommonArgs):
3
    trace: bool = False  # do_test 会得到 verbose、output 和 trace

几条规则保证块的语义无歧义：

• 触发条件是 ArgumentBlock 特性类，而非”是 dataclass”。普通 @dataclass 不受影响，仍可作为普通的单值使用（例如通过 Argument(converter=...)）
• 块必须是普通参数的裸注解。把它包进 Annotated/Optional/联合类型，或用作 *args/**kwargs，都会抛出清晰的错误
• 由于字段是扁平展开的，字段名与其他参数或其他块的字段冲突时，会在构建解析器时报错，而不是静默共享同一个目标名
• 与块参数同名的字段（例如接收为 opts: Opts 的块上的 opts）会被拒绝：字段的扁平参数与接收块实例的参数会共享同一个目标名
• 字段的默认值必须写在 dataclass 字段上（= value 或 = field(default_factory=...)），不能写在 Option/Argument 元数据中，也不能通过动作默认值（append/count）提供。默认值由 dataclass 掌管以保证每次调用得到新值，因此在没有 dataclass 默认值的字段上提供元数据或动作默认值会被拒绝
• 类型本身是块的字段不会被展开（不递归），会作为不支持的类型被拒绝

1
@dataclass
2
class SharedOpts(cmd2.ArgumentBlock):
3
    verbose: Annotated[bool, Option("-v", "--verbose")] = False
4
    level: Annotated[int, Option("--level")] = 1
5

6

7
class App(cmd2.Cmd):
8
    @with_annotated(base_command=True)
9
    def do_root(self, cmd2_subcommand_func, cmd2_base_args: SharedOpts):
10
        if cmd2_subcommand_func:
11
            cmd2_subcommand_func()
12

13
    @with_annotated(subcommand_to="root", help="show the inherited block")
14
    def root_show(self, cmd2_parent_args: SharedOpts):
15
        self.poutput(f"verbose={cmd2_parent_args.verbose} level={cmd2_parent_args.level}")

1
@dataclass
2
class RunOpts(cmd2.ArgumentBlock):
3
    retries: Annotated[int, Option("--retries")] = 0
4

5

6
class App(cmd2.Cmd):
7
    @with_annotated(base_command=True)
8
    def do_root(self, cmd2_subcommand_func, cmd2_base_args: SharedOpts):
9
        if cmd2_subcommand_func:
10
            cmd2_subcommand_func()
11

12
    @with_annotated(subcommand_to="root")
13
    def root_run(self, name: str, cmd2_parent_args: SharedOpts, run: RunOpts):
14
        # --verbose/--level 来自 `root`；--retries 是本子命令自己的标志
15
        self.poutput(f"run {name} verbose={cmd2_parent_args.verbose} retries={run.retries}")

底层解析器构建#

[cmd2.annotated.build_parser_from_function][cmd2.annotated.build_parser_from_function] 可以直接从函数构建解析器，而无需注册命令。它接受与 @with_annotated 相同的 groups、mutually_exclusive_groups、parser_class 和转发的 [Unpack[Cmd2ParserKwargs]][cmd2.annotated.Cmd2ParserKwargs]。与装饰器一样，它会跳过第一个参数作为方法接收者（self/cls）。

1
from cmd2.annotated import build_parser_from_function
2

3

4
def greet(self, name: str, count: int = 1):
5
    """Greet someone."""
6

7

8
parser = build_parser_from_function(greet)
9
namespace = parser.parse_args(["Alice", "--count", "3"])
10
# namespace.name == "Alice", namespace.count == 3

基于类型的自动补全#

使用 @with_annotated 时，标注为 Path 或 Enum 的参数无需显式的 choices_provider 或 completer 即可获得自动补全。

具体来说：

• Path（或任何 Path 子类）触发文件系统路径补全
• MyEnum（任何 enum.Enum 子类）触发基于枚举成员值的补全

使用 @with_argparser 时，若需要补全行为，请显式提供 choices、choices_provider 或 completer。

稳定性与反馈#

由于该功能是实验性的：

• 边缘情况的行为（混合类型元组、深层嵌套的 Annotated、冲突的元数据）可能发生变化
• 诊断性错误消息的措辞可能调整
• 支持的类型注解集合可能扩充或缩减

如果你依赖 @with_annotated，请通过 issue tracker 分享反馈和边缘案例，以便在该功能结束实验性状态之前把行为固定下来。

API 参考：cmd2.annotated#

官方文档中的 API 参考页由 mkdocstrings 从 cmd2.annotated 模块的 docstring 自动生成（源文件仅包含 ::: cmd2.annotated 指令）。其主要公开成员如下：

• [cmd2.annotated.with_annotated][cmd2.with_annotated] —— 根据类型注解构建解析器的命令装饰器
• [cmd2.annotated.Argument][] —— 位置参数的 typing.Annotated 元数据类
• [cmd2.annotated.Option][] —— 选项参数的 typing.Annotated 元数据类
• [cmd2.annotated.Group][] —— 用于参数组与互斥组的分组规格
• [cmd2.annotated.ArgumentBlock][] —— 参数块所继承的 dataclass 特性类
• [cmd2.annotated.build_parser_from_function][] —— 不注册命令、直接从函数构建解析器
• [cmd2.annotated.Cmd2ParserKwargs][] —— 转发给 Cmd2ArgumentParser 构造器的关键字参数 TypedDict

各成员的完整签名与逐参数说明请参阅 cmd2 官方 API 文档或源码 docstring。

自定义补全菜单颜色#

cmd2 利用 prompt-toolkit 实现其 Tab 补全菜单。你可以通过在 cmd2 主题中重写以下样式来自定义补全菜单的颜色：

• Cmd2Style.COMPLETION_MENU - 整个补全菜单容器的基础样式（设置背景）
• Cmd2Style.COMPLETION_MENU_COMPLETION - 单个未选中补全项的样式
• Cmd2Style.COMPLETION_MENU_CURRENT - 当前选中补全项的样式
• Cmd2Style.COMPLETION_MENU_META - 补全项旁边显示的”元信息”样式
• Cmd2Style.COMPLETION_MENU_META_CURRENT - 当前选中项的元信息样式

默认情况下，当前选中的补全项和元数据使用绿色背景上的黑色文本来提供对比度。所有其他项默认保持 prompt-toolkit 的默认值。然而，cmd2 应用作者可以自由地自定义这些样式，以匹配所需的视觉风格和/或品牌。

示例#

参阅 rich_theme.py 了解为 cmd2 应用配置自定义主题的简单示例。

混入类基础#

在 Python 中，混入（mixin）是一种通过多重继承向其他类提供特定功能集合的类。混入不打算被单独实例化；相反，它们的作用是将行为”混合”或组合到一个基类中，而不建立僵化的”是一个（is-a）“关系。

关于混入类的更多信息，我们推荐这篇 Real Python 文章：What Are Mixin Classes in Python?

cmd2 混入类概览#

如果你有一组可复用的行为，希望应用于多个不同的 cmd2 应用，那么创建一个混入类来封装这些行为是个好主意。这是依赖多重继承来扩展 cmd2 的一种方式。它快速而简单，但有一些潜在的陷阱需要了解，以便你知道如何正确使用。

mixins.py 示例展示了如何为 cmd2 应用开发混入类。过去我们称这些为”插件（Plugins）“，但回想起来这可能不是最好的名字。它们本质上是混入类，为继承自 [cmd2.Cmd][] 的类添加一些额外功能。

使用本模板#

本文件提供了一个非常基础的模板，说明你如何创建自己的 cmd2 混入类，将可复用的行为封装起来，通过多重继承应用于多个 cmd2 应用。

命名#

如果你决定将混入发布为 Python 包，应考虑给项目名称加上 cmd2- 前缀。采用这种方式后，项目内部应有一个带 cmd2_ 前缀的包。

添加功能#

有许多方式可以通过混入为 cmd2 添加功能。混入是一个封装并将代码注入另一个类的类。在 cmd2 项目中使用混入的开发者，会将混入的代码注入到他们继承 [cmd2.Cmd][] 的子类中。

1
class MyMixin:
2
    def __init__(self, *args, **kwargs):
3
        # 此处的代码在 cmd2.Cmd 初始化之前运行
4
        super().__init__(*args, **kwargs)
5
        # 此处的代码在 cmd2.Cmd 初始化之后运行

1
import cmd2
2

3

4
class Example(MyMixin, cmd2.Cmd):
5
    """展示如何使用混入类的 cmd2 应用类。"""
6

7
    def __init__(self, *args, **kwargs):
8
        # 此处的代码在 cmd2.Cmd 或
9
        # 任何混入初始化之前运行
10
        super().__init__(*args, **kwargs)
11
        # 此处的代码在 cmd2.Cmd 和
12
        # 所有混入初始化之后运行

1
class MyMixin:
2
    def do_say(self, statement):
3
        """简单的 say 命令"""
4
        self.poutput(statement)

1
class MyMixin:
2
    def __init__(self, *args, **kwargs):
3
        # 此处的代码在 cmd2.Cmd 初始化之前运行
4
        super().__init__(*args, **kwargs)
5
        # 此处的代码在 cmd2.Cmd 初始化之后运行
6
        self.mysetting = "somevalue"
7
        self.settable.update({"mysetting": "short help message for mysetting"})

1
class MyMixin:
2
    def __init__(self, *args, **kwargs):
3
        # 此处的代码在 cmd2 初始化之前运行
4
        super().__init__(*args, **kwargs)
5
        # 此处的代码在 cmd2 初始化之后运行
6
        # 在这里注册你的钩子函数
7
        self.register_postparsing_hook(self.cmd2_mymixin_postparsing_hook)
8

9
    def cmd2_mymixin_postparsing_hook(self, data: cmd2.plugin.PostparsingData) -> cmd2.plugin.PostparsingData:
10
        """在解析用户输入之后、运行命令之前调用的方法"""
11
        self.poutput("in postparsing_hook")
12
        return data

概述#

本文介绍为 cmd2 应用编写单元测试或集成测试时的特殊注意事项。

运行 cmd2 的测试套件#

运行 make test 可执行测试套件，并附带覆盖率统计和 pytest-xdist 并行执行。默认的 -n auto 会根据可用 CPU 数自动选择工作进程数，并发运行相互独立的测试。同样的设置也适用于 uv run pytest 和 CI。

如果只想运行某个特定测试或进行交互式调试，可以禁用并行执行：

1
uv run pytest -n 0 tests/test_history.py
2
uv run pytest -n 0 --no-cov --pdb tests/test_history.py

也可以用 -n 4 之类的方式覆盖工作进程数。覆盖率会针对 cmd2 收集，并输出到终端、coverage.xml 和 htmlcov/。每次调用都会重新开始统计；如果希望合并多次运行的结果，请显式传入 --cov-append。

终端测试替身（test double）应当对光标位置查询作出应答，除非测试本身针对的就是缺失应答的情况。并发测试应使用事件同步，而不是任意的 sleep；当超时路径是被断言的对象时，应缩短仅用于测试的过期时间。对于依赖其他线程推进的等待，应保留足够宽裕的超时边界。

测试命令#

我们鼓励 cmd2 应用开发者参考 cmd2 tests 中的示例，了解如何对 cmd2 命令进行单元测试和集成测试。其中提供了多种辅助工具，可以捕获并返回 stdout、stderr 以及命令特有的结果数据。

Mock（模拟）#

如果你需要在 cmd2 应用中 Mock 任何对象——尤其是在 [cmd2.Cmd][] 或 [cmd2.CommandSet][] 的子类中——必须使用 Autospeccing、spec=True，或你所用 Mock 库提供的等价机制。

为了自动将函数加载为命令，cmd2 会执行大量反射调用来查找你在 cmd2 应用中定义的类的属性。许多 Mock 库会为请求的任何属性自动创建 Mock 对象，而不管该属性是否真实存在于被 Mock 的对象上。这种行为可能错误地引导 cmd2 把某个函数或属性当作它需要识别和处理的东西。为避免这种情况，你应该始终启用 Autospeccing 或 spec=True 来进行 Mock。如果没有开启 autospeccing，你的单元测试会失败，并出现类似下面的错误信息：

1
cmd2.exceptions.CommandSetRegistrationError: Subcommand
2
<MagicMock name='cmdloop.subcommand_name' id='4506146416'> is not valid: must be a string.
3
Received <class 'unittest.mock.MagicMock'> instead

示例#

1
def test_mocked_methods():
2
    with mock.patch.object(MockMethodApp, 'foo', spec=True):
3
        cli = MockMethodApp()

另一个示例使用 pytest-mock 提供的 mocker fixture：

1
def test_mocked_methods2(mocker):
2
    mock_cmdloop = mocker.patch("cmd2.Cmd.cmdloop", autospec=True)
3
    cli = cmd2.Cmd()
4
    cli.cmdloop()
5
    assert mock_cmdloop.call_count == 1

从 3.x 升级到 cmd2 4.x#

从 3.x 到 4.x 最大的变化是从 GNU Readline 库迁移到 prompt-toolkit 来实现 REPL（读取-求值-打印循环）。这一变更提供了 readline 的纯 Python 替代品，完全跨平台兼容，并在功能和可扩展性方面带来了显著增强。

从 2.x 升级到 cmd2 3.x#

关于 3.0.0 版本所有变更的详细信息，请参阅 CHANGELOG.md。

从 2.x 到 3.x 最大的变化是 cmd2 现在依赖 rich。相应地，cmd2 依靠 rich 在终端中进行精美的文本样式设置和格式化。因此，cmd2 中大量自定义代码被移除，其他内容也有所变动或改为基于 rich 实现。

升级到 3.x 时用户应注意的主要变化详述如下各小节。

1
from cmd2_ansi import ansi

1
from cmd2_table import table_creator

cmd2：构建强大的命令行解释器#

cmd2 是一个 Python 包，用于构建强大的命令行解释器（CLI）程序。它扩展了 Python 标准库的 cmd 模块。

cmd2 的基本用法与 cmd 模块完全相同。

1
from cmd2 import Cmd
2

3
class App(Cmd):
4
    # 自定义属性和方法
5
    pass

1
from cmd2 import Cmd
2

3
class App(Cmd):
4
    # 自定义属性和方法
5
    pass
6

7
app = App()
8
app.cmdloop()

cmd2 入门指南#

正在构建一个新的 REPL（读取-求值-打印循环） 或 命令行界面（CLI） 应用程序吗？

已经构建了一个使用 Python 标准库中 cmd 模块的应用程序，并希望通过很少的工作添加更多功能吗？

cmd2 是一个用于构建命令行应用程序的强大 Python 库。从这里开始，了解这个库是否适合你的需求。

1
$ pip install cmd2

1
$ sudo pip install <package_name>

1
$ pip install -U pip setuptools

1
C:\> python -m pip install -U pip setuptools

1
$ pip install cmd2

1
$ pip install -U git+https://github.com/python-cmd2/cmd2.git

1
$ sudo apt-get install python3-cmd2

1
pip install -U cmd2

1
$ pip uninstall cmd2

1
'cmd2>=3,<4'

1
from cmd2 import Cmd
2

3
class MyApp(Cmd):
4
    """一个简单的 cmd2 应用示例"""
5

6
    def do_greet(self, args):
7
        """问候用户"""
8
        if args:
9
            self.poutput(f"你好，{args}！")
10
        else:
11
            self.poutput("你好！")
12

13
    def do_quit(self, args):
14
        """退出应用程序"""
15
        return True
16

17
if __name__ == '__main__':
18
    app = MyApp()
19
    app.cmdloop()

从 cmd 升级到 cmd2#

如果你正在考虑将你的 cmd 应用程序升级为基于 cmd2，本节将帮助你决定它是否适合你的应用程序，并展示如何进行。

1
import cmd

1
import cmd2

1
class CmdLineApp(cmd.Cmd):

1
class CmdLineApp(cmd2.Cmd):

1
'cmd2>=3,<4'

入门示例#

以下是简单的 getting_started.py 示例应用程序的快速演练，它展示了 cmd2 的许多功能：

• 设置
• 命令
• 参数处理
• 生成输出
• 帮助
• 快捷方式
• 历史记录
• 底部工具栏

下面的动画演示了 cat、echo 和 intro 命令的实际运行效果：

如果你不想边看边输入，这里是完整的源代码（你可以点击展开，然后点击右上角的 Copy 按钮）：

1
#!/usr/bin/env python3
2
"""A simple example cmd2 application demonstrating many common features.
3

4
Features demonstrated include all of the following:
5
 1) Colorizing/stylizing output
6
 2) Using multiline commands
7
 3) Persistent history
8
 4) How to run an initialization script at startup
9
 5) How to group and categorize commands when displaying them in help
10
 6) Opting-in to using the ipy command to run an IPython shell
11
 7) Allowing access to your application in py and ipy
12
 8) Displaying an intro banner upon starting your application
13
 9) Using a custom prompt
14
10) How to make custom attributes settable at runtime.
15
11) Shortcuts for commands
16
12) Persistent bottom toolbar with realtime status updates
17
"""
18

19
import pathlib
20
import threading
21
import time
22

23
from prompt_toolkit.formatted_text import FormattedText
24
from rich.style import Style
25

26
import cmd2
27
from cmd2 import (
28
    Color,
29
    stylize,
30
)
31

32

33
class BasicApp(cmd2.Cmd):
34
    """Cmd2 application to demonstrate many common features."""
35

36
    DEFAULT_CATEGORY = "My Custom Commands"
37

38
    def __init__(self) -> None:
39
        """Initialize the cmd2 application."""
40
        # Startup script that defines a couple aliases for running shell commands
41
        alias_script = pathlib.Path(__file__).absolute().parent / ".cmd2rc"
42

43
        # Create a shortcut for one of our commands
44
        shortcuts = cmd2.DEFAULT_SHORTCUTS
45
        shortcuts.update({"&": "intro"})
46
        super().__init__(
47
            auto_suggest=True,
48
            bottom_toolbar=True,
49
            include_ipy=True,
50
            multiline_commands=["echo"],
51
            persistent_history_file="cmd2_history.dat",
52
            shortcuts=shortcuts,
53
            startup_script=str(alias_script),
54
        )
55

56
        # Spawn a background thread to refresh the bottom toolbar twice a second.
57
        # This is necessary because the toolbar contains a timestamp that we want to keep current.
58
        self._stop_refresh = False
59
        self._refresh_thread = threading.Thread(target=self._refresh_bottom_toolbar, daemon=True)
60
        self._refresh_thread.start()
61

62
        # Prints an intro banner once upon application startup
63
        self.intro = (
64
            stylize(
65
                "Welcome to cmd2!",
66
                style=Style(color=Color.GREEN1, bgcolor=Color.GRAY0, bold=True),
67
            )
68
            + " Note the full Unicode support:  😇 💩"
69
            + " and the persistent bottom bar with realtime status updates!"
70
        )
71

72
        # Show this as the prompt when asking for input
73
        self.prompt = "myapp> "
74

75
        # Used as prompt for multiline commands after the first line
76
        self.continuation_prompt = "... "
77

78
        # Allow access to your application in py and ipy via self
79
        self.self_in_py = True
80

81
        # Color to output text in with echo command
82
        self.foreground_color = Color.CYAN.value
83

84
        # Make echo_fg settable at runtime
85
        fg_colors = [c.value for c in Color]
86
        self.add_settable(
87
            cmd2.Settable(
88
                "foreground_color",
89
                str,
90
                "Foreground color to use with echo command",
91
                self,
92
                choices=fg_colors,
93
            )
94
        )
95

96
    def get_rprompt(self) -> str | FormattedText | None:
97
        current_working_directory = pathlib.Path.cwd()
98
        style = "bg:ansired fg:ansiwhite"
99
        text = f"cwd={current_working_directory}"
100
        return FormattedText([(style, text)])
101

102
    def _refresh_bottom_toolbar(self) -> None:
103
        """Background thread target to refresh the bottom toolbar.
104

105
        This is a toy example to show how the bottom toolbar can be used to display
106
        realtime status updates in an otherwise line-oriented command interpreter.
107
        """
108
        import contextlib
109

110
        from prompt_toolkit.application.current import get_app
111

112
        while not self._stop_refresh:
113
            with contextlib.suppress(Exception):
114
                # get_app() will return the currently running prompt-toolkit application
115
                app = get_app()
116
                if app:
117
                    app.invalidate()
118
            time.sleep(0.5)
119

120
    def do_intro(self, _: cmd2.Statement) -> None:
121
        """Display the intro banner."""
122
        self.poutput(self.intro)
123

124
    def do_echo(self, arg: cmd2.Statement) -> None:
125
        """Multiline command."""
126
        self.poutput(
127
            stylize(
128
                arg,
129
                style=Style(color=self.foreground_color),
130
            )
131
        )
132

133

134
if __name__ == "__main__":
135
    import sys
136

137
    app = BasicApp()
138
    sys.exit(app.cmdloop())

1
class BasicApp(cmd2.Cmd):
2
    """展示许多常见功能的 Cmd2 应用程序。"""

1
if __name__ == "__main__":
2
    app = BasicApp()
3
    sys.exit(app.cmdloop())

1
$ uv run python examples/getting_started.py

1
# echo 命令输出文本所用的颜色
2
self.foreground_color = Color.CYAN.value
3

4
# 使 foreground_color 可在运行时设置
5
fg_colors = [c.value for c in Color]
6
self.add_settable(
7
    cmd2.Settable(
8
        "foreground_color",
9
        str,
10
        Text.assemble(
11
            "echo 命令使用的前景色 ",
12
            "（选项： ",
13
            Text("Green", Style(color=Color.GREEN)),
14
            ", ",
15
            Text("Red", Style(color=Color.RED)),
16
            ", ",
17
            Text("Blue", Style(color=Color.BLUE)),
18
            ", ...）",
19
        ),
20
        self,
21
        choices=fg_colors,
22
    )
23
)

1
myapp> set foreground_color
2
myapp> set foreground_color red

1
@cmd2.with_annotated
2
def do_cat(
3
    self,
4
    path: pathlib.Path,  # 必需的位置参数，带类型注解，按 Tab 自动补全文件系统路径
5
    numbered: Annotated[  # 可选的标志参数，带类型注解、默认值和帮助文本
6
        bool, Option("-n", "--number", help_text="在每行前加上其编号")
7
    ] = False,
8
) -> None:
9
    """打印文件内容。`path` 会自动以 Tab 补全文件系统路径。
10

11
    试试：
12
        cat <TAB>              # 路径会补全文件/目录 -- 无需额外连接补全器
13
        cat notes.txt
14
        cat notes.txt -n       # -n / --number，通过 Option 元数据声明
15
        cat notes.txt --no-number
16
    """
17
    text = path.read_text()
18
    lines = text.splitlines()
19
    if numbered:
20
        numbered_lines = []
21
        for index, line in enumerate(lines, start=1):
22
            numbered_lines.append(f"{index}: {line}")
23
        self.ppaged("\n".join(numbered_lines))
24
    else:
25
        # 使用分页器打印内容
26
        self.ppaged(path.read_text())