如何使用Python argparse实现支持1-2个位置参数的CLI命令？

需求 #

需要用Python3的argparse实现以下格式的CLI命令：

python main.py virtual_machine deploy --name "chetan"
python main.py virtual_machine power-on
python main.py image --list

错误尝试代码 #

我尝试了如下代码，但无法正常运行：

parser = argparse.ArgumentParser(description="VM Services")

subparsers = parser.add_subparsers(help="Subcommands")

parser.add_argument('virtual_machine', nargs=2, action=TwoPositionalAction, help="Virtual machine operations")
args = parser.parse_args()

if args.virtual_machine[1] == "deploy":
    vm_parser = subparsers.add_parser("deploy", help="Virtual machine deploy")
    vm_parser .add_argument("--name", required=False, help="name of the vm")
    vm_parser .set_defaults(func=two_parser_command)

运行错误 #

执行python3 main.py virtual_machine deploy时得到错误输出：

usage: main.py [-h] {} ... virtual_machine virtual_machine
main.py: error: invalid choice: 'virtual_machine' (choose from )

问题原因 #

之前的代码混淆了位置参数与子解析器的核心逻辑：

1. 直接给主解析器添加virtual_machine位置参数，同时又创建子解析器，导致参数规则冲突。
2. 解析器初始化顺序错误，未配置完所有子命令就调用parse_args()，后续添加的子命令无法被识别。

正确实现方案 #

通过嵌套子解析器实现多级命令结构：一级子命令处理virtual_machine和image，再为virtual_machine配置二级子命令处理deploy、power-on：

import argparse

# 定义各命令的处理函数
def deploy_vm(args):
    print(f"开始部署虚拟机，名称：{args.name}")

def power_on_vm(args):
    print("启动虚拟机")

def list_images(args):
    print("列出所有镜像")

def main():
    # 主解析器
    parser = argparse.ArgumentParser(description="VM 服务管理工具")
    # 一级子解析器：处理virtual_machine和image命令
    main_subparsers = parser.add_subparsers(dest="main_cmd", required=True, help="可用主命令")

    # --------------------------
    # 配置virtual_machine子命令
    # --------------------------
    vm_parser = main_subparsers.add_parser("virtual_machine", help="虚拟机相关操作")
    # 二级子解析器：处理virtual_machine下的deploy、power-on
    vm_subparsers = vm_parser.add_subparsers(dest="vm_cmd", required=True, help="虚拟机操作子命令")

    # deploy子命令配置
    deploy_parser = vm_subparsers.add_parser("deploy", help="部署新虚拟机")
    deploy_parser.add_argument("--name", required=True, help="虚拟机名称")
    deploy_parser.set_defaults(func=deploy_vm)

    # power-on子命令配置
    power_on_parser = vm_subparsers.add_parser("power-on", help="启动虚拟机")
    power_on_parser.set_defaults(func=power_on_vm)

    # --------------------------
    # 配置image子命令
    # --------------------------
    image_parser = main_subparsers.add_parser("image", help="镜像相关操作")
    image_parser.add_argument("--list", action="store_true", required=True, help="列出所有镜像")
    image_parser.set_defaults(func=list_images)

    # 解析参数并执行对应函数
    args = parser.parse_args()
    args.func(args)

if __name__ == "__main__":
    main()

测试验证 #

执行以下命令可正常运行：

• 部署虚拟机：python main.py virtual_machine deploy --name "chetan"
• 启动虚拟机：python main.py virtual_machine power-on
• 列出镜像：python main.py image --list

内容的提问来源于stack exchange，提问作者Chetan