基本用法#

没有默认值的参数成为位置参数。有默认值的参数成为 --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 分享反馈和边缘案例，以便在该功能结束实验性状态之前把行为固定下来。